Main.png
Party.png
Guild.png
Recents.png
Warband.png
Description
# 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`.
The KeyStoneMastery Team
