CritTracker/AGENT_GUIDE.md

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.

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

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:

  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.