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 – 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
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)
├── PlayerModel (warrior.fbx — Mixamo Charakter mit Skeleton + AnimationPlayer)
├── CollisionShape3D
├── CameraPivot (Node3D)
│   └── Camera3D
├── HUD (hud.tscn)
├── CharacterPanel (character_panel.tscn)
├── InventoryPanel (inventory_panel.tscn)
├── LootWindow (loot_window.tscn)
└── SkillPanel (skill_panel.tscn)

enemy.tscn

Ein Gegner mit Level-basiertem Stats-System.

Enemy (CharacterBody3D)
├── EnemyModel (warrior.fbx — Mixamo Charakter mit Skeleton + AnimationPlayer)
├── 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, Krieger/Schurke)

• 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
• 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
• Icons werden beim Spielstart geladen
• Cooldown-Anzeige: Dunkle Überlagerung + verbleibende Zeit
• Gelber Highlight-Rand beim Drag über Slots

---

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

---

Animations-System

Mixamo-Integration

Charaktermodelle stammen von Mixamo (warrior.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
3. Die Animation wird extrahiert und der AnimationLibrary hinzugefügt
4. _update_animation() wählt basierend auf Bewegungszustand die passende Animation

Verfügbare Animationen (assets/animations/)

Animation	Datei	Verwendung
walk	Walking.fbx	Vorwärts laufen
walk_back	Walking Backwards.fbx	Rückwärts laufen
strafe_left	Left Strafe Walking.fbx	Links seitwärts
strafe_right	Right Strafe Walking.fbx	Rechts seitwärts
jump	Jumping.fbx	Springen
autoattack	Autoattack.fbx	Autoattack / Zauberstab
heavy_strike	Heavy Strike.fbx	Heavy Strike Skill
die	Dying Backwards.fbx	Tod (Spieler + Gegner)

Offene Punkte

• Enemy Walk-Animation: Track-Pfade matchen noch nicht korrekt (Debug in Arbeit)
• Idle-Animation fehlt (kein FBX vorhanden)
• Cast-Animation fehlt (für Frostblitz)

---

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 und Animationen
│   ├── models/              # Mixamo Charakter-Modelle (warrior.fbx + Texturen)
│   ├── animations/          # Mixamo Animationen (Walking, Attack, etc.)
│   └── kenney_blocky-characters_20/  # Kenney Block-Chars (nicht mehr aktiv)
├── 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
│   ├── frostbolt_icon.svg
│   ├── wand_icon.svg
│   └── wooden_staff_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
├── skill_panel.gd           # Fähigkeiten-Panel Script
├── skill_panel.tscn         # Fähigkeiten-Panel Scene
├── world.gd                 # Welt-Script
├── world.tscn               # Hauptszene
└── PROJEKTDOKU.md           # Diese Dokumentation