MMHunterCoach — 射擊獵循環教練（WoW Retail）

Marksmanship Hunter rotation coach addon for World of Warcraft (Retail / 12.x).

In-game UI shows the next ability icon based on:

1. WCL top-parser priority research (Dark Ranger ST on Vorasius; Sentinel ST on Dummy Dome)
2. Live game state: cooldowns, IsSpellUsable, cast locks, Precise Shots aura, hero talent detection

Status: Playable prototype with known bugs. Uploaded so work can continue on any machine via Grok Build / GitHub. Prefer reading this README + docs/CONTEXT.md + CHANGELOG.md before editing.

---

Install

1. Download release zip or clone this repo.

2. Copy the inner folder MMHunterCoach/ into:

   World of Warcraft\_retail_\Interface\AddOns\MMHunterCoach\
   

3. Ensure these files exist:

   MMHunterCoach/MMHunterCoach.toc
   MMHunterCoach/Core.lua
   

4. Restart WoW or /reload, enable the addon on the character select screen.

5. Chat should print something like: MMHunterCoach v1.5.1 已載入

6. Icon frame shows version string (e.g. v1.5.1) at the bottom.

Slash commands

Command	Action
/mmhc	Help
/mmhc show	Force show UI (center, unlock filters)
/mmhc unlock / lock	Drag position
/mmhc hero	Print detected hero talent + priority
/mmhc debug	Open copyable debug window + write lastDebug to SavedVariables
/mmhc dump	Write debug to SavedVariables only
/mmhc combat	Toggle combat-only display
/mmhc mm	Toggle MM-only filter
/mmhc size 80	Icon size
/mmhc reset	Reset position/settings

Debug for remote AI / other PC

1. In game: /mmhc debug (optional if you only need errors)
2. /reload (flushes SavedVariables to disk)
3. Ask agent: 「讀 debug」

SavedVariables path (Windows, example account):

_retail_\WTF\Account\<ACCOUNT>\SavedVariables\MMHunterCoach.lua

Fields:

• lastDebug — last /mmhc debug snapshot
• lastError / errorLog — combat UI errors auto-logged (v1.4.5+)

---

What this addon is trying to do

Goal	Approach
Show next cast	Priority list + CanPress
Dark Ranger ST	Priority driven by WCL Vorasius MM rankings (zone 46, encounter 3177)
Sentinel ST	Older Dummy Dome / Sinister Single style list with Moonlight Chakram
Detect hero	Black Arrow known → Dark Ranger; else Chakram known → Sentinel
Never suggest unlearned	Strict SpellKnown (not “has cooldown table”)
Never Steady Shot	Explicitly excluded from Recommend (v1.5+)
Precise-only Arcane	Real aura via GetPlayerAuraBySpellID when possible
Black Arrow CD	Manual lock ~14s after cast; early unlock only if usable again (proc)
Trueshot on CD	Must not recommend Trueshot while buff/lock/API CD (TrueshotUnavailable)
WoW 12.x secrets	Do not compare secret duration/startTime/spellId fields

---

Priority lists (current)

Dark Ranger (黑蝕箭 / Black Arrow)

Trueshot > Black Arrow > Rapid Fire > Wailing Arrow > Volley
  > Explosive Shot (if known) > Kill Shot > Aimed Shot
  > Arcane Shot (Precise only)

WCL notes (Vorasius, partition 3, MM top parsers): Black Arrow ~37–39% damage share; Explosive often untalented.

Sentinel (月光環刃)

Trueshot > Rapid Fire > Explosive Shot > Volley > Chakram
  > Kill Shot > Aimed Shot > Arcane Shot (Precise only)

If nothing pressable

Show 「等待：<next ability>」 with icon + cooldown swipe — not blank, not Steady Shot.

---

Project layout

MMHunterCoach/                 ← GitHub repo root
  README.md                    ← this file
  CHANGELOG.md                 ← version history
  RELEASE.md                   ← release notes template / latest release body
  docs/
    CONTEXT.md                 ← long-form context for Grok Build / future agents
    KNOWN_ISSUES.md            ← bug list and investigation notes
    WCL_RESEARCH.md            ← ranking sources and parse summary
  MMHunterCoach/               ← folder to copy into AddOns
    MMHunterCoach.toc
    Core.lua                   ← all logic (single-file addon)
  .gitignore

---

Development notes (for Grok Build)

Environment where this was developed

• OS: Windows
• WoW: Retail, Interface often 120100 / 120007
• Character used for testing: TW realm, MM Hunter Dark Ranger
• Black Arrow spell ID on this client: 466930 (name: 黑蝕箭)
• WCL API was used separately (client credentials in user env vars only — never commit secrets)

Coding constraints (WoW 12.x)

• Secret values: comparing duration, startTime, many aura fields will throw and break the UI.
• Prefer: isActive == true (boolean), IsSpellUsable, cast-time locks, GetPlayerAuraBySpellID presence checks only.
• SpellKnown: use IsPlayerSpell / spellbook APIs — never “has GetSpellCooldown table”.
• Do not put Black Arrow IDs into Chakram candidate lists (collision bug at 466930).

How to continue work

1. Clone repo on the new machine.
2. Copy MMHunterCoach/ into the local WoW AddOns path.
3. Read docs/CONTEXT.md + docs/KNOWN_ISSUES.md.
4. Reproduce → /mmhc debug → /reload → read SavedVariables or BugGrabber.
5. Patch Core.lua, bump TOC version, test, update CHANGELOG.

Related local paths (original machine only)

D:\World of Warcraft\_retail_\Interface\AddOns\MMHunterCoach\
D:\Downloads\wcl-api\          ← WCL JSON dumps / analysis scripts (not in this repo)
D:\Downloads\wcl-api\mm-rotation-coach\  ← early web coach + copies (legacy)

WCL analysis artifacts are not required to run the addon; they informed priorities.

---

License

Personal / educational use. No warranty. Warcraft Logs and Blizzard trademarks belong to their owners.

---

Author

Maintained ad-hoc with Grok Build (xAI). GitHub: see repository owner.