# CritTracker – Entwickler- & Agenten-Leitfaden (Developer & Agent Guide)

Dieses Dokument dient als technische Referenz für Entwickler und KI-Agenten, die das Addon **CritTracker** nachvollziehen, erweitern oder in einer vergleichbaren Umgebung reproduzieren möchten.

---

## 1. System- & Zielumgebung

- **Spiel / Client:** World of Warcraft - Forever (Beta)
- **Engine-Basis:** WoW Retail 12.x Engine
- **TOC Interface-Version:** `16001` (`## Interface: 16001`)
- **Addon-Verzeichnis:** `Interface/AddOns/CritTracker/`
- **Slash-Befehle:** `/ctr`, `/crittracker` (Hinweis: `/ct` wurde bewusst vermieden, um Namenskonflikte mit anderen Addons wie CTMod auszuschließen).

---

## 2. Projektstruktur

```
CritTracker/
├── CritTracker.toc          # Addon-Manifest für Interface 16001
├── Localization.lua         # Lokalisierungs-Strings (deDE und enUS)
├── CritTracker.lua          # Core Engine: Event-Handling, Combat-Log, Cooldown, Reset
├── Config.lua               # UI: 2-Spalten Einstellungsmenü (Modern Settings API + Standalone)
├── README.md                # Benutzerdokumentation
├── AGENT_GUIDE.md           # Diese technische Spezifikation für Agenten
└── sounds/
    ├── German/              # Deutsche Audio-Dateien
    │   ├── crit1.mp3 .. crit4.mp3
    │   ├── heal1.mp3 .. heal4.mp3
    │   └── low.mp3
    └── English/             # Englische Audio-Dateien
        ├── crit1.mp3 .. crit4.mp3
        ├── heal1.mp3 .. heal4.mp3
        └── low.mp3
```

> [!IMPORTANT]
> **Audio-Asset-Korrektur:** Die ursprüngliche Datei `sounds/English/low.mp3` war eine fehlerhafte 1.024-Byte-Null-Datei (Stille). Sie wurde durch die funktionierende Audiodatei aus `sounds/German/low.mp3` ersetzt, damit englische Clients nicht stumm bleiben.

---

## 3. Datenarchitektur (`SavedVariables: CritTrackerDB`)

Die Daten werden in `CritTrackerDB` gespeichert. Die Konfiguration ist accountweit geteilt, während die Rekorde strikt pro Charakter und Realm isoliert sind.

```lua
CritTrackerDB = {
    settings = {
        enabled = true,            -- Addon an/aus
        enableChat = true,         -- Lokale Chat-Ausgabe an/aus
        enableSound = true,        -- Soundausgabe an/aus
        enableLowCrit = true,      -- Erkennung schwacher Crits an/aus
        lowThreshold = 30,         -- Grenzwert in Prozent (Standard: 30%)
        cooldown = 5,              -- Cooldown in Sekunden (1-30s, Schieberegler)
        damageSound = "crit1",     -- "crit1", "crit2", "crit3", "crit4", "none"
        healSound = "heal1",       -- "heal1", "heal2", "heal3", "heal4", "none"
        lowSound = "low",          -- "low", "none"
        soundChannel = "Master",   -- "Master", "Dialog", "SFX"
        language = "auto",         -- "auto", "German", "English"
        announceMode = "all",      -- "all" oder "records_only"
    },
    chars = {
        ["CharakterName - RealmName"] = {
            level = 80,
            maxDamage = 152000,
            maxDamageSpell = "Feuerball",
            maxHeal = 89000,
            maxHealSpell = "Lichtblitz",
        }
    }
}
```

---

## 4. Logik- & Entscheidungsfluss (Core Engine)

### 4.1. Combat Log Filterung (`COMBAT_LOG_EVENT_UNFILTERED`)

Die Engine verwendet `CombatLogGetCurrentEventInfo()` mit folgenden Regeln:

1. **Source-Check:** Nur Events mit `sourceGUID == UnitGUID("player")` werden verarbeitet (Spieler-Treffer).
2. **Sub-Events:**
   - **Schaden:** `SWING_DAMAGE`, `SPELL_DAMAGE`, `RANGE_DAMAGE`, `SPELL_PERIODIC_DAMAGE`, `SPELL_BUILDING_DAMAGE`.
     - Effektiver Schaden: `amount + absorbed` (Absorbe werden dem Treffer zugerechnet).
     - Bedingung: `critical == true`.
   - **Heilung:** `SPELL_HEAL`, `SPELL_PERIODIC_HEAL`, `SPELL_BUILDING_HEAL`.
     - Effektive Heilung: `amount + overhealing` (Overheal wird berücksichtigt, damit große Heiler-Crits bei voller HP nicht fälschlich als "Low Crit" eingestuft werden).
     - Bedingung: `critical == true`.

### 4.2. Ablaufdiagramm der Crit-Verarbeitung

```mermaid
flowchart TD
    A["Combat Log Crit Event (Player)"] --> B{"Addon aktiviert?"}
    B -- Nein --> End[Abbruch]
    B -- Ja --> C["Hole bisherigen Rekord (Schaden/Heilung)"]
    
    C --> D{"amount > currentRecord?"}
    D -- Ja --> E["Neuer Rekord! Aktualisiere charData (maxRecord = amount)"]
    D -- Nein --> F{"enableLowCrit UND currentRecord > 0 UND amount <= (currentRecord * threshold)?"}
    
    F -- Ja --> G["Als Low-Crit markieren (Sound: low.mp3)"]
    F -- Nein --> H["Als normaler Crit markieren (Sound: critX / healX)"]
    
    E --> I{"GetTime() - lastOutputTime < cooldown?"}
    G --> I
    H --> I
    
    I -- Ja (im Cooldown) --> J["Ausgabe unterdrückt (Anti-Spam)"]
    I -- Nein (Cooldown frei) --> K["lastOutputTime = GetTime()"]
    
    K --> L["PlaySoundFile(soundPath, soundChannel)"]
    K --> M["DEFAULT_CHAT_FRAME:AddMessage(formatierte Nachricht)"]
```

---

## 5. Kernfunktionen im Detail

### 5.1. Level-Up Reset
- **Event:** `PLAYER_LEVEL_UP`
- **Sicherheits-Check:** Beim Login (`PLAYER_LOGIN`) wird geprüft, ob `UnitLevel("player") > charData.level`. Falls der Spieler offline oder bei deaktiviertem Addon aufgestiegen ist, wird der Reset nachträglich durchgeführt.
- **Wirkung:** `maxDamage = 0`, `maxHeal = 0`, `level = newLevel`.
- **Chat-Meldung:** Gibt lokalen Hinweis aus: `[CritTracker] Stufenaufstieg! Krit-Rekorde wurden auf 0 zurückgesetzt.`

### 5.2. Cooldown für Audio- & Chat-Ausgabe
- Einstellbar von **1 bis 30 Sekunden** über den Schieberegler in den Optionen.
- **Wichtig für Agenten:** Der Cooldown blockiert **nicht** das Speichern neuer Rekorde! Trifft ein Spieler während des Cooldowns einen neuen Rekordwert, wird `charData.maxDamage` sofort aktualisiert. Lediglich die Soundwiedergabe und der Textchat werden gedrosselt, um Tonaussetzer und Chatüberflutung zu verhindern.

### 5.3. Lokale Chat-Ausgabe
- Alle Chat-Meldungen verwenden `DEFAULT_CHAT_FRAME:AddMessage(msg)` oder `print(msg)`.
- Es werden **keine** öffentlichen Chatkanäle (`SAY`, `PARTY`, `RAID`) angesprochen. Die Ausgabe ist garantiert nur für den lokalen Client sichtbar.
- Abschaltbar über `CritTrackerDB.settings.enableChat`.

### 5.4. Zweisprachigkeit (Localization Architecture)
- Lokalisierungs-Proxy via Lua-Metatable in `CritTracker.L`:
  ```lua
  CritTracker.L = setmetatable({}, {
      __index = function(_, key)
          local lang = CritTracker:GetActiveLanguage()
          local locKey = (lang == "German") and "deDE" or "enUS"
          return addonTable.Locales[locKey][key] or addonTable.Locales["enUS"][key] or key
      end
  })
  ```
- **Sprachauflösung:**
  - `auto`: Prüft `GetLocale()`. Bei `deDE` wird Deutsch gewählt, bei allen anderen Sprachen Englisch.
  - `German`: Erzwingt Deutsch.
  - `English`: Erzwingt Englisch.
- **Audio-Pfad:**
  `Interface\AddOns\CritTracker\sounds\<Language>\<SoundKey>.mp3`

---

## 6. UI-Architektur (`Config.lua`)

Das Einstellungsmenü ist für maximale Kompatibilität mit modernem Retail WoW (Dragonflight, War Within, Midnight / 12.x) ausgelegt:

1. **Modern Settings API:**
   - Registrierung über `Settings.RegisterCanvasLayoutCategory(panel, "CritTracker")` und `Settings.RegisterAddOnCategory(category)`.
   - Öffnen über `Settings.OpenToCategory(category:GetID())`.
2. **Standalone-Fallback:**
   - Sollte das Settings-Menü im Betastatus nicht ansprechbar sein oder während des Kampfes aufgerufen werden, öffnet sich das Panel automatisch als bewegliches Standalone-Fenster (`BackdropTemplateMixin`, Close-Button, Dragging).
3. **2-Spalten-Layout:**
   - **Linke Spalte:** Checkboxen (Addon, Chat, Sound, Low-Crit), Cooldown-Slider (1–30s), Schwellenwert-Slider (5–100%), Charakter-Rekordanzeige und Reset-Button.
   - **Rechte Spalte:** Sound-Auswahl (Schaden, Heilung, Low, Kanal), Sprachauswahl und Test-Buttons (`►`).

---

## 7. Anleitung zur Nachbildung / Testen

1. **Dateien anlegen:** Die Dateien `CritTracker.toc`, `Localization.lua`, `CritTracker.lua` und `Config.lua` wie spezifiziert erstellen.
2. **Sounds ablegen:** 
   - `sounds/German/`: `crit1.mp3` bis `crit4.mp3`, `heal1.mp3` bis `heal4.mp3`, `low.mp3`.
   - `sounds/English/`: `crit1.mp3` bis `crit4.mp3`, `heal1.mp3` bis `heal4.mp3`, `low.mp3`.
3. **Im Spiel testen:**
   - `/ctr` eingeben -> Einstellungsfenster muss sich öffnen.
   - Auf die `►`-Buttons klicken -> Die jeweiligen MP3-Dateien müssen hörbar abgespielt werden.
   - `/ctr test crit` -> Testet Schadensmeldung und Audio.
   - `/ctr test heal` -> Testet Heilungsmeldung und Audio.
   - `/ctr test low` -> Testet Low-Crit-Meldung und `low.mp3`.
   - Schieberegler verstellen -> Werte in `CritTrackerDB.settings` müssen persistieren.
   - `/ctr reset` -> Rekorde werden auf 0 gesetzt.