Addon CritTracker implementiert (WoW Forever 12.x Beta, Interface 16001)
- Getrennte Erfassung für Schaden und Heilung - Erkennung schwacher Crits mit einstellbarem Schwellenwert (Standard 30%) - Audio-Feedback (crit1-4, heal1-4, low.mp3) für Deutsch und Englisch - Einstellungsmenü mit Cooldown-Slider (1-30s), Sound-Auswahl und Test-Buttons - Automatischer Reset der Rekorde bei Stufenaufstieg (PLAYER_LEVEL_UP) - Lokale Chat-Benachrichtigungen (nur für Spieler sichtbar) - Slash-Befehle /ctr und /crittracker - Entwickler- & Agenten-Leitfaden (AGENT_GUIDE.md) hinzugefügt - sounds/English/low.mp3 repariert
This commit is contained in:
185
AGENT_GUIDE.md
Normal file
185
AGENT_GUIDE.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user