Void-Bastion/README.md

# Void Bastion - Alpha 0.1.0

Ein plattformübergreifender 2D-Tower-Defense-Prototyp für Godot 4. Der aktuelle Stand ist für Windows, Android und später iOS ausgelegt.

## Enthalten

- sieben auswählbare realistische Weltraumkarten im Querformat; vier zusätzliche Sektoren werden im internen Shop mit Kernkristallen freigeschaltet
- Kartenkatalog mit vier Sektoren pro Seite, persistent gespeicherten Freischaltungen und direktem Shop-Einstieg bei gesperrten Karten
- vollständig sichtbare Einsatzkarten ohne Scrollen, Minikarte oder Richtungstasten
- hellere, kontrastreichere Stationskarten und eigens gestaltete modulare Metallfahrbahnen mit realistischen Materialtexturen auf Geraden und Kurven, Führungsschienen, gebürsteten Paneelen, cyanfarbenen Energieleitungen, farbigen Reflexionen, Schraubpunkten, warmen Positionslichtern und dezenten Lichtkegeln
- feste Benutzeroberfläche mit 1600 × 900 Referenzauflösung
- eine exakt eine Rasterzelle (80 Pixel) breite Straße, die direkt aus den Wegdaten gezeichnet wird
- sichtbare Straßenmitte, Gegner-Lauflinie und gesperrte Bauzellen verwenden auf jeder Karte dieselbe Datenquelle und können deshalb nicht mehr gegeneinander verrutschen
- deutlich längere Wendeschleifen auf Bastion Prime und der Helios-Werft, damit mehr Baufläche taktisch relevant wird
- sichtbares 80-Pixel-Bauraster mit automatischem Einrasten der Türme
- jede geeignete Plattformzelle ist bebaubar; ausschließlich Wegzellen, Reaktoren und Bereiche außerhalb der Plattform sind gesperrt
- neu erzeugte, straßenfreie HD-Kartenbasen mit 3344 × 1882 Pixeln und Mipmaps für eine schärfere Windows-Darstellung
- sechs Türme: Kinetik, Laser, Rakete, Plasma, EMP-Puls und Railgun
- neun Gegnerklassen mit Luft- und Bodeneinheiten: Jäger, Fregatte, Kreuzer, Abfangjäger, Schildkreuzer, Luft-Belagerer, schneller Boden-Rover, Panzer und schwerer Läufer
- neue Bodeneinheiten-Grafiken mit leuchtend grünen Warnmarkierungen und Energielichtern
- Zielprioritäten für Türme: erste, letzte, höchste verbleibende Hülle oder Schildziele zuerst; Laser priorisiert Schilde immer automatisch
- Luft-/Bodenvorschau wird durch gleich gestaltete grüne Pfeile unterschieden: Luft nach oben, Boden nach unten
- Schildgegner haben einen blauen, gegen den Uhrzeigersinn abnehmenden Schildring; Lasertreffer bauen zuerst Schildpunkte ab und übertragen Überschuss auf die Hülle
- sechs Türme mit klar ausgewiesenen Zielen: Boden, Luft oder beide Kategorien; universelle Türme verursachen reduziert Schaden
- HUD-Vorschau mit kleinen Einheitensymbolen und Stückzahl für aktuelle und nächste Welle
- Entwickler-Testregler für Gegner-Lebenspunkte (F9 ein-/ausblenden, +/− verändern; Faktor 0,5×–3,0×, im Online-Koop deaktiviert)
- 15 automatisch skalierende Missionswellen
- drei wählbare Schwierigkeitsgrade: Leicht behält die bisherige Kurve; Schwer startet knapper und erhöht ab Missionsmitte Gegnerhülle, Gegnerzahl und fortgeschrittene Gegnertypen stärker
- höhere Schwierigkeitsgrade beginnen mit knapperen Ressourcen und belohnen einen Kartensieg mit mehr Kernkristallen
- freiwilliger Endlosmodus nach Welle 15 mit unbegrenzt weiter skalierenden Gegnern
- das Ende eines Endloslaufs zählt ausdrücklich nicht als gescheiterte Mission
- Kommandoschiff-Boss in jeder fünften Welle
- Platzierung per Maus oder Touch
- dreistufiges interaktives Einstiegstutorial
- Platzierungsvorschau mit gültiger beziehungsweise ungültiger Bauposition
- Turmverbesserungen bis Stufe 3 und Verkauf
- sichtbarer Reichweitenkreis bereits vor der Platzierung
- Turmkarten mit Schaden, Schüssen pro Sekunde, Reichweite sowie Einzel- oder Flächenschaden
- Upgrade-Vorschau mit dem konkreten Zuwachs an Schaden, Feuerrate und Reichweite
- kompaktes Turm-Informationsfenster, damit möglichst wenig von der Karte verdeckt wird
- korrigierte Zielausrichtung des Kinetik-Geschützes
- zusätzliche sinnvolle Bauplätze auf Bastion Prime, insbesondere zwischen den Wegschleifen und auf der linken Plattform
- zusätzliche Bauplätze zwischen den parallelen Fahrbahnen der Helios-Werft
- feste Reaktor-Sperrzonen auf allen Karten; auf Reaktoren und offenen Reaktorkammern wird kein Bauraster angezeigt und es können dort keine Türme platziert werden
- auf eine Rasterzelle verkleinerte Turmdarstellung, damit angrenzende Türme nicht in die Fahrbahn hineinragen
- dauerhaft gespeicherte Kernkristalle als spätere Freischaltwährung
- Nova-Arkologie (24), Cryo-Schleuse (32), Solarforge (40) und Vestige-9 (48) als kaufbare Einsatzsektoren
- dauerhaftes lokales Gastprofil mit stabiler Spieler-ID als Grundlage für Apple-, Google- und Windows-Anmeldung
- eigene Profilansicht mit lokalen Missions- und Endlosbestwerten pro Karte
- frei wählbarer Spielername mit identischer Prüfung im Spiel und auf dem Server
- zweistufige Kontolöschung direkt im Pilotenprofil; danach wird ein neues lokales Gastprofil erstellt
- direkter Datenschutz-Link im Pilotenprofil
- sichtbare App-Version und vorbereitete Support-Mail an `support@gergames.de` im Pilotenprofil; Version, Plattform und gekürzte Spieler-ID werden für eine schnellere Fehlerzuordnung eingesetzt
- wartende, lokal gespeicherte Highscore-Einträge für die spätere sichere Serverübertragung
- eigener Multiplayerbereich mit schneller Spielersuche sowie privaten Koop-Räumen mit sechsstelligen Raumcodes
- gemeinsame Online-Lobby mit Spielernamen, festen Verteidigungsseiten und manuellem Bereit-Status für beide Piloten
- reservierter Spielerplatz und automatische Wiederverbindung bei einem kurzzeitigen Netzverlust; die laufende Partie wartet bis zu 60 Sekunden
- Vorschau einer symmetrisch gespiegelten Zwei-Spieler-Arena mit gemeinsamem Reaktor
- getrennte Ressourcenmodelle für beide Koop-Spieler sowie gemeinsam geteilte Reaktorleben
- sichtbarer und jederzeit abbrechbarer Wartezustand für schnelle und private Online-Partien
- bereits spielbarer lokaler Koop-Modus mit einem KI-Partner auf der gespiegelten Kartenhälfte
- nahezu verdoppelte Koop-Weltbreite: Beide Spieler erhalten eine vollständige Kartenhälfte in ursprünglicher Größe
- Spiegelachse direkt durch den vorhandenen Kartenreaktor, sodass Hintergrundreaktor, gemeinsamer Zielpunkt und Laufwege wieder zusammenpassen
- eigener Ansichtswechsel zwischen der unverkleinerten Spieler- und KI-Kartenhälfte
- zwei gleichwertige Gegnerströme von den äußeren Kartenrändern zum gemeinsamen Reaktor
- die KI baut und verbessert selbstständig Kinetik-, Laser- und Raketentürme ausschließlich auf ihrer Seite
- Abschussbelohnungen und Baukosten werden dem jeweiligen Spieler beziehungsweise KI-Partner getrennt zugerechnet
- farblich getrennte Bauflächen und markierte KI-Türme zur schnellen Zuordnung im Gefecht
- fünf Kernkristalle als Belohnung für jede erfolgreich abgeschlossene Karte
- auswählbare Spielgeschwindigkeit bis 5× sowie automatischer Start der nächsten Welle
- Pause, Missionssieg, Niederlage und lokaler Wellenrekord
- jederzeit sichtbarer Zurück-Button zum Abbrechen der laufenden Runde und Wechseln ins Kartenmenü
- lokaler Speicherstand für Rekord und Tutorialstatus
- für Mobilgeräte geeigneter Compatibility-Renderer
- vorbereitete AdMob-Anbindung für Android und iOS mit Einwilligungsabfrage
- freiwillige Belohnungswerbung für einmalig 150 Notfallenergie pro Mission
- zurückhaltende Vollbildwerbung frühestens nach drei Missionen und mit 15 Minuten Mindestabstand
- keine Bannerwerbung und keine erzwungene Werbung während einer Angriffswelle

## Starten

1. Godot 4.x installieren.
2. Im Godot-Projektmanager `project.godot` aus diesem Ordner importieren.
3. Das Projekt öffnen und **F6** oder **F5** drücken.

Die Oberfläche ist für 1600 × 900 entworfen und skaliert automatisch auf andere Querformat-Auflösungen.

Beim ersten Öffnen einer frisch entpackten Kopie kann der Import der drei großen HD-Karten je nach PC ungefähr eine Minute dauern. Danach startet das Projekt normal.

Der Prototyp wurde mit der offiziellen Godot-Version 4.7.2 importiert und im automatisierten Headless-Test ohne Skript- oder Laufzeitfehler gestartet.

Der mitgelieferte Logiktest lässt sich bei Bedarf mit `godot --headless --path . --script res://tests/smoke_test.gd` erneut ausführen.

Für reproduzierbare Windows-Builds steht `packaging/windows/build.ps1` bereit. Godot und NSIS werden als Parameter übergeben; das Skript exportiert das Spiel, erstellt den Installer und gibt anschließend Größe und SHA-256-Prüfsumme aus. Die manuellen Freigabeprüfungen stehen in `ALPHA_TEST_CHECKLIST.md`.

Die Hinweise zum aktuellen Windows-Testbuild stehen in `RELEASE_NOTES_0.1.0-alpha.13.md`.

## Werbung und Datenschutz

Die mobile Werbeanbindung ist technisch vorbereitet, aber absichtlich noch nicht für echte Werbung freigeschaltet:

- `is_real` steht auf `false`; Android und iOS verwenden ausschließlich Googles offizielle Test-App- und Test-Anzeigen-IDs.
- Unter Windows bleibt das Werbesystem vollständig deaktiviert.
- Ein Belohnungsvideo erscheint nur nach einem freiwilligen Tipp auf **Video: +150 Notfallenergie** und höchstens einmal pro Mission.
- Vollbildwerbung kann nur am Ende einer Mission erscheinen, frühestens nach drei Missionen und niemals häufiger als alle 15 Minuten.
- Banner, App-Open-Anzeigen und Rewarded-Interstitials werden nicht verwendet.
- Vor der Initialisierung der Anzeigen wird auf Mobilgeräten Googles Consent-Information aktualisiert. Wenn eine Einwilligung erforderlich ist, wird zuerst das UMP-Formular angezeigt.
- Apples App-Tracking-Transparency-Abfrage ist derzeit deaktiviert. Sie wird erst aktiviert, wenn später tatsächlich Tracking beziehungsweise personalisierte Werbung benötigt und rechtlich geprüft wird.

Für die spätere Veröffentlichung müssen im AdMob-Konto eigene App- und Anzeigen-IDs angelegt, in `ads_manager.gd` beziehungsweise den beiden Export-Konfigurationsdateien eingetragen und `is_real` bewusst auf `true` gesetzt werden. Zusätzlich brauchen wir eine veröffentlichte Datenschutzerklärung, die korrekte Datenschutzdeklaration in App Store Connect und Google Play sowie eine erreichbare `app-ads.txt`-Datei auf der Entwickler-Webseite. Bis diese Punkte erledigt und echte Geräte getestet sind, dürfen die Test-IDs nicht ersetzt werden.

Verwendet wird **Godot AdMob Plugin 7.0** aus `godot-sdk-integrations/godot-admob`. Die Android- und iOS-Erweiterungen liegen mit im Projekt; ein iOS-Build benötigt später weiterhin macOS, Xcode und ein Apple-Developer-Konto.

## Online-Backend

Unter `server/nakama` liegt der reproduzierbare Docker-Compose-Stack für das selbst gehostete Online-Backend. Er besteht aus Nakama 3.37.0, einer eigenen internen PostgreSQL-16-Datenbank und einem täglichen Backup-Dienst mit 14 Tagen Aufbewahrung.

Der Stack ist auf dem vorgesehenen Unraid-Server eingerichtet. Nakamas Spiel-API läuft auf Port 7350, die Verwaltungskonsole ist ausschließlich an den Loopback-Port 7351 gebunden und PostgreSQL besitzt keinen veröffentlichten Host-Port. Echte Geheimnisse werden nur in der geschützten `.env`-Datei auf Unraid gespeichert und durch `.gitignore` ausdrücklich aus dem Quellpaket ausgeschlossen.

Die öffentliche Spiel-API ist unter `api.void-bastion.gergames.de` erreichbar. DNS, HTTPS/WSS über den vorhandenen Nginx Proxy Manager und die Godot-Nakama-Clientanbindung sind eingerichtet. Website und Spielserver verwenden damit getrennte Adressen.

### Spielupdates

Der Client prüft beim Start die öffentlichen Releases des Projekts. Ist eine neuere Version vorhanden, erscheint im Hauptmenü ein kompakter Update-Hinweis. Unter Windows öffnet er direkt das aktuelle Setup, unter Android künftig das aktuelle APK; fehlt ein passendes Paket, wird die öffentliche Release-Seite geöffnet. Ein Update wird niemals ungefragt installiert.

### Kartenregel: Laufweg und Reaktor

Jede Einzelspielerroute muss mit ihrem letzten Wegpunkt exakt im Mittelpunkt der primären Reaktorzone enden. `_validate_route_ends_at_reactor()` prüft diese Vorgabe beim Laden jeder Karte; der Smoke-Test prüft sie zusätzlich für alle vorhandenen Karten. Dadurch bleiben sichtbare Straße, Gegnerbewegung, Bausperre und Reaktoreinfahrt deckungsgleich.

## Steuerung

> **Online-Stand Alpha 0.1.0:** Der offizielle Nakama-Godot-Client, automatische Gastanmeldung, servergeprüfte öffentliche Spielernamen, Kontolöschung im Spiel, 36 autoritative Ranglisten, geprüfte Ergebnisübermittlung, Echtzeit-Sockets, serverautoritativer Zwei-Spieler-Koop, private Räume per Raumcode, eine Bereit-Lobby und Wiederverbindung sind eingebaut. Ranglisten lösen den aktuellen öffentlichen Profilnamen über die unveränderliche Spieler-ID auf. Die öffentliche API ist über `https://api.void-bastion.gergames.de` mit einem gültigen Let's-Encrypt-Zertifikat freigeschaltet. Details stehen in `ONLINE_SETUP.md`.

Die Schaltfläche **Bestenliste** im Hauptmenü zeigt die zwölf besten Piloten. Karte, Schwierigkeitsgrad sowie Mission oder Endlosmodus können direkt in der Ranglistenansicht gefiltert werden. Jede Zeile nennt Karte und Schwierigkeit sichtbar; der eigene Eintrag wird farblich hervorgehoben.

- Turm unten auswählen und auf eine freie Plattformfläche klicken oder tippen.
- Am PC folgt der Reichweitenkreis vor dem Bau dem Mauszeiger. Auf Mobilgeräten markiert der erste Tipp den Bauplatz samt Reichweite; der zweite Tipp auf dasselbe Feld bestätigt den Bau.
- Nur die markierten Rasterfelder sind bebaubar; Türme rasten automatisch in der Feldmitte ein. Die sichtbare Straße wird exakt auf denselben Rasterzellen und derselben Mittellinie gezeichnet, denen auch die Gegner folgen.
- Die Einsatzkarte wird vor dem Start im Hauptmenü gewählt.
- Im Hauptmenü wird außerdem der Schwierigkeitsgrad gewählt; die eingeblendete Kurzbeschreibung zeigt die wichtigsten Auswirkungen und den Kristallbonus.
- Die komplette Einsatzkarte bleibt auf PC und Mobilgeräten sichtbar; ein Verschieben ist nicht notwendig.
- Einen vorhandenen Turm auswählen, um ihn zu verbessern oder zu verkaufen.
- Das Informationsfeld rechts oben zeigt dabei die aktuellen Werte und den Mehrwert der nächsten Stufe.
- `Nächste Welle` startet den Angriff.
- `1×` beziehungsweise `2×` ändert die Spielgeschwindigkeit.
- `P`, Escape oder die Pause-Schaltfläche pausiert das Spiel.
- Nach Welle 15 kann die erfolgreiche Mission beendet oder freiwillig im Endlosmodus fortgesetzt werden.
- Unter **Multiplayer → Mit KI-Partner** startet die gespiegelte Koop-Arena sofort. Du baust auf der vollständigen linken Karte, die KI auf deren vollständiger Spiegelung; beide Seiten verteidigen denselben Reaktor. Mit **KI >** und **< ICH** wird ohne Verkleinerung zwischen beiden Seiten gewechselt.
- Unter **Multiplayer → Raum erstellen** wird ein privater Koop-Raum angelegt und ein sechsstelliger Code angezeigt. Der Mitspieler wählt **Raum beitreten** und gibt diesen Code ein.
- In der anschließenden Lobby werden beide Pilotennamen und Verteidigungsseiten angezeigt. Die Partie startet erst, wenn beide **Bereit** gewählt haben.

## Nächste Produktionsschritte

1. Balancing sowie Testanzeigen auf echten Android- und iOS-Geräten prüfen
2. Soundeffekte, Musik und zusätzliche Trefferanimationen
3. Kampagnenfortschritt und zusätzliche Bossvarianten
4. Freischaltmenü für neue Türme und Karten mit den bereits gespeicherten Kernkristallen
5. Plattformkonten mit einer eigenen plattformübergreifenden Spieler-ID verbinden
6. Private Raumcodes und die autoritative Koop-Synchronisierung auf echten Android-, iOS- und Windows-Geräten testen
7. Freundesliste und direkte Einladungen auf zwei echten Clients mit der neuen Server-Runtime prüfen
8. Store-Käufe erst nach stabiler Offline- und Koop-Kernversion

## Godot Agent Tools MCP

Das Projekt enthält das MIT-lizenzierte Godot-Addon **Agent Tools 0.3.1** unter `addons/agent_tools` sowie die lokale MCP-Brücke unter `tools/godot-agent-tools-mcp`.

Der Plugin-Eintrag ist in `project.godot` aktiviert. Beim geöffneten Godot-Editor lauscht die lokale Brücke ausschließlich auf `127.0.0.1:9920`. Codex wurde systemweit mit dem Namen `godot-agent-tools` auf diese lokale Brücke konfiguriert.

Geprüfter Zustand:

- 70 MCP-Werkzeuge erkannt
- `res://main.tscn` als aktuelle Szene erkannt
- Szenenwurzel `VoidBastion` vom Typ `Node2D` erkannt
- 57 Projektverweise geprüft, keine Probleme gefunden

Nach einem Neustart beziehungsweise einer neuen lokalen Codex-Sitzung stehen die Godot-Werkzeuge automatisch zur Verfügung, solange dieses Projekt im Godot-Editor geöffnet ist.

## Grafikherkunft

Die Karten und Sprite-Grafiken im Ordner `assets` wurden für dieses Projekt mit dem integrierten OpenAI-Bildgenerator erzeugt. Für Version 0.12 wurden die drei Karten als straßenfreie, hochauflösende Stationsdecks neu erzeugt und auf 3344 × 1882 Pixel aufbereitet. Die exakten Rasterstraßen entstehen nun im Spiel aus denselben Wegdaten wie Gegnerlinie und Bausperre. Die final verwendeten Prompts stehen in `ART_ASSETS.md`.