Aquila To-Do / Roadmap

Dieses Dokument ist die kanonische Langfrist-Roadmap fuer Aquila.

• docs/PLAN.md bleibt der kurzfristige aktive Arbeitsschritt
• docs/AGENT_LOG.md bleibt das operative Handoff-Protokoll
• docs/TODO_AQUILA.md ist die grosse Zukunftsplanung mit Phasen, Reihenfolge und offenen Entscheidungen
• Diese Datei lebt ab 2026-05-01 in AquilaUnity, weil Unity die aktive Game-Schiene ist. aquila-westmed bleibt Karten-/Tile-Pipeline und Archiv.

Wenn sich Zielbild, Reihenfolge oder Prioritaeten aendern, wird dieses Dokument zuerst aktualisiert. Danach folgen PLAN.md, AGENT_LOG.md und die Portfolio-Webseite.

Pflege-Regeln

• □Bei jedem Wechsel des aktiven Milestones dieses Dokument aktualisieren
• □Nach jeder groesseren Scope-Aenderung docs/PLAN.md mit diesem Dokument abgleichen
• □Nach jeder inhaltlichen Aenderung an dieser Roadmap die Portfolio-Seite neu deployen
• □Erledigte Punkte nicht loeschen, sondern abhaken oder in den Statusbereich verschieben

North Star

Aquila soll am Ende keine bloesse schoene Karte, sondern ein lesbares, historisch gestuetztes Kampagnenspiel sein:

• klare strategische Top-down-Lesbarkeit
• warme, painterly Mittelmeerkarte statt kuehler Digitaloptik
• klickbare Welt mit Staedten, Provinzen, Strassen, Armeen und Entscheidungen
• technische Basis und Produktentwicklung in Unity/C#, waehrend die Python-Pipeline nur Karten- und Tile-Backend bleibt

Aktueller Stand

• ✓Kampagnenkarten-Pipeline in aquila-westmed laeuft lokal reproduzierbar
• ✓Visual Cleanup Pass 1 (A-E) abgeschlossen
• ✓Unity-Prototyp U0 angelegt
• ✓Tile-Streaming U0.2 eingebaut
• ✓U0.2 strukturell stabilisiert (engeres Kamera-Startframing, echte Teilkachel-Geometrie, Low-Zoom-Forest-Mass fuer z0-z2)
• ✓Unity-MCP / CoderGamester fuer Scene- und Console-Checks produktiv nutzbar
• ✓AquilaUnity-Graphify-Baseline + Portfolio-Graph stehen
• ✓U1 Settlement Interaction implementiert (Selection, Deselect, Focus)
• ✓U2 Datenfundament vorbereitet (SettlementRecord erweitert, SettlementRegistry, angereichertes Prototype-JSON)
• ✓Aktive Projektdoku nach AquilaUnity/docs/ verlagert; aquila-westmed bleibt Pipeline-/Archiv-Repo
• ✓Erstes City-Builder-EditorTool mit Karten-Preview, Marker-Auswahl, MoveSelected und JSON-Save gebaut
• ✓City Builder um Settlement-Level, Road-Graph und automatisch berechnete Gate-Preview erweitert
• ✓Terrain-only fal.ai Biome-Materialpalette als Review-Prototyp erzeugt (ohne Waelder)
• ✓Offline Terrain Foundation V2 Preview-Compositor erstellt; falsche logic_mask Klasse 3 als River-Quelle erkannt und im Terrain-Bake zu Land reklassifiziert
• ✓Terrain Foundation V2 im 4x-Spielzoom abgenommen (Till: neue V2-Preview oben rechts im Compare-Sheet ist Zielrichtung)
• ✓Terrain Foundation V2 als aktive Unity-Basemap verdrahten
• ✓Terrain Shader Prototype fuer 5x/6x-Zoom gebaut (URP 2D, live gesampelte fal.ai Biome-Texturen, Fallback-Map darunter)
• ✓echte Fluesse als separaten Shader-Control-Layer bauen (nicht aus logic_mask Klasse 3; Quelle: benannte Rivers aus aquila-westmed Reference-JSON)
• ✓6x-Spielzoom technisch freischalten (minOrthographicSize 1.65)
• ✓Forest-Sprite-Cluster Phase 1 als separaten Runtime-Layer bauen (kleine top-down Sprites, nicht Terrain-Bake)
• ✓Forest-Sprite-Cluster Phase 2 planen und bauen (regionale Varianten, staerker organische kleine Cluster, gedaempftere Tints)
• ✓Map-Tuning u0-015 nach Tills Feedback bauen: Steinanteil reduzieren, Textur-Repetition brechen, Baeume sichtbarer machen
• ✓Map-Tuning u0-016 als harte Overview-Nachkorrektur bauen: Stone-Splat von rocky_hills massiv reduzieren und Rock-Textur dämpfen
• ✓Map-Tuning u0-017 als Gegenkorrektur bauen: Berge ueber echtes Relief-/Hillshade zurueckholen, ohne Lowland wieder zu steinig zu machen
• ✓Map Foundation V3 bauen: dediziertes Relief-/Variance-Overlay (terrain_relief.png, terrain_variance.png) statt weiterer Stone-/Hillshade-Mini-Tweaks
• ✓Forest Mass Hybrid u0-021 bauen: V3-Shader traegt dunkle Waldmasse, Runtime-Sprites sind kleine sparsame Details
• ✓Forest Detail Retune u0-022 bauen: Runtime-Baumzahl wieder auf 2600, Einzelbaumgroesse deutlich kleiner (0.010..0.024)
• ✓Fallback-Map-Audit u0-023: alte steinige westmed_map_4096_biome_preview.png als sichtbaren Fallback in der Shader-Scene deaktiviert
• ✓Forest Density u0-024 bauen: Shader-Speckles + staerkere Waldmasse + 4200 kleine Runtime-Details
• ✓Forest Density u0-025 bauen: Runtime-Baeume auf gebatchte Mesh-Quads umstellen, 42000 deutlich kleinere Baumdetails
• ✓Forest Visibility/Sharpness u0-026 bauen: Forest-Batches auch im Edit Mode sichtbar, Baeume pixel-sichtbar klein, Terrain-Material schaerfer
• □Map Foundation V3 u0-018 visuell abnehmen oder nur Materialwerte feinjustieren
• □U0.2 Playtest formell als stabil freigeben
• □U1/U2 Eyes-on-Playtest als combined slice abnehmen

Milestone 0 - Foundation Lock

Ziel: Die bestehende Karten- und Unity-Basis so stabil machen, dass darauf ohne Angst weitergebaut werden kann.

• □U0.2 Playtest einmal sauber mit Unity + MCP abnehmen
• □pruefen: Tile-Lader, Pan/Zoom, Marker-Klicks, Console sauber
• □dokumentieren: U0.2 in AGENT_LOG.md als APPROVED
• □kleiner Smoke-Test-Workflow definieren, der vor jedem groesseren Unity-Feature erneut gefahren wird

Definition of done

• □keine Console-Errors im Basis-Playtest
• □Tile-Pyramide laedt reproduzierbar
• □Marker/HUD/Camera regressionsfrei

Milestone 0.5 - Map Foundation V3 [ACTIVE]

Ziel: Die Spielkarte muss bei ca. 4x Zoom als Grundlage gut genug aussehen, bevor wir wieder Staedte, Roads und UI darauf stapeln.

• ✓fal.ai terrain-only Biome-Materialien erzeugen
• ✓Terrain-only Offline-Compositor bauen
• ✓falsche Class-3-Wasserflaechen identifizieren und aus dem Terrain-Bake entfernen
• ✓4x-Spielzoom-Crops/Compare gegen Referenzgefuehl pruefen
• ✓Unity-Scene/Tile-Loader auf V2-Basemap umstellen
• ✓Shader-Prototyp als bessere Alternative zum reinen 4096/8192-Tile-Zoom pruefen
• ✓echte Fluesse als separaten Shader-Layer einziehen (terrain_rivers.png: core/bank/valley/mouth)
• ✓Microdetail-Noise fuer Nahzoom einfuehren (terrain_detail_noise.png)
• ✓6x-Spielzoom freischalten
• □Sea-/Land-Kante entscheiden: akzeptieren, mask cleanup, oder neues Coast/Sea-Verfahren
• □Fluesse polishen: Muendungen, Bruecken/Furts, spaetere Road-Anbindung und ggf. Labels
• ✓Forest-Sprite-Cluster als eigener Layer definieren und erste Assets bauen
• ✓Forest-Sprite-Cluster gegen Referenzen tunen: mehr organische Waldgruppen, weniger gleichmaessiger Punktteppich (Phase 2)
• ✓Stein-/Repetition-/Baum-Sichtbarkeits-Tuning u0-015 einziehen
• ✓Stone-Overview-Nachkorrektur u0-016 einziehen (rocky_hills nur noch als kleiner height-gated Akzent)
• ✓Mountain-Readability-Nachkorrektur u0-017 einziehen (directional hillshade statt flacher Hoehenhelligkeit)
• ✓u0-017 reviewen: weiterhin zu flach/gelb und nicht referenznah genug
• ✓Claude/Codex V3-Planreview: Option B, eigenes Relief-/Variance-Overlay
• ✓terrain_relief.png bauen: Hillshade, Ridge-Maske, Valley-Maske, local relief amplitude
• ✓terrain_variance.png bauen: low-frequency painterly Lowland-Patches
• ✓Shader/Material/Scene u0-018 verdrahten
• ✓Review-Captures gegen Referenzen erstellen
• □u0-018 Review-Captures gegen Referenzen sichten und freigeben/feintunen
• ✓Forest Phase 3 planen und bauen: kleinere/dunklere/clusterfoermigere Runtime Tree-Sprites fuer V3
• ✓Forest Phase 4 bauen: einzelne Baeume halbiert, dynamische Cluster-Massen als Waldgruppen-Unterbau
• ✓Forest Mass Hybrid u0-021 bauen: Waldmasse in den V3-Terrain-Shader ziehen, Sprite-Layer auf 900 sehr kleine Detailpunkte reduzieren
• ✓Forest Detail Retune u0-022 bauen: mehr, aber kleinere Baeume nach Tills Feedback
• □Forest Detail Retune u0-022 im Unity Play Mode sichten und freigeben/feintunen
• □Nach u0-023 pruefen: Wenn Steinoptik weiterhin sichtbar ist, Relief/Alpine/Materialwerte tunen statt alten Fallback oder Forest-Layer zu verdächtigen
• □Forest Density u0-025 im Unity Play Mode gegen Referenzen sichten: 42000 Mesh-Baeume muessen bei 4x/6x deutlich feiner/dichter wirken, ohne Console-/Shaderfehler
• □Forest Visibility/Sharpness u0-026 in Unity Scene View pruefen: Forest Sprite Batch XX muss ohne Play sichtbar sein; Zoom darf nicht mehr nur weich-gruen wirken
• ✓Unity-Map-Asset erst ersetzen, wenn Preview wirklich freigegeben ist

Definition of done

• □keine falschen Wasserloecher auf Land
• □Terrain wirkt bei 4x/6x Zoom nicht wie harte Diagnose-/Splatmap und zeigt genug Materialdetail
• ✓Fluesse sind technisch getrennt vom Terrain-Bake
• □Waelder, Roads und Staedte sind bewusst getrennte Layer; Wald besteht jetzt aus Shader-Masse plus kleinem Sprite-Detaillayer
• □Preview-Artefakte sind dokumentiert und reproduzierbar

Milestone 1 - U1 Playable Map Interaction [NEXT]

Ziel: Aus der Karte wird erstmals ein bedienbares Spielgeruest.

• □Settlement anklickbar und eindeutig selektierbar
• □Hover- und Selection-State sauber trennen
• □HUD-Panel fuer Name, Faction, Lon/Lat
• □Deselect durch Klick auf leere Karte
• □Kamera kann auf selektiertes Settlement zentrieren
• □Selection-UX so robust bauen, dass sie spaeter fuer Provinzen/Armeen wiederverwendbar ist

Definition of done

• □ein Marker gleichzeitig selektierbar
• □HUD zeigt korrekte Daten
• □Fokus auf Settlement funktioniert
• □keine Regressions an Tile-Loader und Map-View

Milestone 2 - U2 Campaign Shell [PAUSED UNTIL MAP FOUNDATION V2 REVIEW]

Ziel: Erste echte Kampagnenoberflaeche statt nur Debug-HUD.

• ✓Settlement-Datenfundament fuer die naechste UI vorbereitet (SettlementRegistry, Display-/Region-/Importance-Felder, angereichertes Prototype-JSON)
• ✓Editor-Tool fuer Stadtaufbau mit visueller Karten-Preview vorbereitet
• ✓Settlement-Level und erste Road-/Gate-Daten im Editor sichtbar machen
• □rechter Inspector statt reinem OnGUI-Kasten vorbereiten
• □Layout fuer Top-Bar / Side-Panel / Bottom-Hints festlegen
• □Platzhalter fuer Ressourcen, Runden-/Zeitstatus und Fraktionskontext
• □grundlegende Input-Hierarchie definieren: Karte, UI, Selection, Tool-Modi
• □visuelle Sprache fuer Buttons, Tabs, Info-Panels festlegen

Definition of done

• □UI fuehlt sich wie eine Kampagnenoberflaeche an
• □Debug-Box-Charakter deutlich reduziert
• □Panel-Struktur ist fuer Provinzen, Armeen und Events erweiterbar

Decision Gate A - Was ist der eigentliche Kampagnenloop?

Bevor wir tiefer in Systeme investieren, muessen wir das Spielformat absichern.

• □Entscheidung: rundenbasiert, pausable real-time oder Hybrid
• □Entscheidung: Fokus auf Staat/Fraktion, auf Armee/Generaele oder beides
• □Entscheidung: wie granular ist die Karte spielerisch? Settlements only, Provinzen, Regionen?
• □Entscheidung: wie stark historisch vs. sandboxig?

Ohne diesen Gate riskieren wir, spaeter UI, Provinzen, Armeelogik und AI doppelt zu bauen.

Milestone 3 - U3 World Structure (Settlements, Provinces, Roads)

Ziel: Die Karte bekommt spielbare Struktur.

• □Settlement-Datenmodell ausbauen: IDs, owner, level, tags, ggf. harbor/fort
• ✓erster Level/Road/Gate-Datenansatz im City Builder
• □Provinz-/Regionenmodell definieren
• □Road-Graph aus Python/Source-Daten oder manuell vorbereiten
• □visuelle Darstellung fuer Provinzgrenzen und Strassen
• □Selection kann zwischen Settlement und Provinz unterscheiden
• □Cost-Mask / Bewegungskosten in nutzbares Unity-Format ueberfuehren

Definition of done

• □jedes Settlement gehoert zu einer Provinz/Region
• □Strassen sind sichtbar und logisch nutzbar
• □Karte fuehlt sich nicht mehr wie reine Bildflaeche an

Milestone 4 - U4 Movement and Presence

Ziel: Es gibt erstmals Dinge, die sich auf der Kampagnenkarte bewegen.

• □erstes Army-/Stack-Datenmodell
• □Army-Marker / Banner / Counter definieren
• □Bewegung entlang Strassen und ueber Freiraum regeln
• □Reichweite, ETA oder Zugkosten im UI anzeigen
• □einfache Path-Preview beim Auswaehlen eines Ziels

Definition of done

• □eine Fraktion kann mindestens eine Armee ueber die Karte bewegen
• □Bewegung liest sich visuell klar
• □Wegkosten und Ziel sind fuer den Spieler lesbar

Milestone 5 - U5 Campaign Systems (Ownership, Economy, Supply)

Ziel: Die Karte bekommt strategische Konsequenzen.

• □Besitz/Owner-State fuer Settlements und Provinzen
• □Einnahmen-/Versorgungsmodell minimal definieren
• □Supply-Linien oder Versorgungseinfluss auf Bewegung/Armeen
• □Hafen- und Kuestenlogik als Sonderfall vorbereiten
• □UI fuer Besitzwechsel und einfache Kampagnenwerte

Definition of done

• □Karte reagiert spielmechanisch auf Besitz und Raum
• □Armeen existieren nicht losgeloest von der Welt

Milestone 6 - U6 Conflict Layer

Ziel: Der Schritt von der Strategie- zur Konfliktkarte wird glaubwuerdig.

• □Regeln fuer Begegnung / Blockade / Belagerung / Schlacht-Eintritt definieren
• □erster Kampagnen-Konfliktzustand zwischen zwei Fraktionen
• □UI fuer "angreifen", "belagern", "abweichen", "zurueckziehen" vorbereiten
• □spaeterer Uebergang zu separatem Battle-Prototyp oder abstrahierter Kampfauswertung entscheiden

Definition of done

• □der Spieler kann mehr tun als nur bewegen und anschauen
• □Konflikte sind auf der Kampagnenkarte abbildbar

Milestone 7 - U7 Visual Cleanup Pass 2

Ziel: Die Karte soll deutlich naeher an die Referenzbilder ruecken.

• □globale Waerme steigern (Hillshade / Warmth / Palette)
• □Wald als Masse statt Punktkonfetti lesbar machen
• □ggf. STYLE_FOREST_SPRITE_RENDER_SCALE einfuehren
• □Composition-Pruefung mit echten Campaign-Layern statt nur nackter Karte
• □entscheiden, ob Unity-Side Shader/Mesh-Prototyp noetig ist oder Python-Basis reicht

Definition of done

• □Karte wirkt weniger digital-kuehl
• □Referenzabstand ist sichtbar kleiner
• □Spiel-Layer und Karte harmonieren zusammen

Decision Gate B - Bleibt die Karte 2D-Sprite-basiert oder wechseln wir spaeter zu Mesh/Shader?

Das ist ein groesserer Architekturhebel und soll erst nach funktionierendem Kampagnenkern entschieden werden.

• □pruefen, ob Python-Map + Tile-Streaming fuer den Ziel-Look ausreicht
• □pruefen, ob Unity-Mesh/Heightmap/Shader echten Mehrwert bringt oder nur Komplexitaet
• □Entscheidung dokumentieren, bevor ein groesserer Rendering-Umbau beginnt

Milestone 8 - U8 Content Expansion

Ziel: Aus dem Prototyp wird eine echte Kampagnenwelt.

• □mehr historische Settlements
• □Fraktionsdaten und Startbesitz
• □Provinz-Content / regionale Identitaet
• □Events, Missions oder Startskripte
• □Save/Load-Grundlage

Definition of done

• □die Karte fuehlt sich nicht mehr wie Demo, sondern wie Kampagnenraum an

Parallel-Arbeitsmodell

Codex

• plant die naechsten Milestones und Slices
• prueft Scope, Risiken und Reihenfolge
• reviewed Unity- und Python-Aenderungen
• haelt PLAN, DECISIONS, CHANGELOG, AGENT_LOG und Portfolio-Sync sauber

Claude Code

• implementiert den freigegebenen Slice in Unity oder Python
• bleibt innerhalb der vereinbarten Dateien / Module
• dokumentiert kurz, was getan wurde und was offen bleibt

Till

• gibt Zielrichtung, Referenzlook und Prioritaeten vor
• testet echte Bedienbarkeit im Editor
• entscheidet an den grossen Design-Gates

Update-Trigger fuer diese Roadmap

Roadmap aktualisieren, wenn mindestens einer dieser Punkte eintritt:

• □aktiver Milestone wechselt
• □ein Decision Gate wird entschieden
• □Scope eines Milestones veraendert sich deutlich
• □ein geplanter Block wird gestrichen oder neu aufgenommen
• □Website/Portfolio soll einen neuen Aquila-Status spiegeln

Kurzfristige Reihenfolge ab jetzt

1. U0.2 sauber freigeben
2. U1 Settlement Interaction bauen
3. Campaign Shell definieren
4. Decision Gate A klaeren
5. Provinzen/Strassen/Bewegung aufbauen
6. erst dann tiefer in Kriegssysteme und grossen Visual Pass 2 investieren