Holodeck Arena Developer Handbook

Status: Laufend gepflegte Dokumentation des aktiven Game3D-Projekts

Dieses Handbook beantwortet, wo ein System liegt, welche Klassen den Laufzeitfluss tragen, welche Dateien bei einer Änderung betroffen sind und wie die Änderung geprüft wird. Es dokumentiert ausschließlich beobachteten Code. Nicht fertige Systeme sind als in Entwicklung, Prototyp, Legacy oder geplant markiert.

Projekt in 60 Sekunden

• Primäres Spiel: src/HolodeckArena.Game3D (Godot 4.6.3 Mono, C#, .NET 8).
• Godot-Einstieg: src/HolodeckArena.Game3D/project.godot → Core/Bootstrap/MainScene.tscn.
• Fachliche, Godot-freie Logik: src/HolodeckArena.Shared.
• Netzwerk-Helfer: src/HolodeckArena.Networking.
• Backend: Nakama/TypeScript, Registry/FastAPI, Dashboard/FastAPI und Redis/PostgreSQL unter src/server.
• Game2D: aus dem aktuellen Arbeitsbaum entfernt; keine neuen Features daf?r anlegen.
• Aktiver Dungeon: V3-Generator plus handgebaute 3D-Raumtemplates.
• Waffen/Progression: vier technische Startwaffen sind in den aktiven Combat-Run integriert; finale Modelle und Backend-Persistenz bleiben Ausbaupunkte.
• Replay: lokale Combat-Aufzeichnung, Chunk-/Streaming-Upload, serverseitige Validierung, Manual Leaderboards und Playback sind aktiv; Seek und vollständige Re-Simulation bleiben Ausbaupunkte.

Quickstart

1. Getting Started – Voraussetzungen, lokaler Stack, Godot, Rider, Client und Server.
2. Lokale Entwicklungsvarianten – nur Client, mehrere Clients, Nakama und kompletter Stack.
3. Solution-Übersicht – Zweck und Änderungsstatus jedes Bereichs.
4. Architektur – System-, Run-, Waffen- und Raumfluss.
5. Änderungsmatrix – vom Änderungswunsch direkt zu Code und Tests.

Navigation

Grundlagen

• DDD-/TDD-Migrationsanalyse
• Getting Started
• Solution und Repository
• Architektur
• Konventionen
• Lokale Entwicklung
• Debugging und Profiling
• Tests
• Build und Deployment

Game3D-Systeme

• Game3D-Überblick und Lifecycle
• Dungeon-Runs und Objectives
• Run Completion, Medaillen und Run-Historie
• Dungeon-Generierung und Raumtemplates
• Encounters, Gegner und Bosse
• Waffen, Loadouts, Progression und Mastery
• Multiplayer
• Social Hub und UI
• Replay und Leaderboards
• Power-ups und Character Stats
• Combat-Balance und Arcade-Profil
• Balancing-Sandbox
• Phase 1: Combat Vertical Slice
• Phase 2: Run Authority

Backend und Betrieb

• Backend-Überblick
• Nakama und RPC-Entwicklung
• Registry, Dashboard und Redis
• Headless-Server
• CI/CD und Releases
• Troubleshooting

How-tos

• Dungeon-Raum erstellen
• Raumtemplate registrieren
• Gegner erstellen
• Encounter erstellen
• Boss erstellen
• Waffe erstellen
• Waffen-Modifikation erstellen
• Mastery-Perk erstellen
• Player-Unlock erstellen
• Run-Objective ändern/erweitern
• Run-Modus ergänzen
• Nakama-RPC ergänzen
• Replay-Ereignis ergänzen
• UI-Screen ergänzen
• Input Action ergänzen
• Automatisierten Test ergänzen
• Drop-/Power-up-Visual zuweisen

Referenzen

• Wichtige Pfade
• Zentrale Klassen und Services
• Szenen und Autoloads
• Konfiguration und CLI
• IDs, Events und Signals
• Änderungsmatrix
• System Map
• Glossar

Wichtigste Regeln

1. Neue Features nur in Game3D/Shared/Networking/Backend implementieren, nicht in historischen 2D-Pfaden.
2. Replay-, Score- und Generatorlogik verwendet stabile IDs, Versionen und deterministische Zufallsquellen.
3. Ein gespeichertes PlayerLoadout wird nie direkt ausgeführt; zuerst ILoadoutValidator.CreateValidated verwenden.
4. Godot-Typen bleiben aus Shared-Domain-Modellen heraus.
5. Nakama vergibt Fortschritt, Score oder Mastery nicht aufgrund ungeprüfter Clientwerte.
6. Neue Katalogeinträge erhalten Validierung und Tests; neue Scenes werden zusätzlich in Godot manuell geprüft.
7. Secrets gehören in lokale .env-/user://-Konfiguration oder CI-Secrets, nie in Markdown oder Git.
8. Nach Dokumentationsänderungen python src/tools/documentation/validate_docs.py ausführen.

Historische Snapshots, Uebergabeberichte und redundante Root-Dokumente wurden entfernt. Massgeblich sind dieses Handbook, die Seiten unter docs/development und der aktuelle Code.