Skip to content

Headless-Server

Zweck und Start

Der Headless-Prozess ist dasselbe Game3D-Projekt. ServerBootstrap erkennt --server-mode, lädt Features/Hub/Server/HubServerScene.tscn, erstellt ENetMultiplayerPeer.CreateServer und startet Registry-Heartbeat.

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

-- trennt Godot- von User-Argumenten. Für Remote-Betrieb muss server-public-host eine clientseitig erreichbare Adresse sein und UDP-Port freigegeben werden. Keine produktiven Secrets als CLI-Argumente übergeben.

Lifecycle

Start: Services → HubServerScene → ENet → Registry register/heartbeat. Peer connect/disconnect aktualisiert PlayerCount. Shutdown: Signals abmelden, Registry unregister, ENet schließen, Tokens/Services entsorgen. HubNetworkSync validiert HubDefinition und Bewegung.

Mehrere Server

Rider Local Server 01 nutzt 7001/hub_local_001, Local Server 02 muss andere Instance/Hub-ID und Port erhalten. Jeder Prozess braucht eindeutigen Port; dieselbe Registry kann mehrere Instanzen führen. MaxPlayers und Version werden in Discovery berücksichtigt.

Container/Export

Der aktive Compose-Service headless-server baut das Game3D-Projekt mit dem Export-Preset Linux Server in ein eigenes Image und startet anschließend nur das exportierte Binary. Der Export wird dadurch beim Image-Build gecacht und nicht bei jedem Containerstart wiederholt.

Set-Location src/server
docker compose up -d --build headless-server
docker compose logs -f headless-server

Für einen reinen Neustart ohne Neu-Export genügt docker compose up -d headless-server. Nach Änderungen am Game3D-Projekt muss das Image erneut gebaut werden. Standardmäßig veröffentlicht der Service UDP 7001, registriert hub_local_001 und verbindet sich innerhalb des Compose-Netzes mit nakama:7350 und registry:8080.

Folgende optionale Environment-Variablen überschreiben die lokalen Defaults: HEADLESS_SERVER_HUB_ID, HEADLESS_SERVER_PORT, HEADLESS_SERVER_MAX_PLAYERS, HEADLESS_SERVER_REGION, HEADLESS_SERVER_PUBLIC_HOST, HEADLESS_SERVER_VERSION und HEADLESS_SERVER_HEARTBEAT_SECONDS. NAKAMA_SOCKET_SERVER_KEY ist erforderlich. Für Remote-Betrieb muss HEADLESS_SERVER_PUBLIC_HOST die vom Client erreichbare öffentliche IP oder DNS-Adresse enthalten; außerdem muss derselbe UDP-Port in Firewall/NAT freigegeben sein.

Debugging

Prüfe Startlog, ENet-CreateServer-Error, Registry POST/Heartbeat, /servers, UDP-Firewall und HubHash. Bei hoher Last Network/Physics/GC profilieren; Headless darf keine UI-/Render-Abhängigkeit für Autoritätslogik benötigen. Er autorisiert Social-Hub-Bewegung sowie Dungeon-Waffen-Sessions; vollständige Run-, Encounter- und Boss-Simulation bleibt clientseitig.

Verwandt: Lokale Entwicklung, Multiplayer, Troubleshooting.

Dungeon combat authority

The headless bootstrap injects and runs DungeonCombatNetworkSync alongside hub sync. A registered ENet peer can request a V3 combat session; the server regenerates the dungeon, verifies run id/hash, validates the loadout, and owns weapon state and target health without loading weapon scenes or visual projectiles. Operational validation and current limitations are documented in Server-authoritative dungeon weapon combat.

The current hub registration still trusts the client-provided user id. Do not treat this as production authentication; add Nakama token or signed join-ticket verification before exposing competitive results.