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