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) |
| RMB gehalten | Kamera drehen, Spieler schaut mit |
| Linksklick auf Gegner | Ziel markieren |
| Rechtsklick auf Gegner | Ziel markieren + Autoattack starten |
| 1 | Autoattack manuell starten |
| 2 | Heavy Strike (starke Attacke) |
| 3 – 9 | Aktionsleiste Slots (Consumables/Items) |
| C | Charakter-Panel (Stats + Equipment) |
| I | Inventar öffnen/schließen |
| Leertaste | Springen |
| T | (Test) 10 Schaden am Spieler |

---

## Szenen-Struktur

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

### player.tscn
Der Spielercharakter mit allen UI-Panels.
```
Player (CharacterBody3D)
├── [Kenney GLB Modell]
├── CollisionShape3D
├── CameraPivot (Node3D)
│   └── Camera3D
├── HUD (hud.tscn)
├── CharacterPanel (character_panel.tscn)
├── InventoryPanel (inventory_panel.tscn)
└── LootWindow (loot_window.tscn)
```

### enemy.tscn
Ein Gegner mit Level-basiertem Stats-System.
```
Enemy (CharacterBody3D)
├── [Kenney GLB Modell]
├── CollisionShape3D
├── Area3D
│   └── CollisionShape3D
├── NavigationAgent3D
└── HealthLabel (Label3D)
```

---

## 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 * N` XP (Level 2: 100, Level 3: 200, ...)
- **Stats pro Level:** Basierend auf Klassen-Zuwachsraten
- **HP bei Level-Up:** Werden vollständig aufgefüllt (HP + Klassen-Ressource)
- **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 |

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

---

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

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

### Skills

#### Autoattack (Taste 1)
- **Schaden:** Waffenschaden oder klassenabhängig unbewaffnet + Main-Stat Bonus
- **Cooldown:** GCD (Waffen-Attackspeed / Haste)
- **Reichweite:** Waffen-Reichweite oder 3.0 (unbewaffnet)
- Automatisch per Rechtsklick oder manuell per Taste 1

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

### UI & Icons
- Aktionsleiste mit 9 Slots (Taste 1-9)
- Icons werden beim Spielstart geladen
- Cooldown-Anzeige: Dunkle Überlagerung + verbleibende Zeit
- Alle Slots per Maus klickbar

---

## Gegner-System (enemy.gd)

### Stats
Level-basiert mit automatischer Skalierung:

| Stat | Formel |
|---|---|
| Stärke | base_strength + (level-1) * 2 |
| Ausdauer | base_stamina + (level-1) * 3 |
| Rüstung | base_armor + (level-1) * 2 |
| HP | Ausdauer * 10 |
| Schaden | Stärke * 0.5 + 2 |
| XP-Belohnung | 25 * Level |

### KI-Verhalten (State Machine)
| State | Beschreibung |
|---|---|
| PATROL | Zufällig im Radius um Spawn-Position herumlaufen |
| CHASE | Spieler verfolgen (Aggro-Range: 8.0) |
| ATTACK | Angreifen wenn in Reichweite (1.5) |

### Respawn
- Gegner spawnen nach 5 Sekunden am Ursprungsort neu
- Verwaltet durch world.gd

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

---

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

---

## Geplante Features
- [ ] Wut-Ressource für Krieger
- [ ] Ressourcen-System für Gegner (nicht alle haben Mana)
- [ ] 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/                  # 3D-Modelle (Kenney GLB)
├── classes/                 # Klassen-Definitionen (.tres)
│   ├── warrior.tres         # Krieger (Ressource: NONE)
│   ├── rogue.tres           # Schurke (Ressource: ENERGY, 100)
│   └── mage.tres            # Magier (Ressource: MANA, 100)
├── 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
├── loot_tables/             # Loot-Tabellen (.tres)
│   ├── goblin_loot.tres
│   └── skeleton_loot.tres
├── icons/                   # Icons (SVG)
│   ├── autoattack_icon.svg
│   ├── heavy_strike_icon.svg
│   ├── iron_sword_icon.svg
│   ├── steel_sword_icon.svg
│   ├── leather_chest_icon.svg
│   ├── iron_helm_icon.svg
│   ├── wooden_shield_icon.svg
│   ├── hp_potion_icon.svg
│   └── mana_potion_icon.svg
├── camera_pivot.gd          # Kamera-Script
├── character_class.gd       # CharacterClass Resource (inkl. ResourceType)
├── character_panel.gd       # Charakter-Panel Script (Icon-Grid)
├── character_panel.tscn     # Charakter-Panel Scene
├── class_selection_menu.gd  # Klassenauswahl Script
├── class_selection_menu.tscn # Klassenauswahl Scene
├── consumable.gd            # Consumable Resource
├── enemy.gd                 # Gegner-Script
├── enemy.tscn               # Gegner-Scene
├── equipment.gd             # Equipment Resource
├── hud.gd                   # HUD-Script (inkl. ResourceBar)
├── hud.tscn                 # HUD-Scene
├── inventory.gd             # Inventar Resource
├── inventory_panel.gd       # Inventar-Panel Script
├── inventory_panel.tscn     # Inventar-Panel Scene
├── loot_entry.gd            # LootEntry Resource
├── loot_table.gd            # LootTable Resource
├── loot_window.gd           # Loot-Fenster Script
├── loot_window.tscn         # Loot-Fenster Scene
├── main_menu.gd             # Hauptmenü Script (Einstellungen)
├── main_menu.tscn           # Hauptmenü Scene
├── player.gd                # Spieler-Script (inkl. Ressourcen, Aktionsleiste)
├── player.tscn              # Spieler-Scene
├── world.gd                 # Welt-Script
├── world.tscn               # Hauptszene
└── PROJEKTDOKU.md           # Diese Dokumentation
```