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, Stats & Level-System

Vollständige Dokumentation in 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 (Schadensberechnung, Autoattack, Skills, GCD) Skills entwickeln sich über das SKILL_SYSTEM.md weiter.

Global Cooldown (GCD)

Formel: GCD = Waffen-Attackspeed / (1 + Haste)

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)

---

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

---

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