Skip to content

Getting Started

Voraussetzungen

Werkzeug Im Repository belegte Version Zweck
Godot Mono 4.6.3 Godot.NET.Sdk/4.6.3, Export-Workflows und Rider-Konfigurationen
.NET SDK 8.x alle vorhandenen C#-Projekte zielen auf net8.0
Docker Engine + Compose keine Mindestversion gepinnt; Compose-v2-Syntax Nakama, PostgreSQL, Registry, Redis, Dashboard, Launcher-API
Node.js 20 im Nakama-Dockerfile TypeScript-Runtime bauen
npm passend zu Node 20 npm ci, npm run build
Git aktuelle Version Checkout
Rider (optional) nicht gepinnt vorhandene .run-Profile

Externe Dienste für lokalen Betrieb werden durch src/server/docker-compose.yaml bereitgestellt. Für reine Shared-/Unit-Tests sind Godot, Docker und externe Dienste nicht nötig.

Checkout und Restore

git clone <repository-url> holodeck-arena
Set-Location holodeck-arena
dotnet restore "src/HolodeckArena.Game3D/Holodeck Arena 3D.csproj"
dotnet restore tests/HolodeckArena.Game3D.Tests/HolodeckArena.Game3D.Tests.csproj
dotnet restore tests/HolodeckArena.Bootstrap.Tests/HolodeckArena.Bootstrap.Tests.csproj

Die bereinigte Solution kann direkt mit dotnet restore HolodeckArena.sln wiederhergestellt werden.

Lokale Konfiguration

RuntimeConfigLoader lädt in dieser Reihenfolge:

  1. res://config/client.production.json,
  2. je nach --env Staging oder Local,
  3. user://client.local.json,
  4. CLI-Overrides.

Für Local wird res://config/client.local.json verwendet, falls vorhanden, sonst res://config/client.local.example.json. Kopiere die Example-Datei nur lokal und committe keine Secrets. Die Example-Werte erwarten Nakama 127.0.0.1:7350, Registry 127.0.0.1:8080 und den lokalen Schlüssel test.

Backend starten

Lege src/server/.env mit eigenen Entwicklungswerten an:

LAUNCHER_API_TOKEN=<local-only-value>
POSTGRES_PASSWORD=<local-only-value>
NAKAMA_CONSOLE_PASSWORD=<local-only-value>
NAKAMA_CONSOLE_SIGNING_KEY=<local-only-value>
NAKAMA_SOCKET_SERVER_KEY=test

POSTGRES_PASSWORD muss nach der ersten Initialisierung des Docker-Volumes stabil bleiben. Das offizielle Postgres-Image verwendet den Wert nur beim erstmaligen Anlegen der Datenbank. Ein neuer Wert in .env passt das Kennwort der vorhandenen postgres-Rolle nicht an; Nakamas Anmeldung scheitert dann.

Dann:

Set-Location src/server/nakama/modules
npm ci
npm run build
Set-Location ../..
docker compose --env-file .env -f docker-compose.yaml config
docker compose --env-file .env -f docker-compose.yaml up --build -d
docker compose --env-file .env -f docker-compose.yaml ps

Erwartete lokale Ports: Launcher-API 5000, Registry 8080, Dashboard 8000, PostgreSQL 5432, Nakama gRPC/HTTP/Console 7349/7350/7351. Redis wird nur im Compose-Netz exponiert.

Nakama prüfen

docker compose --env-file src/server/.env -f src/server/docker-compose.yaml logs nakama

Der erfolgreiche Start loggt Holodeck Arena Nakama runtime initialized.. Der Client authentifiziert über NakamaAuthService; rpc_ping kann erst mit einer gültigen Nakama-Session über NakamaRpcService aufgerufen werden.

Game3D im Godot-Editor

  1. Importiere src/HolodeckArena.Game3D/project.godot mit Godot 4.6.3 Mono.
  2. Warte auf C#-Build und Resource-Import.
  3. Starte F6 für Tool-Szenen oder F5 für Core/Bootstrap/MainScene.tscn.
  4. Die Editor-Argumente sind bereits -- --env=local --client-profile=client_a.

project.godot legt MainScene und die Autoloads AppBootstrap, ServerBootstrap, NetworkManager, HubNetworkSync, MouseCursor und NetworkStatsOverlay fest.

Game3D direkt oder aus Rider starten

Direkt, wenn godot im PATH liegt:

godot --path src/HolodeckArena.Game3D -- --env=local --client-profile=client_a

Rider enthält Local Player 01 bis 06, Remote Player 01 bis 05 und Local Server 01/02 unter .run. Deren EXE_PATH ist maschinenspezifisch und muss lokal auf die eigene Godot-Executable zeigen. Die Working Directory muss src/HolodeckArena.Game3D bleiben.

Lokalen Headless-Server starten

godot --headless --path src/HolodeckArena.Game3D -- --env=local --server-mode --run-backend=Nakama --server-hub-id=hub_local_001 --server-port=7001 --server-max-players=5 --region=eu --server-public-host=127.0.0.1 --server-registry-url=http://127.0.0.1:8080/ --server-version=0.1.0 --server-registry-heartbeat-seconds=10

Der Server lädt HubServerScene.tscn, öffnet ENet/UDP, registriert sich bei der Registry und sendet Heartbeats. Der Client entdeckt ihn über /servers und verbindet anschließend per ENet.

Tests

dotnet test tests/HolodeckArena.Game3D.Tests/HolodeckArena.Game3D.Tests.csproj
dotnet test tests/HolodeckArena.Bootstrap.Tests/HolodeckArena.Bootstrap.Tests.csproj
python src/tools/documentation/validate_docs.py

Manuelle Godot-Prüfungen: F6 auf RoomTemplatePreview.tscn und DungeonTemplateIntegrationTest.tscn.

Erste Stolperfallen

  • Production-Konfiguration enthält absichtlich einen Platzhalter-Key und wird von RuntimeConfigValidator abgelehnt, bis ein gültiger Build-Key injiziert ist.
  • Ohne lokalen Headless-Server findet das Main Menu trotz laufendem Nakama keinen joinbaren Hub.
  • Template-Modus unterstützt nur V3; V2/Legacy benötigen GeneratedFallback.
  • Der Blank-Raum ist ein Skelett, kein bereits kataloggültiges Template; Metadaten, Bounds, Sockets und Marker müssen angepasst werden.

Weiter: Lokale Entwicklungsvarianten, Troubleshooting, Konfiguration.