InfiniTower/docs/adr/0001-balancing-daten-als-rust-konstanten.md

ADR-0001: Balancing-Daten als Rust-Konstanten hinter einer Balance-Resource

• Status: Angenommen
• Datum: 2026-08-10
• Betrifft: Wellenkurven, Kosten und Wirkung von In-Run-Upgrades, Workshop-Upgrade-Kurven, Gegner-Stats pro Archetyp, Card-Effekte

Kontext

Der Slice braucht einen Ort für seine Balancing-Zahlen. Die Datenmenge ist klein und bekannt: drei bis vier Gegner-Archetypen, die tragenden Turm-Stats (Damage, Attack Speed, Health, Defense, optional Crit), Workshop-Upgrades mit 20–50 Leveln, Cards mit maximal sieben Stufen, eine Ultimate.

Zwei Größen sind nicht aus dem Referenzspiel ableitbar und müssen von Hand getunt werden: die HP-/Schadens-Skalierung pro Welle und die Kostenkurven der Upgrades. Das Wiki dokumentiert beides nicht (siehe docs/WikiData.md). Wie teuer eine Tuning-Iteration ist, ist deshalb das entscheidende Kriterium.

Gemessen (dieses Repo, examples/perf_spike.rs als Stellvertreter für einen realen Gameplay-Crate, ~490 Zeilen; Bevy-Dependencies bereits kompiliert im gemeinsamen CARGO_TARGET_DIR):

Vorgang	Zeit
Inkrementeller Rebuild --release (Datei angefasst)	9–10 s
Inkrementeller Rebuild dev	22–26 s
Prozessstart bis Fenster und Frames	~1,4 s
Edit-to-see-Loop (Release)	~11 s

Der Release-Build ist schneller als der Debug-Build — das Linken der Debug-Info dominiert. Die Annahme „Balancing braucht Release, also ist der Rebuild teuer" ist damit empirisch widerlegt.

Dagegen steht der Rest der Schleife: Eine Wellenkurve bewertet man, indem man von Welle 1 an spielt. Das kostet Minuten, nicht Sekunden. Die ~11 s Rebuild sind ein einstelliger Prozentsatz eines Tuning-Zyklus.

Was Bevy 0.19 mitbringt (geprüft über docs.rs und context7, nicht aus dem Gedächtnis):

• Es gibt keinen eingebauten generischen Loader für strukturierte Daten (RON/TOML/JSON) für eigene Typen. Ein eigener AssetLoader ist Pflicht (Vorbild: Bevy-Beispiel custom_asset).
• Hot-Reload erfordert das nicht-default Cargo-Feature file_watcher. AssetPlugin::watch_for_changes_override ist laut Doku ausdrücklich nicht der empfohlene Weg.
• ron (0.12.2) und serde (1.0.229) liegen bereits als transitive Dependencies im Cargo.lock; sie direkt zu deklarieren kostet keine zusätzliche Compile-Zeit. file_watcher dagegen zieht notify neu ein und funktioniert nur auf Desktop.

Randbedingungen: Desktop nativ zuerst, Mobile und Web später (siehe Slice-Scope in CONTEXT.md) — auf Wasm gibt es keinen Dateisystem-Watcher, und Assets müssten asynchron über HTTP geladen werden. Kein Modding-Ziel, keine externen Autoren, ein Entwickler mit Toolchain.

Entscheidung

Die Balancing-Daten leben als Rust-Konstanten in einem eigenen Modul balance, das eine einzige Balance-Resource befüllt. Gameplay-Systeme lesen ausschließlich Res<Balance> und sehen die Konstanten nie.

Verbindlich:

1. balance enthält nur Daten und Datenstrukturen — keine Gameplay-Logik, keine Bevy-Systeme.
2. Balance ist eine Resource aus reinen Datenstrukturen, so geformt, dass sie ohne Umbau serialisierbar wäre (flache Felder, Zahlen und Vektoren, keine Handle, keine Entity). Ein serde-Derive wird jetzt nicht hinzugefügt.
3. Genau eine Funktion befüllt Balance aus den Konstanten. Sie ist die Naht, an der ein späterer Asset-Ladepfad ansetzt.
4. Kein Gameplay-Code liest eine Konstante aus balance direkt. Diese Regel ist die einzige Bedingung, unter der die Entscheidung ihren Wert behält.

Verworfene Alternativen

• Konstanten verstreut im Gameplay-Code — gleiche Iterationskosten wie die gewählte Lösung, aber ein späterer Wechsel auf Assets würde jedes System anfassen, das eine Zahl liest.
• Daten-Assets (RON) über den AssetServer mit Hot-Reload — der Preis (eigener AssetLoader, direkte serde-/ron-Deps, file_watcher mit notify, ein Lade-Zustand im Start-Ablauf, ausgelieferte Asset-Dateien plus asynchrones Laden auf Web und Mobile) kauft ~11 s pro Tuning-Zyklus, dessen teurer Teil das Spielen ist. Zusätzlich: Eine Wellenkurve lässt sich mitten im Run ohnehin nicht sinnvoll austauschen — die laufende Welle hat ihre Werte bereits vergeben, man startet den Run neu.
• bevy_common_assets statt eigenem Loader (0.17.0 unterstützt bevy 0.19.0) — spart den Loader-Code, ändert aber nichts an den übrigen Kosten und tauscht sie gegen eine Dependency, deren Release-Takt an Bevy-Versionen hängt.
• Konfiguration über Umgebungsvariablen (wie in examples/perf_spike.rs) — trägt für ein paar Spike-Knöpfe, nicht für Tabellen mit 50 Leveln.

Abweichung von der naheliegenden Wahl

Die übliche Antwort in der Spieleentwicklung lautet „Daten raus aus dem Code". Sie stammt aus Kontexten, die hier nicht gelten: mehrere Designer ohne Compiler, Balancing-Patches ohne Client-Update, Modding. Der Slice hat keinen davon. Wo die Zahl steht, ist deshalb nicht die Frage, die die Iterationszeit entscheidet — die entscheidende Frage ist, ob man die Zahl ohne Neustart ändern und die interessante Welle ohne Vorspielen erreichen kann. Beides adressiert kein Dateiformat, sondern ein Debug-Panel, das Balance im laufenden Prozess mutiert, plus einen Sprung-zu-Welle-Pfad. Beides setzt auf Res<Balance> auf, also auf genau die Naht, die diese ADR festlegt — und beides ist billiger als eine Asset-Pipeline.

Konsequenzen

Positiv

• Keine neuen Dependencies, kein neues Cargo-Feature, kein Lade-Zustand im Start-Ablauf.
• Keine Plattform-API im Spielkern — Mobile und Web erben keine Asset-Auslieferung.
• Falsche Zahlen und fehlende Felder sind Compile-Fehler statt Laufzeit-Parse-Fehler.
• Balancing-Werte sind in die Binary gebacken; ein Save kann nicht auf Werte verweisen, die es im aktuellen Build nicht mehr gibt.

Negativ

• Jede Zahländerung kostet einen Rebuild (~11 s heute, wachsend mit dem Crate).
• Nicht-Entwickler können nicht balancen. Für den Slice irrelevant, für ein späteres Ziel nicht.
• Das Bevy-Asset-System bleibt in diesem Bereich ungelernt. Wenn das ein Lernziel ist, gehört es in ein eigenes Ticket mit einem echten Asset (z. B. Sprites), nicht in die Balancing-Daten.

Folgeaufgaben (nicht Teil dieser ADR)

• Run-Telemetrie (Zeit bis Tod, Coins pro Welle, DPS-Verlauf) — ohne sie beschleunigt ein schnellerer Edit-Loop nur das Raten.
• Debug-Panel und Sprung-zu-Welle-Pfad, beide auf Res<Balance>.

Revisions-Auslöser

Diese Entscheidung wird neu getroffen, sobald eines der folgenden Ereignisse eintritt:

1. Rebuild-Schwelle: cargo build --release nach einer Änderung, die nur src/balance/ berührt, dauert wiederholt über 30 s (heute 9–10 s). Nachmessen mit derselben Methode wie oben: Datei anfassen, bauen, drei Läufe, Median.
2. Zyklus-Schwelle: Eine protokollierte Tuning-Session enthält mehr als 30 Rebuild-Zyklen pro Stunde, deren Diff ausschließlich src/balance/ betrifft. Das ist der Punkt, an dem die 11 s messbar zur dominierenden Kostenstelle werden — vorher nicht.
3. Scope-Änderung: Balancing-Werte müssen von jemandem geändert werden können, der keine Rust-Toolchain hat, oder ohne neuen Build ausgeliefert werden (Live-Balancing, Modding, externe Tester). Keines davon steht im Slice-Scope.

Auslöser 1 und 2 werden zuerst durch das Debug-Panel beantwortet, nicht durch Assets — es ist die billigere Antwort auf dieselbe Beobachtung. Erst wenn das Panel gebaut ist und die Schwelle weiterhin gerissen wird, ist der Wechsel auf Assets fällig. Auslöser 3 führt direkt zu Assets.