mmo/CLAUDE.md

MMO Projekt

Überblick

Community-MMO in Godot 4.6 (Forward+, Jolt Physics). Vision in doc/_core.md, Features in doc/features.md.

Sprache

Der User kommuniziert auf Deutsch. Code und Variablen auf Englisch. Kommentare nur wo nötig.

Code-Style

• GDScript mit 2 Spaces Einrückung
• Explizite Typen wo der Inferenzer scheitert (Ergebnisse von Variant-Funktionen, Helper-Returns die Node sein könnten)
• Keine Debug-Prints im finalen Code
• Keine emoji

Architektur

Autoloads (autoloads/)

• EventBus — alle Signals (Combat, Wave, Inventory, Dialog, Chat, …)
• Net — ENet P2P Multiplayer-Manager (Singleplayer = OfflineMultiplayerPeer)
• Stats — zentrale Registry: register(entity, base_resource) / get_stat / set_stat
• GameState — Wave#, Scene-Pfade, Run-Seed, Pause, Dungeon-Seed
• SaveLoad — JSON-basierte Persistenz (Stub für später)

Resources (resources/)

• stats/ — BaseStats + Player/Enemy/Boss/Portal/Gate/Village/Building Stats
• abilities/ — Ability + AbilitySet (3 Klassen × 5 Abilities, im RoleSystem in Code aufgebaut)
• items/ — Item, Recipe (Crafting in CraftingSystem in Code)
• buildings/ — Building Resource (Blueprints in BuildingSystem in Code)
• npcs/ — NpcProfile (Lore + Personality für Ollama)
• effects/ — Effect Resource + Element (NONE, FIRE)

Szenen (scenes/)

• menu/ — main_menu, lobby, options_menu
• world/ — world.tscn (Dorf-Welt mit Village + alle Systeme als Children)
• dungeon/ — dungeon.tscn (procedural generation via dungeon_generator.gd)
• entities/ — player, enemy, gate, portal, building, loot, npc, village
• hud/ — hud.tscn (alles-in-einem: vitals, abilities, chat, minimap, inventory, crafting, build, dialog, map, pause, game over)

Systeme (systems/)

Alle als Children unter World/Systems und Dungeon/Systems instanziert:

• Combat: HealthSystem, ShieldSystem, RespawnSystem, CooldownSystem, AbilitySystem, AutoAttackSystem
• Effects: EffectSystem, ElementSystem, AggroSystem, RoleSystem
• World: SpawnSystem, WaveSystem, InvasionSystem, XpSystem, LootSystem
• Player: InventorySystem, CraftingSystem, BuildingSystem
• Social: NpcSystem, DialogSystem (Ollama HTTP), ChatSystem, MapSystem, AudioSystem

Multiplayer-Pattern

• ENet P2P, Host-Authoritative
• Singleplayer = Net.host_singleplayer() (OfflineMultiplayerPeer)
• Player-Entities tragen Authority des jeweiligen Peers (_enter_tree() → set_multiplayer_authority(name.to_int()))
• Stats/Damage/Spawn/Wave/XP/Inventory laufen nur am Host (if not multiplayer.is_server() and multiplayer.multiplayer_peer != null: return)
• Client-Aktionen via RPC zum Host: _request_*.rpc_id(1, ...) → Host validiert + sync via MultiplayerSpawner und MultiplayerSynchronizer
• Sync-Felder pro Entity über MultiplayerSynchronizer mit SceneReplicationConfig

Input-Map

• WASD + Space: Move + Jump
• 1–4: Abilities (im Build-Mode: Bauteil-Auswahl)
• ALT+1/2/3: Tank/Damage/Healer
• Tab: Cycle target | LMB: Click target | RMB: Camera drag (capture mouse)
• I: Inventory | C: Crafting | B: Build mode | M: Map | Y: Chat | E: Interact (NPC)
• R: Rotate building preview
• Escape: Pause / Cancel UI

Dialog (Ollama)

• HTTP localhost:11434/api/generate, Modell mistral-nemo
• Pro NPC: System-Prompt aus lore + personality
• Fallback: npc.fallback_text wenn Ollama nicht erreichbar — Spiel bleibt voll spielbar

Bauen

• Grid-Snap 1m, 4 Bauteile (Floor, Wall, Door, Roof)
• LMB im Build-Mode platziert, MMB entfernt
• Material-Verbrauch aus Crafting-Items (alle aus wood, das aus essence gecrafted wird)
• Persistenz via Host (Buildings sind echte Nodes unter EntityRoot/Buildings, MultiplayerSpawner repliziert)

Wave-Loop

1. WaveSystem startet 10-min Timer, spawnt 3 normale + 1 rotes Gate
2. Gate stirbt → spawnt Portal an gleicher Position
3. Spieler betritt Portal → Dungeon (procedural, 5–8 Räume + Boss)
4. Boss-Tod → Welt-Rückkehr; rotes Portal → Wave++ + alle Stats skalieren
5. Timer 0 ohne rotes Portal → Invasion (8+wave×2 Mobs zur Village)
6. Village 0 HP → Game Over → Hauptmenü

Workflow mit dem User

• Erst planen (doc/ lesen), dann implementieren
• Schrittweise, modulares Aufbauen — nicht alles auf einmal umbauen
• Nach Änderungen: godot-4 --headless --quit-after 60 res://scenes/world/world.tscn um Parse-/Runtime-Fehler zu sehen
• doc/ nicht anfassen — das ist die User-Spec

Smoke-Test

• godot-4 --headless --import → Kein Error
• godot-4 --headless --quit-after 600 res://scenes/world/world.tscn → Kein Error
• godot-4 --headless --quit-after 600 res://scenes/dungeon/dungeon.tscn → Kein Error

Bekannte Lücken / TODOs

• Ollama muss installiert werden (Modell mistral-nemo erwartet) — Stub-Fallback funktioniert sonst
• Save/Load Slots im Hauptmenü (Autoload existiert, UI fehlt)
• Multiplayer Late-Join: Building-/Wave-State wird beim spätem Beitritt nicht synchronisiert
• Damage Numbers / Hit FX / Particle Effects fehlen (rein Polish)