Technische Architektur

11.1 Engine-Entscheidung: Godot 4.7 vs. Unity 6

Entscheidung [Vorschlag]: Godot 4.7.2 mit GDScript. Unity gewinnt bei iOS-Ökosystem und High-End-Grafik. Beides ist für ein stilisiertes, Android-first Cozy-Spiel nicht entscheidend. Godot gewinnt bei dem, was für ein kleines Team zählt: vorhandenes Wissen und Bausteine, Kosten, agentenfreundliche Textformate, schnelle lokale Builds.

Renderer: Compatibility statt Mobile

Entscheidung: Compatibility für alle Stufen. Alle Shader werden so geschrieben, dass sie auch im Mobile-Renderer laufen. Ein späterer Wechsel (z. B. „Hoch“-Stufe auf Vulkan) bleibt möglich, verdoppelt aber die QA – daher erst nach dem MVP prüfen.

11.2 Projektstruktur

project.godot · export_presets.cfg
scenes/            main.tscn, planet.tscn, ui/*.tscn
scripts/
  autoload/        game.gd (Einstellungen, Profil) · bus.gd (Signale) · sfx.gd (Audio+Radio, aus Bellmoor)
                   loc.gd (Sprache, aus Bellmoor) · analytics.gd · notify.gd · ads.gd · quality.gd
  sim/             rng.gd · grid.gd · planet_state.gd · climate.gd · hydrology.gd · terrain.gd · biomes.gd
                   vegetation.gd · life.gd · civ.gd · events.gd · chronicle.gd · actions.gd · simulator.gd
                   offline.gd · names.gd
  meta/            energy.gd · progression.gd · challenges.gd · achievements.gd · galaxy.gd · scenarios.gd
  services/        save.gd · time_keeper.gd
  view/            planet_view.gd · props_view.gd · fx_view.gd · camera_rig.gd · input_router.gd · night_lights.gd
  ui/              hud.gd · tool_ring.gd · info_sheet.gd · evolution_card.gd · chronicle_view.gd · settings.gd …
shaders/           planet_surface.gdshader · ocean · atmosphere · clouds · prop_foliage · prop_creature · prop_building · fx_lava
data/              balance.json · biomes.json · events.json · evolution_cards.json · challenges.json · scenarios/*.json
                   names/<lang>.json · chronicle_templates/<lang>.json
assets/            models/ · textures/ · audio/ · icons/ · fonts/ · ui/
locale/            strings.csv → *.translation
addons/            pp_analytics (aus Bellmoor) · notification-Plugins · werbemodul (Port)
tests/             test_*.gd (headless) · ui_*.gd (mit Fenster) · bench_*.gd
tools/             export-wiki.mjs · tripo.mjs · audio-prep.mjs · import-gpt-art.mjs · blender/*.py
artifacts/         KI-Rohdaten (git-ignoriert)
docs/konzept/      diese Dokumente

11.3 Schichten und Abhängigkeiten

             ┌──────────── UI (scripts/ui) ─────────────┐
             │  liest Zustand, sendet Aktionen          │
             ▼                                          │
     View (scripts/view)  ◄── Bus-Signale ──  Meta (energy, progression, challenges)
             │ liest PlanetState (read-only)            │
             ▼                                          ▼
     ┌──────────────── Sim (scripts/sim) ─────────────────────┐
     │  reine RefCounted-Klassen · kein Node · kein Rendering │
     └─────────────────────────────────────────────────────────┘
             ▲
     Services (save, time_keeper) · Autoloads (sfx, ads, notify, analytics, quality)

Regeln (für Coding-Agenten verbindlich, kommen in CLAUDE.md):

1. scripts/sim/ importiert nichts aus view/ui/autoload. Tests laufen headless.
2. Jede Zustandsänderung durch den Spieler ist eine Aktion (actions.gd, Command-Muster): validate(state) → cost → apply(state). Dadurch: Rückgängig (5 s), Wiederholbarkeit in Tests, Energieprüfung an einer Stelle.
3. View schreibt nie in den Zustand. Sie liest PlanetState und TickReport.dirty_regions.
4. Zahlen fürs Balancing stehen in data/*.json, nie im Code.
5. Zufall nur über rng.gd (PCG32, benannte Ströme).

11.4 Module – Verantwortung und Schnittstellen

11.5 Speichersystem

• Profil: user://profile.json – Einstellungen, Sternenstaub, Achievements, Planetenliste, Zustimmungen, Zeitstempel.
• Planet: user://planets/<id>.save – JSON-Kopf (Version, Epoche, Zyklus, Seed, Arten, Kulturen, Ziele) + Regionsfelder als PackedByteArray, gesamt per FileAccess.open_compressed (zstd).
• Atomar: schreiben nach <id>.tmp, dann umbenennen; die vorige Datei bleibt als <id>.bak. Beim Laden: Prüfsumme (CRC32 im Kopf); bei Fehler .bak.
• Wann: Epochenwechsel, nach jeder Evolutionskarte/Ereignis-Entscheidung, alle 60 s, bei NOTIFICATION_APPLICATION_PAUSED und WM_CLOSE_REQUEST, vor Eigenwerbung.
• Version & Migration: save_version im Kopf, migrate() je Versionssprung, Test mit gespeicherten Beispielständen (tests/fixtures/saves/).
• Kein Cloud-Save im MVP. Phase 3: Android Backup (Auto Backup) prüfen – kostet nichts, braucht nur android:allowBackup + Ausschlussregeln.

11.6 Tests & Debugging

• Headless-Tests (tests/test_*.gd, Runner tools/godot-test.ps1 nach Studio-Muster): Determinismus, Offline-Äquivalenz, Aktionen (Kosten/Validierung), Biom-Klassifikation, Populationsgrenzen, Speichern/Laden/Migration, Zielfortschritt, Zeitsicherheit.
• Bot-Balancing (tests/bot_balance.gd): Ein Bot spielt mit einfachen Regeln 30 Tage simulierte Zeit (aktive Sitzungen + Offline-Lücken) und protokolliert Epochen-Zeitpunkte und Energie-Engpässe → Abgleich mit der Zielkurve in 06 §6.6.
• Benchmarks (tests/bench_*.gd): Zyklus, Makroschritt, Szenen-Kamerafahrt → JSON nach artifacts/bench/.
• Debug-Overlay (nur Debug-Builds, 3-Finger-Tipp): FPS, Frametime-Kurve, Draw Calls, Vertices, Sim-ms, Stufe, Zyklus, Seed; Datentextur-Ansichten (Temperatur/Feuchte/Biom/Population als Falschfarben).
• Testzustände (Studio-Muster test_unlock.gd): -- --epoch=5 --seed=42 --energy=999 setzt beliebige Startzustände, auf Android/iOS wirkungslos.
• Capture-Modus (Studio-Muster --capture): rendert Store- und Wiki-Screens deterministisch.

11.7 Plan B für die Rechenleistung

Falls GDScript die Budgets aus 12 verfehlt (Messung ab T-06), wird nur sim/ (ohne Schnittstellenänderung) als GDExtension in C++ neu geschrieben; Tests bleiben gleich und prüfen Gleichheit über Zustands-Hashes. Aufwand [Schätzung] 2–3 Wochen. Vorher ausschöpfen: Packed-Arrays, Schleifen ohne Dictionaries, Teilaktualisierung (dirty), Worker-Thread.