Void-Bastion/PROJEKT-HANDBUCH-FORTSETZUNG.md

Void Bastion – Projekt- und Fortsetzungs-Handbuch

Stand: 9. Oktober 2026 · Version: 0.1.0-alpha.4 · Engine: Godot 4.7.2

Dieses Dokument ist die zentrale technische Übergabe für die Weiterarbeit an Void Bastion – auch nach einem PC-Wechsel. Es beschreibt den aktuellen Stand, die Projektstruktur und die verbindlichen Gestaltungs- und Datenregeln. Bei Änderungen immer zuerst diese Datei, README.md, ART_ASSETS.md und die Tests lesen.

Projektziele und aktueller Stand

Void Bastion ist ein 2D-Tower-Defense-Spiel im realistischen Science-Fiction-Stil für Windows, Android und später iOS. Der aktuelle Spielstand ist Alpha 4. Einzelspieler mit sieben Karten, sechs Türmen, drei Schwierigkeitsstufen, 15 Wellen plus optionalem Endlosmodus, Shop, lokalem Profil und Bestenlisten ist vorhanden. Ein lokaler Koop-Modus gegen KI sowie eine Nakama-Onlineanbindung sind vorbereitet/implementiert.

Wichtige Einschränkungen des aktuellen Android-Teststands:

• Der Android-Emulator (Android 17, x86_64, SwiftShader) startet Alpha 4 und bleibt mindestens 45 Sekunden aktiv. Der Bildschirm zeigt das Hauptmenü; im Log gab es während dieses Laufs keinen Absturz.
• Android verwendet den Mobile/Vulkan-Renderer. Die GLES-Compatibility-Variante überschritt auf dem Emulator die verfügbare Shader-Uniform-Grenze.
• Wegen eines reproduzierbaren nativen SIGSEGV in Androids AudioTrack/OpenSL-Ausgabepfad sind Musik und UI-Klicktöne derzeit nur auf Android deaktiviert. Windows-Audio bleibt aktiv. Vor dem Wiederaktivieren erst mit regulären, eingebundenen Audioassets und auf echten Geräten erneut testen.
• Im Android-Log meldet das AdMob-Plugin, dass sein natives Singleton nicht initialisiert ist. Android-Werbung ist deshalb nicht als funktionsfähig getestet anzusehen.
• Die geprüfte Emulator-Datei ist build/android/Void-Bastion-Android-x64-alpha4.apk. Sie hat die Paketkennung de.gergames.voidbastion, Versionsnamen 0.1.0-alpha.4 und ist mit dem lokalen Debug-Schlüssel signiert. Sie ist nur zum Sideload-/Emulator-Test bestimmt, nicht zur Store-Veröffentlichung.
• Es wurde kein echtes Android-Handy in diesem Testlauf geprüft. Touch-Bedienung, Geräteperformance, verschiedene Seitenverhältnisse, Anzeigen und Audio brauchen noch echte Gerätetests.

Projektdateien und Zuständigkeiten

• project.godot: Godot-Projekt, Fenster-/Viewport-Einstellungen, Autoloads, Editor-Plugins und Renderer. Desktop bleibt auf gl_compatibility; Mobilgeräte nutzen derzeit mobile/Vulkan.
• main.gd: Spielzustand, Karten-/Weg-/Bau-/Turmdaten, Wellen, KI, Kampf, UI, Zeichnen und lokale Navigation. Die zentralen Datenkonstanten stehen am Dateianfang.
• main.tscn: Hauptszene und Manager-Nodes.
• multiplayer_manager.gd: lokale Koop-/KI-Regeln und Multiplayer-Helfer.
• online_manager.gd, account_manager.gd: Nakama-Verbindung, Profil, Anmeldung und Ranglisten.
• ads_manager.gd: Werbeintegration. Testmodus beibehalten, bis Konten, Einwilligung und Store-Konfiguration rechtlich/technisch geprüft sind.
• update_manager.gd: Prüft öffentliche Releases und bietet einen Update-Link an; installiert nichts ungefragt.
• assets/: Kartenbasen, Turm-/Gegnersprites, Straßenmaterial und UI-Grafiken.
• tests/smoke_test.gd: Offline-/Logikregressionstest. Nach Karten-, Weg-, Turm-, Wellen- oder Balancingänderungen immer ausführen.
• tests/online_integration_test.gd: Nakama-/Onlineintegrationstest; nur gegen ausdrücklich gewählte Testumgebung ausführen.
• packaging/windows/build.ps1 und packaging/windows/installer.nsi: Windows-Export und Setup-Installer.
• export_presets.cfg: Windows-, Android- und iOS-Exportprofile.
• server/nakama/: Serverkonfiguration/Module. Keine Servergeheimnisse hier ablegen.
• README.md, ART_ASSETS.md, ONLINE_SETUP.md, LEGAL_RELEASE_CHECKLIST.md, PLATFORM_ACCOUNT_SETUP.md, THIRD_PARTY_NOTICES.md: ergänzende Projektunterlagen.
• .godot/, build/, dist/, android/build/: generierte Imports, Builds, Caches und Artefakte. Sie gehören zum vollständigen PC-Backup, aber normalerweise nicht in Git-Commits.

Karten: verbindliche Regeln

Koordinatensystem und Raster

• Die logische Spielfläche ist SCREEN = Vector2(1600, 900) in main.gd.
• GRID_SIZE = 80 Pixel; Karten, Wege, Bauzellen und Turm-Snapping müssen mit demselben Raster arbeiten.
• Das Rasterzentrum eines Feldes liegt bei (40 + 80·x, 40 + 80·y). Wegpunkte sollen auf diesen Feldmitten liegen. Der auslaufende Start darf links bei x = -40 liegen.
• Wegsegmente verlaufen nur waagerecht oder senkrecht. Keine diagonalen Segmente. Kurven entstehen durch aufeinanderfolgende rechtwinklige Segmente.
• Gegnerrouten und Straßenzeichnung beziehen ihre Daten gemeinsam aus MAP_PATHS/path_cells. Niemals zusätzlich einen unabhängigen Weg in die Hintergrundgrafik malen oder eine zweite separate Laufroute definieren.

Drei parallele Kartendatenlisten

Jeder Karteneintrag muss denselben Index in ALLEN folgenden Arrays besitzen (in main.gd):

1. MAP_TEXTURES: Hintergrundtextur.
2. MAP_NAMES, MAP_DESCRIPTIONS, MAP_UNLOCK_COSTS: Name, Kurzbeschreibung und Shoppreis.
3. MAP_PATHS: geordnete Mittellinienpunkte für Gegner und Straße.
4. MAP_BUILD_ZONES: erlaubte Deckbereiche als ein oder mehrere Rect2-Rechtecke.
5. MAP_REACTOR_ZONES: Reaktormittelpunkt(e) und Sperrradius/-radien.

Alle Listen müssen dieselbe Kartenanzahl und identische Reihenfolge haben. Nach Hinzufügen oder Umsortieren einer Karte die Anzahl und Reihenfolge prüfen und Smoke-Test ergänzen.

Routenende, Reaktor und Bauverbote

• Letzter Punkt in MAP_PATHS[index] muss exakt im Mittelpunkt des Hauptreaktors landen (Toleranz in _validate_route_ends_at_reactor() ist 1 Pixel). _select_map() validiert die Route; der Smoke-Test validiert alle Karten.
• Die Reaktorgrafik im Hintergrund, MAP_REACTOR_ZONES[index][0].center und letzter Wegpunkt müssen optisch/technisch deckungsgleich sein.
• Auf jedem Reaktor ist Bauen verboten. Alle Reaktoren/offenen Reaktorkammern derselben Karte in MAP_REACTOR_ZONES eintragen. Pyrax hat zusätzlich die offene Reaktorkammer als zweite Sperrzone.
• Erlaubte Deckzellen werden über MAP_BUILD_ZONES definiert. Das Spiel sperrt zusätzlich Wegzellen, Reaktorzonen, Randzellen und bereits belegte Zellen.
• Türme werden auf Feldmitten eingerastet. Weder Türme noch Wegkacheln sollen nur über Bildkoordinaten korrigiert werden: zuerst Raster-/Routendaten korrigieren.

Kartengrafik

• Karte ist eine saubere, hochauflösende Draufsicht im Querformat (bestehende HD-Basen etwa 3344×1882 Pixel).
• Hintergrundgrafik ohne eingebauten Weg, Fahrbahn, Raster, Bauplätze, Türme, Gegner, UI, Text oder Logos erstellen. Straße/Raster/Route werden im Spiel gezeichnet; so können sie nicht gegeneinander verrutschen.
• Der Reaktor soll gut erkennbar am rechten Rand ungefähr auf Höhe des Spielfeldzentrums liegen, außer die Route/Zone definiert absichtlich eine andere Lage.
• Behalte realistische aktive Stationsbeleuchtung, Metallpaneele, Cyan-Energieelemente und kleine warme Positionslichter. Keine dunkle/ausgewaschene Karte und keine starke gelbe Umrandung der kompletten Straße.
• Die Straße ist eine Rasterzelle breit (80 px) und nutzt road_straight.svg, road_corner.svg, road_surface_material_v1.png, road_corner_surface_v1.png.
• Der letzte Abschnitt zum Reaktor wird in _draw_reactor_approach() mit leisem Lichtimpuls und langsamem Transparenzverlauf gestaltet. Den Schluss nicht hart abschneiden und keine groben Doppelbögen ans Reaktorzentrum setzen.
• Asset-Prompts und Asset-Herkunft in ART_ASSETS.md dokumentieren.

Kartenprüfung

1. Für jeden Wegpunkt Rastermitte prüfen, horizontale/vertikale Segmente sicherstellen.
2. Ende exakt am Reaktormittelpunkt kontrollieren.
3. Reaktor im Hintergrund mit Sperrzone vergleichen; keine Bauzellen auf dem Reaktor.
4. Das Projekt starten: Weg muss sichtbar mit Gegnerlaufspur, Raster und Hintergrund zusammenpassen.
5. Zwischen Wegen müssen Bauzellen frei bleiben, soweit sie innerhalb einer Build-Zone und außerhalb aller Route-/Reaktor-Sperren liegen.
6. tests/smoke_test.gd für jede neue Karte um Routenende, Reactor-Sperre, baubare Zellen und Shop-Kosten erweitern und ausführen.

Türme und Gegner

Turmdaten und Darstellung

Die Liste TOWER_DATA in main.gd ist die zentrale Quelle für Turmname, Baukosten, Basisschaden, Reichweite, Schussintervall (rate, Sekunden pro Schuss), Projektilgeschwindigkeit, Schadensart, Farbe, Freischaltpreis und Beschreibung. Schüsse/Sekunde wird aus dem Intervall berechnet. Beim Hinzufügen eines Turms müssen UI-Karte, Shop, Platzierung, Reichweitenvorschau, Angriff/Schadenslogik, Upgrade, Speichern/Freischaltung und Tests konsistent ergänzt werden.

Sprites:

• Kinetik, Laser, Rakete: drei horizontale Frames aus assets/defense_towers.png.
• Plasma, EMP-Puls, Railgun: separate Texturen (tower_plasma.png, tower_emp.png, tower_railgun.png).
• Ergänzende Sprites im bestehenden maßstäblichen Top-Down-Stil und mit transparenter Fläche erzeugen. In _draw_tower() Textur/Fall ergänzen. Bei der Kinetik-Ausrichtung beachten, dass ein falscher Basiswinkel den Lauf um 180° verdreht erscheinen lässt.

Turm	Kosten	Schaden	Reichweite	Intervall	Besonderheit
Kinetik	120 EN	22	190	0,55 s	Einzelziel
Laser	180 EN	12	165	0,18 s	Schnell, effektiv gegen Schilde
Rakete	250 EN	65	260	1,40 s	Flächenschaden 76
Plasma	230 EN	48	240	1,05 s	Flächenschaden 92; 18 Kernkristalle Freischaltung
EMP-Puls	210 EN	34	215	0,92 s	Flächeneffekt 118; 24 Kernkristalle
Railgun	300 EN	110	330	1,85 s	Durchschlägt Schild; 30 Kernkristalle

Alle Türme unten in der Leiste darstellen. Reichweite schon vor dem Bauen zeigen; Vorschaukasten kompakt/transluzent halten. Turminfo soll Schaden, Schüsse pro Sekunde, Reichweite und Einzel-/Flächentyp zeigen. Upgrade-Vorschau muss den echten Zuwachs darstellen und darf keine verdeckten Felder erzeugen. Bei Balancingänderungen Shoptext und Tests mit anpassen.

Gegner

Gegnerwerte liegen in ENEMY_DATA: Jäger (70 HP, Tempo 105, Belohnung 18), Fregatte (185 HP, Tempo 72, Belohnung 34), Kreuzer (520 HP, Tempo 43, Belohnung 78). Skalierung und Wellenlogik werden zusätzlich durch DIFFICULTY_DATA/Wellenfunktionen beeinflusst. Schildgegner sollen Laserschaden bevorzugt wirksam bekommen; andere Türme dürfen reduziert, aber nicht grundsätzlich null Schaden verursachen. Railgun ignoriert den Schildschutz.

Wellen, Wirtschaft, Highscore

• MAX_WAVES = 15; Bossgegner alle fünf Wellen.
• Leicht entspricht dem früheren Balancing, Mittel/Schwer steigern Lebenspunkte, Tempo und Gegneranzahl und reduzieren Startressourcen. Belohnung aktuell 5/7/10 Kernkristalle nach Schwierigkeit.
• Nach Welle 15 gibt es die Wahl: Mission beenden oder freiwillig Endlosmodus. Endlos-Verlust gilt nicht als gescheiterte Mission.
• Punkte sollen neben erreichter Welle auch Restenergie und effiziente Turmverwendung abbilden. Verkauf aller Türme in der Schlusswelle darf keinen Multiplikator-Trick ermöglichen; deshalb Turmbau-/Verkaufshistorie berücksichtigen, nicht nur die am Ende noch stehenden Türme.
• Spielwährung heißt konsistent Kernkristalle (nicht abwechselnd „Kern“ oder „Kristalle“). Energie/EN ist die missionsinterne Bauressource.
• Für neue Türme/Karten Shopfreischaltungen und Belohnung konsistent speichern; kein echter Geldeinkauf ist für diese Testfassung erforderlich.

Multiplayer

• Lokale KI-Arena verwendet COOP_LEFT_PATH und eine Spiegelung exakt um die Achse durch den gemeinsamen Reaktor (COOP_MIRROR_X = 1480). Weltbreite ist doppelt; beide Seiten sollen voll groß bleiben, nicht zusammengeschrumpft.
• Reaktorleben sind gemeinsam, Credits getrennt; jeder baut auf seiner Seite. KI-Platzierung in _find_ai_build_position() anhand echter Gegnerroute und effektiver Turmreichweite bewerten, niemals zufällige/off-route Plätze wählen.
• Onlinekonten, Räume, Ranglisten und Ergebnisprüfung laufen über Nakama. Niemals Admin-/Server-/HTTP-Schlüssel in Godot-Projekt, .env-Beispiel, Git, Website oder diese Anleitung kopieren.
• Server-/Unraid-Konfiguration und öffentliche Adresse sind in ONLINE_SETUP.md bzw. server/nakama/README.md beschrieben; echte Geheimnisse liegen nur auf dem Server/Webhosting.

Builds, Checks und Release

Logiktest

& 'E:\Program Files\Godot\Godot_v4.7.2-stable_win64_console.exe' --headless --path . --script tests/smoke_test.gd

Erfolg endet mit VOID_BASTION_SMOKE_TEST_OK. Bekannte Umgebungswarnungen zum CA-Zertifikat oder user://-Log sind nicht automatisch ein Spielfehler; entscheidend ist Rückgabecode und Ergebnis.

Windows-Installer

& '.\packaging\windows\build.ps1' `
  -GodotExe 'E:\Program Files\Godot\Godot_v4.7.2-stable_win64_console.exe' `
  -MakeNsisExe '.\build\nsis-portable\nsis-3.13\makensis.exe'

Artefakt: dist/Void-Bastion-Setup-x64.exe. Das Skript blendet das Entwicklungs-MCP aus dem Release aus, exportiert und stellt anschließend project.godot wieder her.

Android

• Godot Exportprofil heißt Android Studio Emulator x86_64 (emulator) bzw. Android Test APK (ARM64/ARMv7-Geräte).
• Erfordert Android SDK, Java 17, Gradle und Godot-Android-Templates. Android-Paketkennung ist de.gergames.voidbastion.
• Das Editor-MCP-Autoload/Plugin darf nicht ins Release gelangen: temporär vor dem Export _MCPGameBridge und res://addons/agent_tools/plugin.cfg aus der Exportkopie entfernen und Quelldatei danach wiederherstellen (Windows-Skript zeigt das sichere try/finally-Muster). Nie eine Änderung versehentlich dauerhaft aus der Entwicklerdatei löschen.
• Emulator Alpha 4 wurde mit Gradle 8.11.1, AGP 8.6.1, Java 17 und SDK 36 gebaut. Bei einem Gradle AccessDeniedException in einer Transform-Cache-Datei neues separates GRADLE_USER_HOME nutzen; vorhandene Cache-Datei nicht blind löschen.
• Für einen Testbuild prüfen: aapt dump badging zeigt de.gergames.voidbastion und 0.1.0-alpha.4; apksigner verify --verbose muss Verifies melden; danach auf Emulator installieren und mindestens 45 Sekunden starten, Logcat auf SIGSEGV/FATAL prüfen und Screenshot kontrollieren.
• Erfolgreiche Testdatei liegt in build/android/Void-Bastion-Android-x64-alpha4.apk (Debugsignatur; nur intern). APK ist im Git-Verlauf nicht garantiert; im Vollbackup enthalten.
• Für neue Google-Play-/Sideload-Versionen Android versionCode erhöhen. Signaturschlüssel für Produktion getrennt und sicher aufbewahren, nicht Debugschlüssel als Store-Schlüssel verwenden.

iOS und Stores

iOS-Export erzeugt ein Xcode-Projekt, erfordert macOS, Xcode, Zertifikate/Provisioning und ein Apple-Developer-Konto. Ein Windows-Rechner kann die iOS-App nicht final signieren oder in den App Store hochladen. Google Play-/Apple Store-/Steam-Accounts, Datenschutz- und Storefreigaben bleiben manuelle Betreiberaufgaben. Vor öffentlichem Release Checklisten/Third-party-Lizenzen und echte Geräteprüfung abschließen.

Webseite und Releases

Homepage: https://void-bastion.gergames.de/. Öffentliche Releases/Setup liegen im separaten Gitea-Releases-Projekt; der Ingame-Updater fragt die Release-API ab und soll automatisch das neueste passende Setup/APK verlinken. Nach einer Veröffentlichung Release-Tag, Version in Godot, Windows Installer, Android versionCode und Release-Assetnamen synchron halten. Keine Websiteänderung ist erforderlich, wenn Release-API/Assets korrekt gepflegt sind.

Netcup-Dateiübertragung

Der aktuelle, schnellere Git-/SSH-Ablauf für Website und Nakama steht in DEPLOYMENT-SCHNELLWEG.md. Diese Datei bei Veröffentlichungen zuerst lesen. Der Website-Quellcode wird lokal per repositorygebundenem SSH-Deploy-Key nach Gitea gepusht; Nakama wird unabhängig davon per SSH gezielt auf Unraid aktualisiert.

• Die Website void-bastion.gergames.de liegt im Netcup-Webspace unter gergames.de/void-bastion. Änderungen nur in diesem Domain-/Ordnerbereich vornehmen; andere gehostete Seiten sind ausdrücklich außerhalb des Arbeitsumfangs.
• Beim Prüfen des Netcup-Panels am 9. Oktober 2026 zeigte der FTP-Bereich nur das Hauptkonto hosting143098 mit Basisverzeichnis /. Das ist ein webhostingweiter Zugang und darf nicht für automatisierte Void-Bastion-Uploads verwendet werden, weil er auch andere Websites erreichen kann.
• Laut Netcup-Dokumentation lässt sich kein zusätzlicher FTP-Benutzer anlegen; zur Verfügung steht der SSH-Zugang. Ein separater, auf Void Bastion beschränkter FTP-Benutzer existiert daher nicht.
• Für automatisierte Übertragungen zuerst prüfen, ob SFTP über den vorhandenen SSH-Zugang aktiviert ist und ob dessen Startverzeichnis sicher auf den benötigten Webspace begrenzt ist. Bis Host, Port, Authentifizierung und zulässiger Zielpfad praktisch bestätigt sind, nichts automatisiert hochladen.
• Zugangsdaten oder private SSH-Schlüssel niemals in dieses Repository oder diese Anleitung schreiben. Für die Einrichtung nach Möglichkeit einen eigenen SSH-Schlüssel verwenden und nur lokal/geschützt speichern. Das bestehende Git-Deployment bzw. der Netcup-Dateimanager bleiben sichere Alternativen, bis SFTP getestet wurde.
• Passwörter, private Schlüssel und API-Tokens niemals in diese Anleitung, Git oder Projektdateien schreiben. Geheimnisse separat im Passwortmanager bzw. geschützten lokalen Credential Store des Betreibers ablegen. In der Anleitung dürfen nur Host, Protokoll, Port, Benutzername und begrenzter Zielpfad stehen, sofern diese Werte bestätigt wurden.

Weiterarbeit nach einem PC-Wechsel

1. Backupordner auf neuen PC kopieren und vorzugsweise in einen stabilen Arbeitsordner legen.
2. Git installieren; git status und git log -1 prüfen. Den mitgesicherten .git-Ordner nicht entfernen, damit die Historie erhalten bleibt.
3. Godot 4.7.2 installieren und project.godot importieren; ersten Assetimport abwarten.
4. PROJEKT-HANDBUCH-FORTSETZUNG.md, README.md, ART_ASSETS.md, ALPHA_TEST_CHECKLIST.md, ONLINE_SETUP.md lesen.
5. Android-Buildtools/JDK 17 nur einrichten, wenn Android gebraucht wird. Emulator neu anlegen; lokale Gradle-Caches und lokale Godot-Einstellungen sind maschinengebunden und können auf dem neuen PC neu erzeugt werden.
6. tests/smoke_test.gd ausführen, dann Spiel im Editor starten und zuletzt Plattformbuilds prüfen.
7. Serverzugänge, Signierzertifikate, echte AdMob-/Nakama-Schlüssel und Hostingpasswörter separat aus einem Passwortmanager/Server sichern. Diese sind absichtlich nicht Teil des Repositories oder dieser Anleitung.

Grundsatz bei jeder Karten-/Turmänderung

Eine visuelle Änderung ist erst fertig, wenn Datenquelle, Darstellung, Kollisions-/Bauprüfung, Kauf-/Freischaltstatus, UI-Text und automatisierter Test zueinander passen. Bei Karten besonders Route, Straßenkacheln, Raster, Bauflächen, Sperrzonen und Reaktorhintergrund gemeinsam prüfen. Keine unabhängige „optische Reparatur“ über die Route zeichnen.