saumwacht-godot/docs/luneraria/ARCHITEKTUR.md

Architektur- und Migrationsentscheidungen

Stand: 27. September 2026 (M0).

Bestand (geprüft)

• Werkzeuge: Godot 4.7.2 (Fedora-Build; offizielle 4.7.2-Exportvorlagen unter assets-source/phase6/export-templates), Blender 5.2.2 LTS, Forward+ mit OpenGL-Kompatibilitätsmodus. Kein Engine-Update.
• Repository: Es gab kein Git. Angelegt wurde ein lokales Repository mit dem Baseline-Commit c2b4476 auf main (unveränderter Stand 0.15.0, Phase 20A); die Arbeit läuft auf luneraria/m1. Screenshots und die Projekt-Doku außerhalb des Projektordners sind in ../backups/vor-luneraria-2026-09-27-docs-und-screenshots.tar.gz gesichert (seit G2: ../_archiv/backups/). Keine uncommitteten fremden Änderungen; ../.mimocode gehört zu einem fremden Werkzeug und bleibt unberührt. Ein Stand 20B existiert nicht. Keine CLAUDE.md.
• Spiel: eine Szene scenes/main.tscn, sieben Autoloads (AssetLibrary, DataCatalog, GameState, EconomyManager, WaveManager, Preferences, Soundscape), alle Oberflächen im Code. Kampf in scripts/combat/: Verteidiger gegen Angreifer je Lane, die Feindschaft hängt an is_attacker, die Lane an team_id.
• Baseline-Tests (logs/m0-baseline/): 209 · 33 · 463 · 206 · 1.665 bestanden.

Entscheidungen

1. Neuer Modus neben dem Legacy-Modus. Die Saumwacht-Regeln (zwei Bretter, 8/20 Wellen, Kern-HP-Entscheid, Arbeiter/Funken) widersprechen den neuen Produktregeln. Sie werden nicht umgeschrieben, sondern als Legacy-Modus archiviert: scenes/main.tscn und die zugehörigen Tests bleiben lauffähig. Die neue Hauptszene scenes/luneraria.tscn startet Champions of Luneraria. Die bisherigen QA-Schalter (--smoke-test, --faction-test, --expedition-test) leitet sie in die Legacy-Szene um. So vermischen sich die Wirtschaftsmodelle nicht (Arbeitsannahme E), und die technischen Regressionen bleiben erhalten.
2. Neue autoritative Simulation in scripts/luneraria/core/ als reine Datenklassen (RefCounted) ohne Szenenbaum. Der alte Kampf ist an zwei Bretter und is_attacker gebunden. Übernommen werden Einheitenwerte (DataCatalog), Schadensmatrix, Fähigkeitsregeln (auf Teamfeindschaft umgeschrieben), Modelle und die Animationsanbindung (SkeletalFigure.update_combat, AnimatedFigure.pose).
   • LuneBalance (Resource) enthält alle Zahlen.
   • LuneMap enthält Lane-Polylinien, 16 Türme und 2 Kerne, Aufmarschflächen, Sperrlogik und die Grotte. Die Karte entsteht per Konstruktion spiegelsymmetrisch zur Diagonale x = z: Team 1 ist das Spiegelbild von Team 0.
   • LuneCombat rechnet einen festen Schritt in zwei Phasen, die Ergebnisse sind reihenfolgeunabhängig.
   • LuneMatch verwaltet Teams, Spieler, Gold, Besitz mit eindeutigen IDs, Befehle, Runden, Abrechnung, Sieg und Ereignisprotokoll.
   • LuneWaves erzeugt datengetriebene, unbegrenzte Wellen mit Mengengrenze.
   • LuneBot nutzt dieselbe Befehlsschnittstelle wie der Mensch.
3. Autoritative Matchinstanz von Anfang an. Oberfläche und Bots senden nur Befehle (LuneMatch.submit), die beim Phasenwechsel atomar geprüft werden. Darstellung und Tests lesen denselben Zustand. Zufall kommt nur aus einer RandomNumberGenerator-Instanz mit Seed (Wellenrotation, Bots). Das ist die Grundlage für M4 (Host/Join), ohne Bit-Identität über Plattformen zu behaupten.
4. Darstellung in scripts/luneraria/view/: Kartenaufbau aus Bestandsmaterialien (Kluft-Shader, Kerne, Felsen, Bäume), neu erzeugte Türme (Blender-Generator), eine Einheitenansicht pro Kampfinstanz mit Positionsinterpolation zwischen den Simulationsschritten. Sichtbarkeit und Kamera beeinflussen die Simulation nicht.
5. Oberfläche in scripts/luneraria/ui/ mit dem gemeinsamen SaumwachtTheme und seinen Bauteilen. Titel und Menü werden auf Champions of Luneraria umgestellt. Die Eingabeabschirmung aus 20A bleibt.
6. Benutzereinstellungen: Der Projektname wird zu „Champions of Luneraria“, dadurch ändert sich der user://-Pfad. Preferences übernimmt beim ersten Start einmalig die alte preferences.cfg aus „Saumwacht · Glutpakt“ und protokolliert das. Fehlt sie, gelten die Standardwerte.
7. Tests: Neue Tests liegen unter tests/luneraria/ und tools/luneraria/, die Legacy-Tests bleiben unverändert und werden als „Legacy“ geführt. Neue Referenzen werden erst nach fachlicher Prüfung festgeschrieben.
8. M3-Nachtrag: Bots planen Items/Champions vor der Armee und helfen deterministisch (kein geteilter rng), damit Spiegelmatches bit-symmetrisch bleiben. Kartenprops stammen aus map_props.glb (MultiMesh, ENV_*-Kluftshader). Volksrepräsentanten p_* sind Asset- und Datenziele ohne Matcheinbindung; siehe VOELKER.md. Balance- und Stresswerkzeuge liegen unter tools/luneraria/.
9. M4-Nachtrag: scripts/luneraria/net/lune_session.gd (Node) kapselt ENet Host/Join. Der Host besitzt LuneMatch, rechnet jeden Kampf und sendet je Sitz den öffentlichen Zustand plus nur dessen eigenen Entwurf (rpc_state), zum Kampfbeginn die Einheitenliste (rpc_combat_begin), danach Momentaufnahmen (rpc_frame, 20/s, PackedFloat32Array). Der Client baut daraus ein reines Anzeige-Abbild von LuneCombat, auf dem nie eine Regel läuft. Clients senden nur Befehle (rpc_hello mit Protokollversion, rpc_submit, rpc_ready). Peer-ID → Sitz, ein Peer ein Sitz. Disconnect: Bot-Übernahme, kein Kernverlust, keine Hostmigration; Wiedereinstieg über den Anzeigenamen. LuneGame spricht offline direkt mit LuneMatch, im Netzspiel ausschließlich mit der Sitzung. Protokolltests tests/luneraria/test_lune_net.gd, Mehr-Runden-Loopback tools/luneraria/net_pair.tscn mit Treiber tools/luneraria/net_rounds.py. Export-Presets Luneraria-Linux / Luneraria-Windows, Demo-Bau tools/luneraria/build_luneraria_demo.py.
10. G1-Nachtrag (Karte):
    • LuneMap baut jede Lane aus Catmull-Rom-Kontrollpunkten ihrer blauen Hälfte (Endpunkt auf der Achse, gespiegelter Phantompunkt, dadurch knickfrei). Bottom wird per Bisektion auf die Länge von Top gelöst. LanePath sucht Segmente binär.
    • Die Simulation bleibt zweidimensional. Die Darstellung liest Höhen aus scripts/luneraria/view/lune_terrain.gd (LuneTerrain): Höhenfeld aus Achsenkoordinate, Achsenabstand und gespiegelten Kartenelementen, daher exakt symmetrisch. Es wird für die Blau-Hälfte berechnet und gespiegelt, je Prozess einmal erzeugt; die walk_height liefert Deckhöhen statt Flussbett.
    • lune_world.gd baut Gelände, Wasser, Lanebeläge, Plattform, Deltabrücke, Basen, Grotte, Landmarken, Vegetationscluster und Aufmarschflächen aus Bestandsassets und Blockout-Primitiven.
    • lune_camera.gd ist eine perspektivische Kamera, deren zoom die sichtbare Bodenhöhe bleibt; die Neigung hängt vom Zoom ab.
    • Die Grottenpunkte behalten ihre M2-Abstände zum Grottenmittelpunkt.
11. G2-Nachtrag (strategische Bauwerke):
    • Views je Objekt: Jedes strategische Objekt hat eine eigene View, die nur den autoritativen Zustand liest:
      • lune_tower_view.gd (HP → Stufe, Angriffsfortschritt und Trefferzähler → Aufladen und Bolzenstart);
      • lune_ancient_view.gd;
      • lune_grotto_view.gd (fünf Zustände aus Runde, Claim, nächster Verfügbarkeit und dem Grottenboss des laufenden Kampfes). Keine View schreibt in die Simulation.
    • Effekte: lune_tower_fx.gd zeigt Zielring, Bolzen und Einschläge gepoolt; lune_fx.gd liefert begrenzte GPU-Partikelbausteine.
    • Welt: lune_world.gd baut und synchronisiert alles in sync_strategic und sync_grotto und berechnet den Occlusion-Fade: Bildschirmrechteck des Gebäudes und Bodentiefe entlang der Blickrichtung, alle zwei Bilder.
    • Materialien: lune_materials.gd ordnet LN_*-Oberflächen gemeinsamen ShaderMaterials zu (view/materials/*.gdshader). Alles Gebäude- oder Teamspezifische sind Instanzparameter mit festen Indizes (0–15). Der Fade wird im orthografischen Schattenpass übersprungen.
    • Assets: Blender-Generatoren unter assets-source/luneraria/g2/ mit gemeinsamem Baukasten lune_bpy.py. Sie schreiben .blend, GLB und assets/luneraria/g2/g2_manifest.json, das AssetLibrary zusätzlich liest (der Boss als skelettierte Figur).
    • Figuren: SkeletalFigure kennt eine Schrittweite pro Modell und play_event() für Einmal-Clips (Brüllen, Sieg). LuneUnitView zeigt jede Boss-Einheit als Schlundkrone und färbt ihre Adern nach Team.
    • Gelände: LuneTerrain hat eine kleine, symmetrische Senke hinter dem Grottentor (nur Darstellung). Die Grottenfläche und der Ancient-Dais heben Figuren an (surface_lift).
    • Plattform: lune_main.gd startet mit --lune-smoke einen Plattform-Kurztest. project.godot importiert Texturen zusätzlich als ETC2/ASTC (Voraussetzung für den Apple-Silicon-Export) und führt die Luneraria-Version unter [luneraria]. Export-Presets: Linux, Windows x64, Windows ARM64, macOS Universal.