KeyStoneMastery

# KeyStoneMastery
KeyStoneMastery is a World of Warcraft Retail Mythic+ addon that does three things:
1. Replies to M+ chat requests (`!key`, `!score`, `!best`). 2. Tracks your key and group/guild key data in a `/ksm` dashboard. 3. Shows a live Mythic+ run overlay with timer/objectives/deaths/Enemy Forces.
Target client/API: Retail 12.0.5 (compatible with 12.0.1+).
## Exactly What The Addon Does
### 1) Chat responses for Mythic+ requests
- Responds to `!key` / `!keys` with your current keystone link (or fallback text if link APIs are unavailable). - Responds to `!score` / `!scores` with your Mythic+ score. - Responds to `!best` with your best weekly/season run summary. - Watches guild chat for keystone-style messages and uses them to update guild key cache. - Defers outgoing chat messages during combat and sends them after combat ends.
### 2) `/ksm` dashboard for key visibility
- `Main` tab shows your key/rating context plus seasonal summary data. - `Party` tab shows current party member key snapshots and score context. - `Guild` tab shows known guild keys with pagination/filtering and refresh requests. - `Recents` tab shows previously seen players with known keys. - `Warband` tab shows your own character key snapshots. - Integrates incoming key data from KeyStoneMastery sync messages and supported external payload formats.
### 3) Live Mythic+ run overlay
- Displays dungeon header, affixes, run timer, chest breakpoints, objectives, death tracking, and Enemy Forces progress. - Can be enabled/disabled, shown/hidden, moved, locked, and scaled with slash commands. - Supports falling back to Blizzard UI behavior when the custom overlay is disabled.
### 4) Keystone workflow helpers
- Announces newly changed keys to party when your key changes. - Auto-slots your keystone when the Font of Power receptacle opens.
### 5) Name handling and storage behavior
- Stores names using incoming authoritative data. - Does not synthesize local realm suffixes. - Preserves cross-realm player identifiers when they are provided.
### 6) Guild tab inclusion rules (current)
- Shows max-level guild characters only (Retail cap-aware). - Shows rows when known key data is available (map + level). - Deduplicates same-character variants (short/full realm names) and prefers richer roster/GUID-backed data. - Keeps online/offline state resilient to roster churn while updating quickly.
### 7) Guild refresh behavior
- `Request Guild Keys` performs an immediate refresh and short follow-up pulls to catch members whose addons initialize shortly after login. - Inbound updates are accepted from KeyStoneMastery sync messages, AstralKeys payloads, and Details/OpenRaid payloads. - A guild member may still not appear if they are below max level, have no known key to share, or do not have a compatible key-sharing addon payload active.
## Commands
### Chat triggers
- `!key` / `!keys` - `!score` / `!scores` - `!best`
### Slash commands
- `/km` or `/keymaster`: addon help and status entry point. - `/km settings`: open settings panel. - `/km status`: show UI state. - `/km ui on` / `/km ui off` / `/km ui restore`. - `/km unlock` / `/km lock`. - `/km hide` / `/km show`. - `/km reset`. - `/km scale <0.70-1.50>`. - `/km deaths`. - `/km criteria`. - `/km forces`. - `/ksm`: open/toggle dashboard. - `/ksm show` / `/ksm hide`. - `/ksm main` / `/ksm party` / `/ksm guild`. - `/ksm refresh`.
## Install
1. Download the latest release zip. 2. Extract the `KeyMaster` folder into:
```text World of Warcraft/_retail_/Interface/AddOns/ ```
3. Launch WoW and enable KeyStoneMastery in the addon list. 4. Run `/reload`.