DungeonCrawler/PROJEKTDOKU.md

# DungeonCrawler – Projektdokumentation

## Übersicht
DungeonCrawler ist ein Third-Person Action-RPG entwickelt in Godot 4.
Spieler können solo oder in einer Gruppe von bis zu 6 Spielern Dungeons erkunden,
Gegner bekämpfen und ihre Charaktere mit verschiedenen Klassen und Ausrüstungen anpassen.

---

## Technologie
- **Engine:** Godot 4 (GDScript)
- **Perspektive:** Third-Person
- **Plattform:** PC (Windows)

---

## Steuerung

| Taste | Aktion |
|---|---|
| W / A / S / D | Bewegen |
| Mausrad | Kamera zoomen (min 5, max 20) |
| LMB gehalten + Mausbewegung | Kamera frei drehen (umschauen), Charakter bleibt in Position |
| LMB Klick auf Gegner | Ziel markieren |
| LMB Klick auf freie Fläche | Ziel abvisieren |
| RMB gehalten + Mausbewegung | Spieler + Kamera drehen (auch mit Target → weglaufen) |
| RMB Klick auf Gegner | Ziel markieren + Autoattack starten |
| 1 – 9 | Aktionsleiste Slots (Skills + Consumables, frei belegbar) |
| C | Charakter-Panel (Stats + Equipment) |
| I | Inventar öffnen/schließen |
| P | Fähigkeiten-Panel (alle Skills, Drag auf Aktionsleiste) |
| Leertaste | Springen |
| NumLock | Walk/Run umschalten |

---

## Szenen-Struktur

### world.tscn
Hauptszene der Spielwelt. Zeigt bei Start das Hauptmenü (Einstellungen), dann Klassenauswahl.
```
World (Node3D)
├── Player (player.tscn)
├── Enemy (enemy.tscn)
├── Boden (StaticBody3D)
│   ├── MeshInstance3D (Schachbrett-Shader)
│   └── CollisionShape3D
├── DirectionalLight3D
└── NavigationRegion3D
```

### player.tscn
Der Spielercharakter mit allen UI-Panels.
```
Player (CharacterBody3D)
├── Model (Node3D)
│   └── castle_guard_01 (Mixamo FBX mit Skeleton3D + AnimationPlayer)
├── CollisionShape3D
├── CameraPivot (Node3D + camera_pivot.gd)
│   └── Camera3D
└── HUD (hud.tscn)
```
UI-Panels (CharacterPanel, InventoryPanel, LootWindow, SkillPanel) werden zur Laufzeit erstellt.

### enemy.tscn
Ein Gegner mit Patrol-KI und Kampf-Animationen.
```
Enemy (CharacterBody3D)
├── Model (castle_guard_01.fbx — Mixamo Charakter mit Skeleton3D + AnimationPlayer)
├── CollisionShape3D
├── NavigationAgent3D
└── HealthDisplay (Node3D)
    └── Label3D
```

---

## Kamera-System (camera_pivot.gd)

### Modi
| Situation | Verhalten |
|---|---|
| Kein Ziel, LMB gehalten | Kamera orbitet frei, Spieler dreht sich nicht |
| Kein Ziel, RMB gehalten | Spieler + Kamera drehen sich gemeinsam |
| Ziel markiert, nichts gedrückt | Soft Lock-On: Spieler dreht sich smooth zum Ziel |
| Ziel markiert, LMB gehalten | Lock-On pausiert, Kamera frei drehbar (umschauen) |
| Ziel markiert, RMB gehalten | Lock-On pausiert, Spieler+Kamera drehen (weglaufen) |

Lock-On springt automatisch zurück sobald LMB/RMB losgelassen wird und Ziel noch markiert ist.

---

## Klassen-System

### CharacterClass (character_class.gd)
Resource-Klasse die eine spielbare Klasse definiert.

| Property | Typ | Beschreibung |
|---|---|---|
| class_name_de | String | Deutscher Klassenname |
| main_stat | MainStat | STRENGTH, AGILITY oder INTELLIGENCE |
| base_strength/agility/intelligence/stamina | int | Basis-Stats auf Level 1 |
| strength/agility/intelligence/stamina_per_level | float | Stat-Zuwachs pro Level |
| unarmed_min_damage | int | Unbewaffneter Mindestschaden |
| unarmed_max_damage | int | Unbewaffneter Maximalschaden |
| unarmed_attack_speed | float | Unbewaffnete Angriffsgeschwindigkeit |
| resource_type | ResourceType | NONE, MANA, RAGE, ENERGY |
| base_resource | int | Basis-Ressource auf Level 1 |

**Konstanten:**
- `HP_PER_STAMINA = 10` — HP pro Stamina-Punkt
- `MANA_PER_INT = 5` — Mana pro Intelligenz-Punkt
- `DAMAGE_PER_MAIN_STAT = 0.5` — Zusatzschaden pro Main-Stat-Punkt

### Verfügbare Klassen (classes/)

| Klasse | Main-Stat | Ressource | STR | AGI | INT | STA | Unbewaffnet |
|---|---|---|---|---|---|---|---|
| Krieger | Stärke | Keine | 15 | 8 | 5 | 12 | 2-4 Schaden, 1.8s |
| Schurke | Beweglichkeit | Energie (100) | 8 | 15 | 7 | 10 | 1-3 Schaden, 1.5s |
| Magier | Intelligenz | Mana (100 + INT*5) | 5 | 8 | 15 | 8 | 1-2 Schaden, 2.0s |

### Hauptmenü (main_menu.gd)
Wird als erstes angezeigt mit Optionen:
- **Spielen** — Öffnet Klassenauswahl
- **Einstellungen** — Auflösung (720p-4K), Fenstermodus (Fenster/Randlos/Vollbild), VSync, Anti-Aliasing (Aus/2x/4x/8x)
- **Beenden** — Spiel schließen

### Klassenauswahl (class_selection_menu.gd)
Wird nach dem Hauptmenü angezeigt. Spieler wählt eine Klasse, danach wird Startausrüstung angelegt.

---

## Klassen-Ressourcen-System

Jede Klasse kann eine eigene Ressource haben:
| Ressource | Farbe | Skalierung | Klasse |
|---|---|---|---|
| Keine | - | - | Krieger |
| Mana | Blau | base_resource + INT * 5 | Magier |
| Energie | Gelb | Fix (base_resource) | Schurke |
| Wut | Rot | Fix (base_resource) | (geplant) |

Die Ressourcen-Leiste wird nur angezeigt wenn die Klasse eine Ressource hat.

---

## Level-System

- **XP-Kurve:** Level N benötigt `100 * 1.5^(N-2)` XP
- **Stats pro Level:** Basierend auf Klassen-Zuwachsraten
- **HP bei Level-Up:** Werden vollständig aufgefüllt (HP + Klassen-Ressource)
- **XP-Vergabe:** Gegner geben XP basierend auf `xp_reward` Export-Variable
- **Character Panel:** Aktualisiert sich automatisch bei Level-Up

---

## Equipment-System

### Equipment (equipment.gd)
Resource-Klasse für alle Ausrüstungsgegenstände.

**Slots:** HEAD, CHEST, HANDS, LEGS, FEET, WEAPON, OFFHAND

**Seltenheiten:**
| Seltenheit | Farbe |
|---|---|
| COMMON | Weiß |
| UNCOMMON | Grün |
| RARE | Blau |
| EPIC | Lila |

**Stats auf Equipment:**
| Property | Typ | Beschreibung |
|---|---|---|
| item_name | String | Name des Items |
| slot | Slot | Equipment-Slot |
| rarity | Rarity | Seltenheitsstufe |
| armor | int | Rüstungswert |
| strength/agility/intelligence/stamina | int | Stat-Boni |
| haste | float | Angriffsgeschwindigkeits-Bonus (0.1 = 10%) |
| min_damage / max_damage | int | Waffenschaden (nur Waffen) |
| attack_speed | float | Angriffsgeschwindigkeit (nur Waffen) |
| weapon_range | float | Reichweite (nur Waffen) |

### Vorhandene Equipment-Items (equipment/)
- **iron_sword.tres** — Eisenschwert (Waffe)
- **steel_sword.tres** — Stahlschwert (Waffe, besser)
- **leather_chest.tres** — Lederrüstung (Brust)
- **iron_helm.tres** — Eisenhelm (Kopf)
- **wooden_shield.tres** — Holzschild (Nebenhand)

### Character Panel (character_panel.gd, C-Taste)
Zeigt zwei Spalten:
- **Stats-Spalte:** Stärke, Beweglichkeit, Intelligenz, Ausdauer, Rüstung, HP
- **Equipment-Spalte:** Icon-Grid mit Tooltips bei Hover, Waffenschaden + DPS

Unbewaffnet: Zeigt klassenabhängige Schadenswerte.

---

## Consumable-System

### Consumable (consumable.gd)
Resource-Klasse für verbrauchbare Items (Tränke, Essen, etc.).

| Property | Typ | Beschreibung |
|---|---|---|
| item_name | String | Name des Tranks |
| effect_type | EffectType | HEAL_HP, RESTORE_MANA, HEAL_AND_MANA |
| amount | int | Heilungsmenge |
| cooldown | float | Cooldown nach Benutzung |
| icon | Texture2D | Icon für UI |
| stack_size | int | Aktuelle Anzahl im Stack |
| max_stack | int | Maximale Stack-Größe (20) |

### Vorhandene Tränke (consumables/)
- **small_hp_potion.tres** — Kleiner Heiltrank (+50 HP, 40% Drop-Chance)
- **small_mana_potion.tres** — Kleiner Manatrank (+40 Mana, 25% Drop-Chance)

### Benutzung
- **Rechtsklick im Inventar:** Trank direkt benutzen
- **Shift+Linksklick im Inventar:** Trank auf nächsten freien Aktionsleisten-Slot legen
- **Taste 3-9:** Trank über Aktionsleiste benutzen
- HP-Tränke: Nur wenn HP nicht voll, stellt HP wieder her
- Mana-Tränke: Nur wenn Mana nicht voll, stellt Ressource wieder her
- **Stacking:** Gleichnamige Tränke werden automatisch gestackt (max 20)

---

## Inventar-System

### Inventory (inventory.gd)
Resource-Klasse für das Spieler-Inventar.

- **MAX_SLOTS:** 20 Inventarplätze
- **Gold:** Währung, wird im HUD angezeigt
- **Signals:** `inventory_changed`, `gold_changed`

**Funktionen:**
| Funktion | Beschreibung |
|---|---|
| add_item(item) | Item hinzufügen (false wenn voll) |
| remove_item(item) | Item entfernen |
| add_gold(amount) | Gold hinzufügen |
| spend_gold(amount) | Gold ausgeben (false wenn nicht genug) |
| is_full() | Prüfen ob Inventar voll |
| swap_items(a, b) | Zwei Items tauschen |
| move_item(from, to) | Item verschieben |

### Inventory Panel (inventory_panel.gd, I-Taste)
- 5x4 Grid mit Item-Slots
- Gold-Anzeige im Header
- Items in Seltenheitsfarbe
- Tooltips mit vollständigen Item-Stats
- **Rechtsklick** auf Item: Direkt anlegen (tauscht mit aktuellem Equipment)
- **Drag & Drop:** Items innerhalb des Inventars verschieben, auf Aktionsleiste ziehen

---

## Loot-System

### LootTable (loot_table.gd)
Resource die mögliche Drops eines Gegners definiert.

| Property | Typ | Beschreibung |
|---|---|---|
| min_gold | int | Minimaler Gold-Drop |
| max_gold | int | Maximaler Gold-Drop |
| possible_drops | Array[LootEntry] | Mögliche Item-Drops |

### LootEntry (loot_entry.gd)
Ein einzelner Drop-Eintrag.

| Property | Typ | Beschreibung |
|---|---|---|
| item | Resource | Das droppbare Item (Equipment oder Consumable) |
| drop_chance | float | Wahrscheinlichkeit (0.0 - 1.0) |

### Vorhandene LootTables (loot_tables/)
- **goblin_loot.tres** — 2-8 Gold, Eisenschwert (15%), Lederrüstung (10%), Eisenhelm (10%), Heiltrank (40%), Manatrank (25%)
- **skeleton_loot.tres** — 5-15 Gold, Stahlschwert (10%), Holzschild (12%), Eisenhelm (15%)

### LootWindow (loot_window.gd)
- Erscheint automatisch wenn ein Gegner stirbt
- Zeigt Gold und gedropte Items
- Einzelne Items per Klick aufheben
- "Alles aufheben" Button
- Gold skaliert mit Gegner-Level

---

## Kampfsystem

### Global Cooldown (GCD)
Alle Aktionen (Autoattack + Skills) teilen sich einen GCD.

**Formel:** `GCD = Waffen-Attackspeed / (1 + Haste)`

Beispiel: Waffe mit 1.5s + 50% Haste → `1.5 / 1.5 = 1.0s`

### Schadensberechnung
1. **Basisschaden:** Zufällig zwischen Waffen min/max (oder unbewaffnet klassenabhängig)
2. **Stat-Bonus:** `Main-Stat * 0.5`
3. **Rüstungsreduktion (Nahkampf):** `Reduktion = Rüstung / (Rüstung + 50)`
4. **Level-Differenz:** `±10% pro Level, max ±50%`
5. **Mindestschaden:** Immer mindestens 1

### Autoattack
- Startet per RMB-Klick auf Gegner oder manuell per Taste 1
- Greift automatisch an sobald GCD abgelaufen und Ziel in Reichweite
- Stoppt wenn Ziel stirbt oder abvisiert wird
- Startet neu wenn man wieder in Range kommt (solange aktiv)

### DPS-Berechnung
`DPS = (Durchschnittsschaden + Stat-Bonus) / GCD`

### Skills

#### Autoattack (Taste 1, Krieger/Schurke)
- **Schaden:** Waffenschaden oder klassenabhängig unbewaffnet + Main-Stat Bonus
- **Cooldown:** GCD (Waffen-Attackspeed / Haste)
- **Reichweite:** Waffen-Reichweite oder 3.0 (unbewaffnet)
- **Animation:** autoattack

#### Zauberstab (Taste 1, Magier)
- **Schaden:** Waffenschaden + INT (magisch, ignoriert Rüstung)
- **Cooldown:** GCD
- **Reichweite:** 20.0
- Deaktiviert Autoattack, exklusiver Fernkampf-Modus
- **Animation:** autoattack

#### Frostblitz (Taste 2, Magier)
- **Schaden:** 12-20 + INT (magisch)
- **Castzeit:** 1.5 Sekunden (unterbrechbar durch Bewegung/Schaden/Springen)
- **Manakosten:** 20
- **Cooldown:** 2.5 Sekunden
- **Reichweite:** 20.0
- Castbar wird über der Aktionsleiste angezeigt

#### Heavy Strike (Taste 2, Krieger/Schurke)
- **Schaden:** 10-15 + Main-Stat Bonus
- **Cooldown:** 3 Sekunden (eigener Cooldown, löst auch GCD aus)
- **Reichweite:** 4.0
- Aktiviert automatisch Autoattack danach
- **Animation:** heavy_strike

### UI & Icons
- Aktionsleiste mit 9 Slots (Taste 1-9), frei belegbar mit Skills und Consumables
- Drag & Drop: Skills/Tränke zwischen Slots verschieben, aus Leiste rausziehen zum Entfernen
- Fähigkeiten-Panel (P-Taste): Listet alle verfügbaren Skills, per Drag auf Aktionsleiste ziehen
- Cooldown-Anzeige: Dunkle Überlagerung + verbleibende Zeit
- Gelber Highlight-Rand beim Drag über Slots

---

## Gegner-System (enemy.gd)

### Stats (Export-Variablen)
| Stat | Standard |
|---|---|
| max_hp | 50 |
| min_damage / max_damage | 3-7 |
| attack_range | 2.0 |
| attack_speed | 2.0s |
| move_speed | 5.5 (Rennen bei Aggro) |
| patrol_speed | 1.5 (Laufen bei Patrol) |
| detection_range | 15.0 |
| patrol_radius | 8.0 |
| xp_reward | 20 |

### KI-Verhalten (State Machine)
| State | Beschreibung |
|---|---|
| IDLE | Wartet (wird initial für 5s nach Spawn verwendet) |
| PATROL | Läuft zwischen zufälligen Punkten im Spawn-Radius, walk-Animation, Turn-Animationen beim Richtungswechsel |
| CHASING | Rennt zum Spieler (run-Animation), aktiviert bei detection_range oder Schaden |
| ATTACKING | Steht, dreht sich zum Spieler, greift in attack_speed-Intervallen an |
| DEAD | Spielt death-Animation, wird nach 2s entfernt |

### Patrol-System
- Enemy patrouilliert um seinen Spawnpunkt im konfigurierbaren Radius
- Wartet 2-5 Sekunden zwischen Patrol-Punkten (idle-Animation)
- Spielt Turn-Animation (left_turn_90 / right_turn_90) vor dem Loslaufen
- Läuft mit langsamer patrol_speed und walk-Animation
- Bei Aggro sofort Wechsel zu run-Animation und move_speed

### Aggro
- **Detection Range:** Spieler wird automatisch erkannt wenn in 15m Reichweite
- **Schaden-Aggro:** Bei Schaden sofort Wechsel zu CHASING, auch aus PATROL
- **Spieler-Suche:** Per `get_nodes_in_group("player")`

### Respawn
- Gegner spawnen nach 5 Sekunden am Ursprungsort neu
- Verwaltet durch world.gd (`_on_enemy_died` Signal)

### Animationen
Werden zur Laufzeit aus FBX-Dateien geladen (gleiche Methode wie Player):
- idle, walk, run, autoattack, death, turn_left, turn_right
- Root Motion wird automatisch entfernt (`_strip_root_motion`)

### Loot-Drops
- Jeder Gegner hat eine optionale `loot_table` (LootTable Resource)
- Gold skaliert mit Gegner-Level
- Ohne LootTable: Standard-Gold-Drop

---

## Animations-System

### Mixamo-Integration
Charaktermodelle stammen von Mixamo (castle_guard_01.fbx) und werden mit separaten Animations-FBX-Dateien kombiniert.

**Lade-Prozess (player.gd / enemy.gd):**
1. `_setup_animations()` findet den AnimationPlayer im Modell
2. Jede Animations-FBX wird als PackedScene geladen (`_load_anim_from_fbx`)
3. Root Motion wird entfernt (`_strip_root_motion` — XZ-Position nullen, Y behalten)
4. Loop-Modus wird gesetzt (Bewegungsanimationen loopen, Angriff/Tod nicht)
5. Animation wird der AnimationLibrary hinzugefügt

### Verfügbare Animationen (assets/Warrior+Animation/)
| Animation | Datei | Loop | Verwendung |
|---|---|---|---|
| idle | idle.fbx | Ja | Stillstehen |
| walk | walking.fbx | Ja | Vorwärts laufen |
| run | running.fbx | Ja | Rennen |
| walk_back | Walking Backwards.fbx | Ja | Rückwärts laufen |
| strafe_left | left strafe walking.fbx | Ja | Links seitwärts |
| strafe_right | right strafe walking.fbx | Ja | Rechts seitwärts |
| run_strafe_left | Running Left Strafe.fbx | Ja | Rennen links |
| run_strafe_right | Running Right Strafe run.fbx | Ja | Rennen rechts |
| jump | jump.fbx | Nein | Springen |
| walk_jump | Walking Jump.fbx | Nein | Sprung beim Laufen |
| run_jump | Running Jump.fbx | Nein | Sprung beim Rennen |
| autoattack | Autoattack.fbx | Nein | Autoattack / Zauberstab |
| heavy_strike | Heavy Strike.fbx | Nein | Heavy Strike Skill |
| death | Dying Backwards.fbx | Nein | Tod |
| roll | Quick Roll To Run.fbx | Nein | Ausweichrolle |
| turn_180 | Running Turn 180.fbx | Nein | 180°-Drehung |
| turn_left | Left Turn 90.fbx | Nein | 90° links (Enemy Patrol) |
| turn_right | Right Turn 90.fbx | Nein | 90° rechts (Enemy Patrol) |

---

## HUD (hud.gd)

| Element | Beschreibung |
|---|---|
| HealthBar | Rote HP-Leiste mit Text "aktuell / max" |
| ResourceBar | Ressourcen-Leiste (Blau=Mana, Gelb=Energie, Rot=Wut), nur sichtbar wenn Klasse eine Ressource hat |
| LevelLabel | "Lv X" Anzeige |
| XPBar | Blaue XP-Leiste |
| GoldLabel | Gold-Anzeige in Goldfarbe |
| ActionBar | 9 Slots mit Icons, Cooldowns, Klick-Support, Stack-Anzeige für Consumables |
| Castbar | Zauberbalken über der Aktionsleiste (eigener CanvasLayer, layer 10) |

---

## Geplante Features
- [ ] Wut-Ressource für Krieger
- [ ] Spell-System (Feuerbälle etc.)
- [ ] Schadenstypen (Physical, Fire, Ice, Lightning, Poison)
- [ ] Mehrere Gegnertypen
- [ ] Dungeon-Level mit Wänden und Räumen
- [ ] Multiplayer (bis zu 6 Spieler)
- [ ] Boss-Gegner
- [ ] Item-Shop / Händler

---

## Projektstruktur
```
DungeonCrawler/
├── assets/
│   ├── Warrior+Animation/      # Mixamo Charakter + Animationen (castle_guard_01.fbx + FBX)
│   └── kenney_animated-characters-1/  # Kenney Animated Characters Pack
├── classes/                 # Klassen-Definitionen (.tres)
│   ├── warrior.tres
│   ├── rogue.tres
│   └── mage.tres
├── consumables/             # Verbrauchbare Items (.tres)
│   ├── small_hp_potion.tres
│   └── small_mana_potion.tres
├── equipment/               # Equipment-Items (.tres)
│   ├── iron_sword.tres
│   ├── steel_sword.tres
│   ├── leather_chest.tres
│   ├── iron_helm.tres
│   ├── wooden_shield.tres
│   └── wooden_staff.tres
├── loot_tables/             # Loot-Tabellen (.tres)
│   ├── goblin_loot.tres
│   └── skeleton_loot.tres
├── icons/                   # Icons (SVG)
│   ├── autoattack_icon.svg
│   ├── heavy_strike_icon.svg
│   ├── frostbolt_icon.svg
│   ├── wand_icon.svg
│   ├── iron_sword_icon.svg
│   ├── steel_sword_icon.svg
│   ├── leather_chest_icon.svg
│   ├── iron_helm_icon.svg
│   ├── wooden_shield_icon.svg
│   ├── wooden_staff_icon.svg
│   ├── hp_potion_icon.svg
│   └── mana_potion_icon.svg
├── camera_pivot.gd          # Kamera-Script (Lock-On, freies Drehen, Zoom)
├── character_class.gd       # CharacterClass Resource
├── character_panel.gd/.tscn # Charakter-Panel (Stats + Equipment)
├── class_selection_menu.gd/.tscn # Klassenauswahl
├── consumable.gd            # Consumable Resource
├── enemy.gd / enemy.tscn    # Gegner (KI, Patrol, Kampf, Animationen)
├── equipment.gd             # Equipment Resource
├── hud.gd / hud.tscn        # HUD (HP, Ressource, XP, Aktionsleiste, Castbar)
├── inventory.gd             # Inventar Resource
├── inventory_panel.gd/.tscn # Inventar-Panel (Drag & Drop)
├── loot_entry.gd            # LootEntry Resource
├── loot_table.gd            # LootTable Resource
├── loot_window.gd/.tscn     # Loot-Fenster
├── main_menu.gd/.tscn       # Hauptmenü (Einstellungen)
├── player.gd / player.tscn  # Spieler (Bewegung, Kampf, Skills, UI)
├── skill_panel.gd/.tscn     # Fähigkeiten-Panel
├── world.gd / world.tscn    # Hauptszene (Spawn, Respawn, Sky, Boden)
└── PROJEKTDOKU.md           # Diese Dokumentation
```