Void-Bastion/ONLINE_SETUP.md

Void Bastion Online 0.23

Fertiger Stand

Das Spiel nutzt den offiziellen Nakama-Godot-Client 3.4.0. Beim normalen Start wird automatisch ein app-eigenes Gastkonto angemeldet. Das lokale Profil bleibt auch offline nutzbar; neue Bestwerte werden gespeichert und bei der nächsten erfolgreichen Verbindung nachgereicht.

Spielernamen werden lokal und serverseitig auf 3 bis 20 erlaubte Zeichen geprüft. Reservierte Bezeichnungen wie ADMIN, GERGAMES, MODERATOR, SUPPORT und SYSTEM sind gesperrt. Ranglisten schreiben den öffentlichen Namen und lösen beim Anzeigen den aktuellen Profilnamen über die Spieler-ID auf; dadurch wird keine technische Gast-ID gezeigt und eine spätere Namensänderung gilt auch für ältere Bestwerte. Im Pilotenprofil kann das aktuell angemeldete Online-Konto nach einer zweiten ausdrücklichen Bestätigung gelöscht werden; anschließend verwirft das Spiel die lokale Identität und erstellt ein neues Gastprofil.

Der Unraid-Stack besteht aus:

• Nakama 3.37.0 mit eigener JavaScript-Serverlogik
• PostgreSQL 16 ohne öffentlich freigegebenen Datenbank-Port
• täglichem komprimiertem Backup mit 14 Tagen Aufbewahrung
• ausschließlich lokal erreichbarer Nakama-Verwaltungskonsole
• getrennten zufälligen Schlüsseln für Sitzungen, Sitzungserneuerung, Verwaltung und Server-RPCs

Ranglisten

Es existieren 36 autoritative Ranglisten: vier Spielarten mal drei Karten mal drei Schwierigkeitsgrade. Der Client kann nicht direkt in diese Ranglisten schreiben. Ergebnisse laufen durch submit_run; Karte, Schwierigkeit, Modus, Welle und eine großzügige Plausibilitätsgrenze für die Punktzahl werden vor dem Eintrag geprüft.

Die Kennungen folgen diesem Muster: mission_map0_difficulty0.

Mögliche Spielarten sind mission, endless, coop_ai und coop_online.

Interne Nutzungsstatistik

Nach jeder erfolgreichen Anmeldung meldet der Client Plattform und App-Version an die Serverfunktion record_activity. Pro Konto wird nur ein pseudonymer Aktivitätsdatensatz mit erstem und letztem Aktivitätstag gespeichert. Daraus führt Nakama zusammengefasste Werte für registrierte und täglich aktive Spieler sowie die Verteilung nach Plattform und Version.

Die Serverfunktion private_stats ist ausschließlich über den geheimen Nakama-HTTP-Schlüssel für die geschützte, nicht verlinkte Statistikseite der Homepage erreichbar. Angemeldete Spielclients können diese Werte nicht abrufen. Der geheime Schlüssel bleibt auf Unraid und im privaten Webhosting-Verzeichnis; er wird weder exportiert noch im Repository gespeichert.

Die geschützte Statistikseite kann außerdem Freischaltcodes für alle Türme, alle Karten oder beides erstellen. create_unlock_code ist nur Server-zu-Server mit dem Nakama-HTTP-Schlüssel verfügbar. Codes werden über ihren SHA-256-Schlüssel nachgeschlagen; zusätzlich liegt der Klartextcode für die geschützte Admin-Übersicht in einem privaten Nakama-Speicherobjekt mit permissionRead:0 und permissionWrite:0. Das Spiel kann diese Objekte nicht lesen. list_unlock_codes liefert Code, Freischaltumfang, optionale Bemerkung, Erstellungszeit und Einlösungszähler ausschließlich für Server-zu-Server-Aufrufe zurück. Die Statistikseite zeigt daraus „Offen“, „Teilweise eingelöst“ oder „Eingelöst“; die Bemerkung ist optional und auf 160 Zeichen begrenzt. Hinweise können z. B. Empfänger beschreiben und sollten keine unnötigen privaten Daten enthalten. Bereits vor dieser Erweiterung erzeugte Codes behalten ihren Status, aber ihr Klartext kann nicht rekonstruiert werden.

Das Einheiten-Balancing liegt einheitlich im privaten Nakama-Speicher (game_balance/global). Die geschützte Statistikseite liest und ändert es über die nur mit NAKAMA_HTTP_KEY aufrufbaren RPCs get_game_balance und set_game_balance; der HTTP-Schlüssel wird nie an Clients ausgeliefert. Angemeldete Spielclients rufen get_game_balance beim Start auf, cachen die letzte gültige Konfiguration lokal und verwenden sie auch offline. Jede neue Online-Partie lädt dieselbe Konfiguration serverseitig bei matchInit; bereits laufende Partien bleiben unverändert. Falls der Server unerreichbar ist, gelten der letzte lokale Cache bzw. die eingebauten Ausgangswerte. Änderung des Balancings erfordert dadurch keine neue Spiel-EXE, aber das Runtime-Bundle auf dem Nakama-Server und die interne PHP-Seite müssen zunächst aktualisiert werden.

server/nakama/tests/balance_duel_test.js ist ein reproduzierbarer Referenztest, der die echte Nakama-Kampf-Simulation nutzt und alle zulässigen Turm-/Gegner-Kombinationen sowie den ersten Boss bewertet. Er ist ein gezielter 1-gegen-1-Wegtest (ein Level-1-Turm, keine Upgrades/Unterstützung), kein Ersatz für komplette Wellen- und Spielertests. Ergebnisse daher als Warnsignal und Vergleich zwischen Versionen verwenden, nicht als alleinige automatische Balancing-Entscheidung.

Pro Konto gelten höchstens zehn Codeversuche in fünf Minuten. Die Spieler lösen Codes im Menü über redeem_unlock_code ein; die Freischaltungen liegen am Onlinekonto und werden nach einer Anmeldung über get_promo_unlocks wiederhergestellt. Für die Codeverwaltung müssen sowohl das Nakama-Runtime-Bundle als auch die PHP-Statistikseite aktualisiert werden. Der Nakama-HTTP-Schlüssel bleibt ausschließlich auf Unraid und im privaten Webhosting-Verzeichnis.

Im Hauptmenü ist eine Ranglistenansicht für die aktuell gewählte Karte und Schwierigkeit eingebaut. Sie zeigt Mission und Endlosmodus getrennt, löst aktuelle öffentliche Profilnamen auf und hebt den eigenen Eintrag hervor.

Multiplayer

Die Godot-Anbindung öffnet nach der Anmeldung eine WSS/WS-Echtzeitverbindung. Die schnelle Spielersuche vermittelt exakt zwei passende Spieler. Alternativ erstellt ein Spieler einen privaten Raum mit einem sechsstelligen Code, dem der zweite Spieler gezielt beitritt.

Vor dem Start zeigt eine gemeinsame Lobby beide Pilotennamen und ihre zugewiesene Verteidigungsseite. Erst wenn beide Spieler ihren Bereit-Status bestätigt haben, beginnt die Partie. Bei einem kurzzeitigen Verbindungsabbruch bleibt der Spielerplatz 60 Sekunden reserviert, die Simulation pausiert und der Client versucht automatisch, demselben Match wieder beizutreten.

Der autoritative Matchserver verwaltet Spielerplätze, getrennte Energie, Türme, Gegner, Wellen und die gemeinsamen Reaktorleben. Beide Clients erhalten denselben geprüften Spielzustand. Der lokale KI-Koop bleibt unabhängig davon spielbar.

Sprache und Freunde (in Entwicklung)

Unter Einstellungen kann zwischen Deutsch und Englisch gewechselt werden. Die Wahl liegt in der lokalen Datei user://void_bastion_settings.cfg und bleibt nach einem Neustart erhalten. Hauptmenü, Kartenwahl, Koop- und Freundesbereich sowie die wichtigsten Spiel-, Shop- und Ergebnisansichten sind übersetzt. Einzelne ältere Status- und Fehlermeldungen können noch auf Deutsch erscheinen; vor einer internationalen Veröffentlichung ist ein vollständiger Sprachdurchlauf nötig.

Die Freundesliste verwendet die Nakama-Freundschaftsfunktionen: Eine Anfrage wird über die eindeutige Spielerkennung gesendet und muss von der anderen Seite angenommen werden. Nur bestätigte Freunde zeigen Online- bzw. Im-Spiel-Status. Der Status ist grob (menu oder playing), ohne Karten-, Wellen- oder Standortdaten. Ein privater Raum kann nur vom Raumersteller an bestätigte Freunde eingeladen werden. Die Serverfunktion invite_friend prüft Raum und Freundschaft, begrenzt wiederholte Einladungen und sendet eine flüchtige Systembenachrichtigung mit Raumcode. Es gibt keinen Chat und keinen frei formulierten Nachrichtentext. Für diese Funktion müssen Client und Nakama-Runtime gemeinsam auf den neuen Stand gebracht werden; sie ist mit dem lokalen Test allein noch nicht live.

Adressen

• Produktion: https://api.void-bastion.gergames.de und wss://api.void-bastion.gergames.de
• Entwicklung im Heimnetz: http://192.168.178.20:7350 und ws://192.168.178.20:7350

In Debug-Builds versucht das Spiel nach einer fehlgeschlagenen Produktionsverbindung automatisch den Heimnetz-Server. Release-Builds verwenden ausschließlich HTTPS/WSS.

Die öffentliche Freischaltung ist abgeschlossen: Der autoritative DNS-Eintrag api.void-bastion.gergames.de zeigt als CNAME auf bs6o73mrdi3e60p0.myfritz.net; Reverse Proxy, HTTPS/WSS und das automatisch erneuerte Let’s-Encrypt-Zertifikat sind aktiv.

Tests

• Offline-/Gameplaytest: godot --headless --path . --script res://tests/smoke_test.gd
• Online-Zustands-/Interpolationstest ohne Server: godot --headless --path . res://tests/online_snapshot_test.tscn
• echter Onlinetest im Heimnetz: godot --headless --path . --script res://tests/online_integration_test.gd
• Produktionstest: VOID_BASTION_TEST_HOST=api.void-bastion.gergames.de VOID_BASTION_TEST_SCHEME=https VOID_BASTION_TEST_PORT=443 godot --headless --path . --script res://tests/online_integration_test.gd

Der Onlinetest prüft zwei Gastanmeldungen, Änderung und Ablehnung von Spielernamen, die Löschung eines eigens erzeugten Wegwerf-Testkontos, RPC, Ergebnisannahme, Ranglistenabruf, zwei WebSocket-Verbindungen, schnelles Matchmaking, die Bereit-Lobby, autoritative Spielzustände sowie Erstellen, Verlassen und Wiederbeitreten eines privaten Raums per Code.

Bei einem stockenden Onlinespiel schreibt der Client jetzt einen fortlaufenden Diagnosebericht pro Partie. Im Online-Pausemenü kann der Bericht mit DIAGNOSE KOPIEREN vollständig in die Zwischenablage kopiert werden. Er enthält Zehn-Sekunden-Werte und einzelne Hänger-/Verbindungsereignisse, aber keine Spielernamen, Raumcodes oder Kontenkennungen. Für Ablauf und Auswertung auf zwei PCs siehe ONLINE_DIAGNOSE.md.

Der Client fasst bei Rückstau maximal fünf eingetroffene Spielstände zusammen: Nur der neueste Zustand wird angewendet, die Schusseffekte dieser wenigen Pakete bleiben erhalten. Ältere, verworfene Zustände sind nur noch historische Zwischenbilder. coalesced und queue_dropped im Diagnosebericht trennen zusammengefasste von wegen voller Warteschlange verworfenen Zuständen. Weg- und Baufeldgeometrie wird nur beim Karten- bzw. Arenenwechsel neu berechnet. Der lokale Snapshot-Test prüft außerdem, dass Geschosse nach einem langen Bildaussetzer ihr Ziel erreichen und verschwinden.

Der Server meldet mit ONLINE DIAG tick_gap_ms verspätete Match-Ticks über 250 ms und mit ONLINE DIAG loop_ms eine Verarbeitung über 70 ms. Die Meldungen enthalten nur Ticknummer und Objektanzahl. Wenn beim Client Paketlücken auftreten, aber zur gleichen Zeit keine Tick- oder Loop-Warnung auf dem Server, liegt die Suche als Nächstes bei WebSocket-Verbindung und Reverse Proxy.