# HLYqol

Keep this file and `CLAUDE.md` synchronized. When project rules, architecture notes, modules, assets, or workflow guidance change, update both files in the same change.

WoW addon (TWW, Interface 120005). Author: HLYSHT. Version: 1.6. SavedVariables: `HLYQoLDB`.

## Structure

```
Initialize.lua          addon table + HLY AceAddon object
Settings/Defaults.lua   addon.P defaults (all module defaults here)
Core/Init.lua           OnInitialize, OnEnable, shared utilities
Options/Options.lua     AceConfig-3.0 options UI
Modules/                one file per feature
Libs/                   Ace3 + LibSharedMedia (vendored, do not edit)
Assets/                 sounds + textures
```

Load order: Initialize -> Defaults -> Modules -> Options -> Core/Init.

## Workflow

After addon changes, copy the working tree to `C:\World of Warcraft\_retail_\Interface\AddOns\HLYqol`. Exclude Git and AI-agent files/folders: `.git`, `.gitignore`, `.agents`, `.claude`, `AGENTS.md`, `CLAUDE.md`, and `skills-lock.json`.

## Architecture

- `Initialize.lua` creates `addon.HLY` via `AceAddon-3.0:NewAddon`
- All modules grab `local HLY = addon.HLY` and add methods to it
- DB: `AceDB-3.0`, profile at `self.db`, defaults from `addon.P.hlyqol`
- Events: `HLY:RegisterEvent(...)` / `HLY:SafeRegisterEvent(...)`
- Options: `AceConfig-3.0` + `AceConfigDialog-3.0`, opens via `/hlyqol`

## Modules

| Module | What it does |
|---|---|
| UpgradeTrack | Shows upgrade track label (Explorer/Adventurer/Veteran/Champion/Hero/Mythic + ratio) on bag, character, inspect slot buttons |
| BoEWuE | Shows BoE/WuE badge on item slots |
| CompareStats | Stat comparison overlay on character/inspect frame hover |
| AutoAccept | Auto-clicks LFG role check popup (`LFG_ROLE_CHECK_SHOW/UPDATE`) |
| JoinReminder | Screen + chat message when joining a group |
| DeathAlert | Role-specific sound when group member dies (Tank/Healer/DPS) |
| TrinketAlert | Sound alert on tracked trinket cooldowns |
| Loot | Auto-greed on decorative/non-upgrade loot |
| LustAlert | Detects Bloodlust/Heroism via Sated debuff (IDs hardcoded), plays sound, optional countdown timer |
| GearCheck | Detects PvP gear via tooltip scan, shows screen alert + sound |
| HLYstats | Movable frame: ilvl, mainstat, crit, haste, mastery, vers, leech, avoidance, speed |
| MinimapButton | Minimap icon, angle stored in db |
| FrenchConnection | Joke module: shows baguette + plays "ohoho" when French player joins |
| HLYmarker | Marks first assigned tank in normal parties with a raid target icon; auto-creates macro `HLYmarkerTank`; movable reminder frame when tank is unmarked |
| Statistics | Always-on account-wide statistics; shows total played time, played time for all recorded classes, character gold, Warbank gold, and total gold |

## Key Utilities (Core/Init.lua)

- `HLY:SafeCall(fn, ...)` - pcall wrapper, returns nil on error
- `HLY:SafeNumber(val, fallback)` - safe tonumber
- `HLY:ApplyFont(text, name, size, outline)` - LSM font with fallback chain
- `HLY:ApplyBackdrop(frame)` - dark backdrop, only applied once (`hlyBackdropApplied` guard)
- `HLY:ShortValue(n, decimals)` - formats large numbers as `1.2k` / `3.4m`
- `HLY:GetClassColor(classFile)` - returns `RAID_CLASS_COLORS` entry
- `HLY:GetUnitItemLevel(unit)` - player uses `C_PaperDollInfo.GetItemLevel`, others `GetInspectItemLevel`, fallback manual slot scan
- `HLY:ForEachBagSlot(cb)` - iterates all bag buttons across vanilla/ElvUI/Bagnon/Baganator
- `HLY:QueueBagRefresh()` - debounced (0.05s) bag refresh

## Bag Compatibility

Supported bag addons: default UI (`ContainerFrameCombinedBags`, `ContainerFrame1-20`, `BankPanel`, `AccountBankPanel`), ElvUI, Bagnon, Baganator. Detection in `HLY:GetBagRoots()`.

## Settings Pattern

New module default -> add key to `Settings/Defaults.lua` under `addon.P.hlyqol`.
Read in module: `self.db.<module>.<key>` (AceDB copies profile from defaults).
Guard pattern: `if not self.db or not self.db.foo or not self.db.foo.enabled then return end`

## Libraries

All vendored under `Libs/`. Do not modify.
- `LibStub`, `CallbackHandler-1.0`
- `AceAddon-3.0`, `AceConsole-3.0`, `AceEvent-3.0`, `AceHook-3.0`
- `AceDB-3.0`, `AceGUI-3.0`, `AceConfig-3.0`
- `LibSharedMedia-3.0`, `AceGUI-3.0-SharedMediaWidgets`

## Assets

| File | Used by |
|---|---|
| `Assets/LustAlert/drop_it_short.ogg` | LustAlert default sound |
| `Assets/LustAlert/drop_it_long.ogg` | LustAlert alt sound |
| `Assets/baguette.tga` | FrenchConnection |
| `Assets/ohoho.mp3` | FrenchConnection |
| `Assets/moment.mp3` | GearCheck default sound |
| `Assets/spongebob-fail.mp3`, others | selectable alert sounds |
| `hlysht.tga` | addon icon |
