# [AH] Arena Helper

**Version:** 1.0.0  
**Interface:** 12.0.1 (WoW Midnight)  
**Author:** AH Dev  

---

## What It Does

[AH] Arena Helper lets you create **interactive macros that update themselves automatically** — out of combat — based on live arena enemy detection.

You create a macro definition once, drop the in-game macro on your action bar, and the addon keeps it up-to-date with the correct target name as you detect the enemy team.

---

## Installation

1. Drop the `ArenaHelper` folder into:
   ```
   World of Warcraft/_retail_/Interface/AddOns/
   ```
2. Inside `ArenaHelper/Libs/` add the following libraries (standard Ace3 libraries):
   - `LibStub`
   - `CallbackHandler-1.0`
   - `LibDataBroker-1.1`
   - `LibDBIcon-1.0`
   - `AceGUI-3.0`
   - `AceConfig-3.0`

   These can be downloaded from CurseForge or the Ace3 SVN repository. The TOC lists them as `OptionalDeps` so the addon will still load without them (the minimap button will simply not appear if LibDBIcon is missing).

3. Launch WoW and enable **Arena Helper** in the AddOn list.

---

## Quick Start

| Command | Action |
|---|---|
| `/ah` | Open / Close the main window |
| `/ah new` | Open the Macro Editor to create a new macro |
| `/ah update` | Force re-scan and update all macros NOW |
| `/ah status` | Print current arena detection + macro list |
| `/ah announce on/off` | Toggle /say announce when target changes |
| `/ah help` | Full command list |

---

## How Macros Work

### Step 1 — Create a Macro Definition

Click **+ New Macro** in the UI (or `/ah new`).

Fill in:
- **Spell Name** — e.g. `Hex`
- **Macro Name** — max 16 chars, e.g. `AH_Hex`
- **Automation Type** — pick from the dropdown (see below)
- **Base Macro Body** — the macro text. The target/focus line is added automatically.

### Step 2 — Add it to Your Action Bar

Open the WoW **Macros** panel (default: type `/macro`). You'll find the macro named `AH_Hex` (or whatever you chose). Drag it to your action bar.

### Step 3 — Enable Automation

Toggle the switch in the [AH] UI to **ON** for that macro. Each time you leave combat (or enter a new arena), the addon rewrites the macro with the correct target name.

---

## Automation Types

| Type | Description |
|---|---|
| **CC Macro → Healer name** | Writes `/target HealerName` before your CC spell. Perfect for Hex, Polymorph, Fear on the healer. |
| **Target enemy Healer** | Detects healer by spec ID and targets them. |
| **Target enemy Melee DPS** | Detects the melee DPS and targets them. |
| **Target enemy Caster DPS** | Detects ranged/caster DPS and targets them. |
| **Target enemy with lowest HP%** | Always targets whoever is lowest HP on the enemy team. |
| **Target ally that needs dispel** | Targets your teammate with the most debuffs. |
| **Focus enemy Healer** | Sets healer as Focus (`/focus HealerName`). Great for interrupt tracking. |
| **Focus enemy Melee** | Sets melee as Focus. |
| **Focus enemy Caster** | Sets caster as Focus. |
| **Mouseover → fallback to target** | Writes `[@mouseover,help,nodead][@target]` syntax. Great for heals/buffs. |
| **Interrupt macro → Focus** | Writes `[@focus,exists,harm][@target]` interrupt macro. |
| **No automation (clone current)** | Keeps the macro as-is with no auto-targeting. |
| **Custom expression** | You write your own `/target <expr>` string. |

---

## Announce System

When **Announce changes in /say** is checked (or `/ah announce on`), every time a macro's target changes the addon sends a message to /say:

```
[AH] MacroHEX Target set to JohnSmith
```

This is visible to your teammates in arena and helps coordinate swaps.

---

## Healer Detection

Detection works in two layers:
1. **Spec ID** — `GetArenaOpponentSpec(i)` returns the spec ID of arena opponents after the prep phase. All known healer spec IDs (Holy Paladin, Resto Druid, Mistweaver Monk, Disc/Holy Priest, Resto Shaman, Preservation Evoker) are mapped.
2. **Class fallback** — If spec data isn't available yet, the addon falls back to class-based heuristics.

Scans run every 0.5s while in an arena and are disabled outside of arena instances to save performance.

---

## Macro Slots

The addon creates **global** (account-wide) macros. WoW allows 120 global macro slots. If you hit the cap, the addon will print an error.

---

## Example Macro Outputs

**Hex on Healer (CC_HEALER):**
```
#showtooltip Hex
/target JohnSmith
/cast Hex
```

**Interrupt on Focus (INTERRUPT_FOCUS):**
```
#showtooltip Kick
/cast [@focus,exists,harm][@target] Kick
```

**Dispel on lowest-debuff ally (TARGET_DISPEL):**
```
#showtooltip Cleanse
/target AllyName
/cast Cleanse
```

**Mouseover heal with fallback (MOUSEOVER_FRIENDLY):**
```
#showtooltip Holy Light
/cast [@mouseover,help,nodead][@target] Holy Light
```

---

## File Structure

```
ArenaHelper/
├── ArenaHelper.toc
├── ArenaHelper.lua          ← Main init + slash commands
├── Core/
│   ├── Constants.lua        ← All enums, labels, defaults
│   ├── Utils.lua            ← Helpers (print, announce, etc.)
│   ├── ArenaTracker.lua     ← Enemy/ally detection engine
│   ├── MacroEngine.lua      ← Macro builder & writer
│   └── AutomationRules.lua  ← Per-automation resolvers
├── UI/
│   ├── MinimapButton.lua    ← LibDBIcon minimap button
│   ├── MainFrame.lua        ← Main dashboard window
│   └── MacroEditor.lua      ← Create/edit macro popup
└── Libs/                    ← (add your Ace3 libs here)
    ├── LibStub/
    ├── CallbackHandler-1.0/
    ├── LibDataBroker-1.1/
    ├── LibDBIcon-1.0/
    ├── AceGUI-3.0/
    └── AceConfig-3.0/
```
