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.
Enthält Overworld (Gras-Terrain, Berg, Dungeon-Tor, Felsen, Bäume) und generiert Dungeon-Ebenen zur Laufzeit.
```
World (Node3D)
├── Player (player.tscn)
├── Enemy (enemy.tscn)                   # Overworld-Gegner
├── Boden (StaticBody3D)                 # Gras-Terrain mit Noise-Shader
│   ├── MeshInstance3D
│   └── CollisionShape3D
├── DirectionalLight3D
├── NavigationRegion3D                   # Overworld NavMesh (im Editor backen!)
├── Mountain (CSGCombiner3D)             # Berg mit 4 CSGSphere3D, use_collision
├── DungeonGate                          # Tor zum Dungeon (Area3D + Label)
│   ├── GateArea (Area3D)
│   └── GateLabel (Label3D)
├── Rocks (9x CSGSphere3D)
├── Trees (6x CSGCylinder3D + CSGSphere3D)
└── [DungeonContainer] (zur Laufzeit)    # Wird bei Dungeon-Eintritt generiert
    ├── DungeonNavRegion (NavigationRegion3D)
    ├── Floor/Wall/Ceiling Tiles (CSGBox3D)
    ├── Enemies
    ├── ReturnPortal (Area3D)
    └── DeeperPortal (Area3D)
```

### 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 (Goblin-Modell) mit Patrol-KI, NavMesh-Pathfinding und Kampf-Animationen.
```
Enemy (CharacterBody3D)
├── Model (goblin_d_shareyko.fbx — Goblin mit Skeleton3D + AnimationPlayer)
├── CollisionShape3D (CapsuleShape3D, radius=0.35, height=1.4)
├── NavigationAgent3D (radius=0.4, für NavMesh-Pfadfindung)
└── 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.

### Kamera-Kollision
- Raycast vom Pivot zur gewünschten Kameraposition
- Bei Wandkollision: Kamera rückt näher an den Spieler (min 1.0 Abstand)
- Ignoriert CharacterBody3D (Gegner) — nur Wände/Terrain
- Smooth-Zoom zurück wenn Wand nicht mehr im Weg

---

## Klassen, Stats & Level-System

> Vollständige Dokumentation in [CHARAKTER_SYSTEM.md](CHARAKTER_SYSTEM.md)
> (Klassen, Grund-/Zusatzstats, freie Punkte, Level-System, Kampf-System, Skills)

### 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

---

## 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)

### Waffen-Modell am Charakter (BoneAttachment3D)
- Schwert-Modell (`medieval_sword.glb`) wird zur Laufzeit an die rechte Hand (`mixamorig_RightHand`) des Spielers gehängt
- Verwendet `BoneAttachment3D` am Skeleton3D des Spielermodells
- Modell wird beim Ausrüsten einer Waffe (`equip_item`) angezeigt und beim Ablegen entfernt
- Position/Rotation/Scale werden im Code gesetzt: `Vector3(0.5, 0.2, 0)`, `Vector3(90, 180, 0)`, `Vector3(0.8, 0.8, 0.8)`
- Funktionen: `_setup_weapon_attachment()`, `_attach_weapon_model()`, `_remove_weapon_model()`

### 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)
- **Trink-Animation:** Beim Benutzen wird die Drinking-Animation abgespielt (0.3s Blend, 0.7x Speed)
- Während des Trinkens: keine Skills, kein weiterer Trank, Bewegung bricht ab
- **Starter-Tränke:** Spieler startet mit 3 kleinen Heiltränken auf Slot 3

---

## 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) |

### Gold-Skalierung nach Enemy-Level
- `generate_loot(enemy_level)` berechnet Gold: `base_gold * (1.0 + (level-1) * 0.5)`
- Level 1: x1.0, Level 3: x2.0, Level 5: x3.0

### Vorhandene LootTables (loot_tables/)
- **goblin_loot.tres** — 2-8 Gold, Eisenschwert (5%), Lederrüstung (5%), Eisenhelm (5%), Heiltrank (15%), Manatrank (10%)
- **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, Skills & UI

> Vollständige Dokumentation in [CHARAKTER_SYSTEM.md](CHARAKTER_SYSTEM.md)
> (Schadensberechnung, Autoattack, Skills, GCD, Krieger-Skills)
> Skills entwickeln sich über das [SKILL_SYSTEM.md](SKILL_SYSTEM.md) weiter.

### Krieger — Wut-System
- Ressource: **Wut** (0–100, rot), verfällt nach 5s außerhalb Kampf
- Aufbau: +10 durch Heavy Strike, +15 wenn Schaden genommen
- Während **Berserker** aktiv: Wut verfällt nicht, Skills kosten keine Wut

### Krieger — Skills (implementiert)
| Level | Skill | Kosten | Effekt |
|---|---|---|---|
| 1 | Autoattack | — | Basis-Schaden |
| 1 | Heavy Strike | — | Schaden + 10 Wut, 3s CD |
| 5 | Tektonischer Schlag | 30 Wut | AoE Radius 4m, Slow 60% für 3s |
| 10 | Durchbeißen | — | Mit Schild → Schildwall (85% Reduktion); ohne → Trotz (skaliert mit fehlendem HP) |
| 15 | Blutrausch | 25 Wut | Sofortschaden + Blutung DOT (4/s, 8s) |
| 20 | Wirbelwind | 40 Wut | AoE Radius 3.5m, hoher Schaden |
| 28 | Zornfesseln | 35 Wut | Zieht Gegner heran (12m), dann Schlag |
| 35 | Berserker | Alle Wut (min 50) | 10s: 2× Attackspeed, 25% weniger Schaden; danach 2.5s Crash |

### Gegner-Debuffs (enemy.gd)
- `apply_slow(factor, duration)` — Bewegungsgeschwindigkeit reduzieren
- `apply_pull(source, duration)` — Gegner zu Quelle ziehen, überschreibt KI

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

### UI & Icons
- Aktionsleiste mit 9 Slots (Taste 1-9), frei belegbar mit Skills und Consumables, mittig unten
- 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
- Slot-Nummern (1-9) oben links im Slot sichtbar
- XP-Leiste direkt unter der Aktionsleiste, gleiche Breite, zeigt "Lv X  current/max XP" zentriert
- Icons: PNG (Dark Fantasy Stil, via ChatGPT generiert) für alle Krieger-Skills

---

## 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 |
| mob_level | 1 |

### Level-Skalierung
Stats werden in `_ready()` basierend auf `mob_level` skaliert (Basiswerte = Level 1):
- **HP:** +30% pro Level (`max_hp * (1 + (level-1) * 0.3)`)
- **Schaden:** +20% pro Level (`damage * (1 + (level-1) * 0.2)`)
- **XP:** +40% pro Level (`xp * (1 + (level-1) * 0.4)`)
- **Gold:** +50% pro Level (in `generate_loot`)

### 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 10s 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
- Patrol-Ziel wird auf nächsten begehbaren NavMesh-Punkt gesnapped
- Bei Aggro sofort Wechsel zu run-Animation und move_speed

### Pathfinding (NavigationAgent3D)
- Nutzt `NavigationAgent3D` mit NavMesh-Pfadfindung (Dungeon)
- Gegner laufen um Wände und Ecken herum zum Spieler
- Pfad wird nur neu berechnet wenn Spieler sich > 1.5 Einheiten bewegt hat (Anti-Flicker)
- Fallback auf direkte Bewegung wenn kein NavMesh vorhanden (Overworld)

### Aggro & Leash
- **Detection Range:** Spieler wird automatisch erkannt wenn in 15m Reichweite
- **Schaden-Aggro:** Bei Schaden sofort Wechsel zu CHASING, auch aus PATROL
- **Leash Range:** Gegner verliert Aggro wenn > 30 Einheiten vom Spawnpunkt entfernt
- **Spieler-Suche:** Per `get_nodes_in_group("player")`

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

### Animationen (Goblin-Modell)
Werden zur Laufzeit aus FBX-Dateien geladen (assets/Goblin+Animation/):
- idle, walking, standard run, attack, die, left turn 90, right turn 90
- 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

### Spieler-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 |
| turn_right | Right Turn 90.fbx | Nein | 90° rechts |

### Gegner-Animationen (assets/Goblin+Animation/)
| Animation | Datei | Loop | Verwendung |
|---|---|---|---|
| idle | idle.fbx | Ja | Stillstehen |
| walk | walking.fbx | Ja | Patrol-Laufen |
| run | standard run.fbx | Ja | Rennen (Aggro) |
| autoattack | attack.fbx | Nein | Angriff |
| death | die.fbx | Nein | Tod |
| turn_left | left turn 90.fbx | Nein | 90° links (Patrol) |
| turn_right | right turn 90.fbx | Nein | 90° rechts (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 |
| ResourceBar | Ressourcen-Leiste oben links (Blau=Mana, Gelb=Energie, Rot=Wut) |
| GoldLabel | Gold-Anzeige in Goldfarbe oben links |
| ActionBar | 9 Slots, mittig unten, Icons füllen ganzen Slot, Slot-Nummern oben links |
| XPBar | Unter der Aktionsleiste, gleiche Breite, Label zentriert: "Lv X  XP/max" |
| Castbar | Zauberbalken über der Aktionsleiste (eigener CanvasLayer, layer 10) |

---

## Skill Mastery & Fusion System (Konzept)

Ein organisches Skill-System bei dem Skills sich wie Lebewesen verhalten — sie erinnern sich, wachsen und können Beziehungen eingehen.

### Kern-Konzept: Skill Memory
Jeder Skill speichert Kontext-Schnappschüsse jeder Nutzung:
- `hp_percent` — Wie viel HP der Spieler bei Nutzung hatte
- `was_opener` — War es der erste Treffer im Kampf
- `target_hp_percent` — HP des Ziels bei Nutzung
- `was_moving` — Ob der Spieler sich bewegte
- `time_since_last_skill` — Zeit seit dem letzten Skill
- `last_skill_used` — Welcher Skill davor benutzt wurde

Nach genug Nutzungen erkennt das System **dominante Muster** und der Skill bekommt eine **Mutation** (eigenständig, ohne Spielereingriff):

| Muster (60%+ der Nutzungen) | Mutation |
|---|---|
| Bei <30% HP | "Verzweiflung" — Schaden skaliert mit fehlendem HP |
| Als erster Treffer im Kampf | "Hinterhalt" — Bonus nur beim Opener |
| Im Stehen | "Standoff" — Channeling-Effekt, mehr Schaden |
| Direkt nach demselben Skill | "Rhythmus" — Combo-Bonus bei Wiederholung |
| Selten genutzt | "Verblasst" — schwächer, irgendwann weg |

### Sockel-System
Spieler können Edelsteine mit Elementen in Sockel-Slots eines Skills einsetzen:
- **Elemente:** Feuer, Eis, Blitz, Dunkel, Licht
- Nach X Nutzungen **verschmilzt** der Edelstein mit dem Skill — der Skill trägt das Element dauerhaft
- **Neuer Sockel** entsteht automatisch bei hoher Resonanz (Element passte zur Spielweise), sonst per Soul Dust erzwingbar
- **Rarity** bestimmt maximale Sockel-Slots: Common=1, Rare=2, Epic=3, Legendary=4

**Hybrid-Elemente** durch Verschmelzung zweier Skills:
| Kombination | Ergebnis |
|---|---|
| Feuer + Eis | Dampf / Schmelze |
| Dunkel + Licht | Gleichgewicht |
| Blitz + Erde | Magnetismus |
| Feuer + Blitz | Plasma |

### Verheiratungs-Phasen (Skill Linking)
Zwei Skills können verlinkt werden und entwickeln sich gemeinsam weiter:

```
VERLOBT → VERBUNDEN → FUSIONIERT ★
```

| Phase | Beschreibung |
|---|---|
| **Verlobt** | Beide Skills bleiben einzeln spielbar. Teilen Kontext-Erinnerungen. Zusammen gespielt = mehr Resonanz. Jederzeit kostenlos trennbar. |
| **Verbunden** | Nach ausreichend gemeinsamer Nutzung verschmelzen beide zu EINEM neuen Skill. Trennbar gegen Kosten (Erinnerungssplitter, nicht beide Skills zurück). |
| **Fusioniert ★** | Spieler markiert bewusst als untrennbar. Kein Zurück. Kleiner permanenter Bonus als Belohnung fürs Commitment (z.B. extra Sockel-Slot, CD-Reduktion). |

**Scheidung** (nur für verheiratete/verbundene Skills, nicht für eigenständig mutierte):
- Verbundene Skills trennen kostet **Soul Dust** + Verlust der während der Ehe entwickelten Elemente
- Organische Mutationen beider Skills bleiben erhalten
- Fusioniert ★ = endgültig, keine Scheidung möglich

### Ressourcen
| Ressource | Herkunft | Verwendung |
|---|---|---|
| **Soul Dust** | Auflösen ungenutzter Skills | Neuen Sockel erzwingen, Scheidungskosten |
| **Edelsteine** | Gefunden / Gegner-Drops | In Sockel einsetzen für Elemente |
| **Erinnerungssplitter** | Scheidung verbundener Skills | In anderen Skill "einpflanzen" um Kontext-Geschichte zu übertragen |

### Rarity-System
Rarity steigt durch Skill-Generationen (Verbindung/Fusion) — nicht durch Grinding:
- Kind-Skills aus Verbindungen starten automatisch mit höherer Rarity als ihre Eltern
- Mehr Rarity = mehr Sockel-Slots = mehr Potential für Elementar-Kombinationen

---

## Dungeon-System (world.gd)

### Überblick
Prozedural generierte Dungeon-Ebenen innerhalb derselben Szene (kein Szenenwechsel). Overworld wird versteckt, Dungeon als Kind-Nodes generiert. Spieler-State (HP, Inventar, Level) bleibt erhalten.

### Dungeon-Generierung
- **Grid-basiert:** 60x60 Zellen, TILE_SIZE = 3.0
- **Räume:** 6-10 Räume, Größe 4-9 Zellen
- **Gänge:** L-förmige Korridore zwischen Räumen (Breite 2)
- **Geometrie:** CSGBox3D für Boden, Wände (Höhe 6.0), Decke, jeweils mit `use_collision`
- **Beleuchtung:** OmniLight3D pro Raum + Decken-SpotLights in Gängen
- **Environment:** Eigene WorldEnvironment mit Fog, kein Himmel

### NavMesh (Navigation)
- Pro Dungeon-Ebene wird ein `NavigationRegion3D` mit manuell gebautem `NavigationMesh` erstellt
- Positions-basierte Vertex-Deduplizierung: gleiche Position → gleicher Index → zusammenhängendes NavMesh
- Wand-Margin (0.5): Kanten an Wänden werden nach innen versetzt, damit Gegner Abstand halten
- Edge-Connection-Margin auf 0.6 gesetzt

### Portal-System
| Portal | Farbe | Funktion |
|---|---|---|
| Rückkehr-Portal | Blau | Im ersten Raum, führt eine Ebene hoch oder raus |
| Deeper-Portal | Rot/Orange | Im letzten Raum, führt eine Ebene tiefer |

- **Ebene 1:** Rückkehr-Portal → direkt zur Overworld
- **Ebene 2+:** Rückkehr-Portal → Auswahl: "Eine Ebene hoch" oder "Dungeon verlassen"
- **Interaktion:** E-Taste, Labels zeigen Ebenen-Info

### Dungeon-Persistenz
- Generierte Ebenen werden in `saved_dungeons` Dictionary gespeichert (Level → {grid, rooms})
- Beim Zurückgehen wird das gespeicherte Layout wiederhergestellt
- Beim Verlassen des Dungeons werden alle gespeicherten Ebenen gelöscht

### Gegner im Dungeon
- Spawnen in Räumen 2 bis N-1 (nicht im Start- und End-Raum)
- `mob_level = dungeon_level` (steigt mit jeder Ebene)
- Nutzen NavMesh-Pathfinding um Wände herum

---

## Geplante Features
- [ ] Skill Mastery & Fusion System (siehe Konzept oben)
- [ ] Wut-Ressource für Krieger
- [ ] Spell-System (Feuerbälle etc.)
- [ ] Schadenstypen (Physical, Fire, Ice, Lightning, Poison)
- [ ] Mehrere Gegnertypen
- [ ] Multiplayer (bis zu 6 Spieler)
- [ ] Boss-Gegner
- [ ] Item-Shop / Händler

---

## Projektstruktur
```
DungeonCrawler/
├── assets/
│   ├── Warrior+Animation/      # Spieler-Charakter + Animationen (castle_guard_01.fbx + FBX)
│   ├── Goblin+Animation/       # Gegner-Modell + Animationen (goblin_d_shareyko.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
```