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)

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)

---

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