InfiniTower/docs/adr/0002-stat-und-modifier-pipeline.md

# ADR-0002: Stat- und Modifier-Pipeline

- **Status:** Angenommen
- **Datum:** 2026-08-10
- **Betrifft:** Turm-Stats, Workshop, Cards, In-Run-Upgrades, Ultimate; Datentyp aller Stat-Werte
- **Baut auf:** ADR-0001 (Balancing-Daten als Rust-Konstanten hinter `Balance`)

## Kontext

Vier Quellen wirken auf dieselben Turm-Stats: **In-Run-Upgrades** (verfallen am Run-Ende),
**Workshop** (permanent), **Cards** (1–5 Slots im Slice) und die **Ultimate** (Death Wave,
zeitlich begrenzt). Ohne feste Stapelregel wird jede neue Quelle zu einer eigenen Sonderregel,
und ein Save, der einen berechneten Wert speichert, friert eine Formel ein, die sich noch ändert.

Zwei Randbedingungen aus dem Repo:

- Es gibt genau **einen** Turm. Ticket #4 hat gemessen: bei 10 000 Gegnern kostet die gesamte
  Gameplay-Logik **0,114 ms von 16,67 ms**; 96–98 % gehen ins Rendering. Eine Stat-Berechnung
  pro Frame wäre nicht messbar. Performance ist hier also **kein** Argument.
- Alle Zahlen kommen laut ADR-0001 aus `Res<Balance>`. Diese ADR fügt keine Zahlen hinzu,
  sondern nur die Struktur, in der sie stehen. Auch die Clamp-Grenzen sind Balancing-Werte und
  leben in `Balance`.

**Geprüft an der Bevy-0.19-Doku** (docs.rs, über context7): Components lassen sich zur Laufzeit
über `commands.entity(e).insert(..)` / `.remove::<T>()` an- und abheften; `RemovedComponents<T>`
und die Lifecycle-Hooks `on_add`/`on_insert`/`on_discard`/`on_remove` existieren, werden hier
aber **nicht** gebraucht (siehe Entfernungspfad). Change Detection über `Res<T>::is_changed()`
und `Changed<T>` ist der Auslöser der Neuberechnung. `Resource` = weltweit genau einmal,
`Component` = an eine Entity gebunden und stirbt mit ihr — dieser Unterschied trägt unten die
Run-Grenze.

## Entscheidung

### 1. Drei Akkumulatoren, ein Anwendungsmodus pro Stat

Jeder Stat sammelt drei Akkumulatoren:

| Akkumulator | Einheit | Verknüpfung |
|---|---|---|
| `flat` | absolute Einheiten des Stats | additiv |
| `points` | Prozentpunkte (0,15 = +15 pp) | additiv, **einmal am Ende** geclamped |
| `mult` | Faktor | multiplikativ |

Jeder Stat trägt zusätzlich **ein Bit**, seinen Anwendungsmodus:

- **`Direct`** — der Wert wächst mit dem Bonus:
  `(base + flat) × (1 + clamp(points)) × mult`
- **`Interval`** — der Wert ist eine Zeitspanne in Sekunden und **schrumpft** mit dem Bonus:
  `(base + flat) × (1 − clamp(points)) ÷ mult`

Der Modus ist eine Eigenschaft des Stats, kein Sonderfall des Modifikators. Damit gibt es drei
Akkumulatoren und vier Anwendungsregeln, ohne dass irgendwo eine fünfte Regel entsteht.

Zeitbasierte Stats bleiben **Intervalle, keine Raten**: Der Spieler liest „12 s Cooldown", nicht
„0,083 Auslösungen/s". Eine Cooldown-Reduktion ist deshalb kein eigener Akkumulator, sondern
`points` im `Interval`-Modus.

### 2. Clamp: summieren, dann einmal begrenzen

`clamp(points)` ist `points.clamp(0.0, cap)`. Das `cap` ist ein Balancing-Wert und steht in
`Balance.caps`, pro Stat einer (Crit Chance, Defense %, jeder Cooldown). Es gibt keinen globalen
Clamp und keinen Default im Code.

Geclamped wird **die Summe, genau einmal, nach der Summierung** — nie pro Quelle. Folgen, die
ausdrücklich gewollt sind:

- Die Reihenfolge der Quellen ist egal; das Ergebnis ist assoziativ und kommutativ.
- Es gibt **keine** abnehmenden Erträge, sondern eine harte Wand. Liefern drei Quellen je 30 pp
  Cooldown-Reduktion bei `cap = 0,60`, wirken 60 pp und 30 pp verfallen ersatzlos.
- Die **ungeclampte** Summe bleibt für die Anzeige erhalten (siehe Sichtbarkeitsanforderung).
  Sie wird nicht persistiert, sondern bei der Neuberechnung nebenher ermittelt.

### 3. Stat-Tabelle

`base` kommt immer aus `Balance`. „Erwartet" nennt die Akkumulatoren, die im Slice tatsächlich
bespielt werden — technisch stehen jedem Stat alle drei offen (die übrigen sind 0 bzw. 1).

| Stat | `base` | Modus | Erwartet | Clamp |
|---|---|---|---|---|
| `Damage` | > 0 | Direct | `flat` (Workshop, In-Run), `mult` (Cards) | — |
| `AttackInterval` | > 0 | **Interval** | `mult` (Workshop, Cards, In-Run) | — |
| `Range` | > 0 | Direct | `mult` | — |
| `MaxHealth` | > 0 | Direct | `flat` (Workshop, In-Run), `mult` (Cards) | — |
| `CritFactor` | > 0 | Direct | `mult` | — |
| `CoinGain` | 1,0 | Direct | `mult` | — |
| `CritChance` | 0 | Direct | `points` | `caps.crit_chance` |
| `DefensePercent` | 0 | Direct | `points` | `caps.defense_percent` |
| `HealthRegen` | **0** | Direct | `flat` (Workshop), `mult` (Cards) | — |
| `DefenseFlat` | 0 | Direct | `flat`, `mult` | — |
| `UltimateCooldown` | > 0 | **Interval** | `points` | `caps.cooldown_reduction` |
| `WaveCooldown` | > 0 | **Interval** | `points` | `caps.wave_cooldown_reduction` |

`HealthRegen` und `DefenseFlat` sind der Grund für den flachen Akkumulator: Ihre Basis ist 0,
und ein rein multiplikativer Bonus auf 0 bleibt 0. Dasselbe gilt später für Lifesteal und Thorns.

**`AttackInterval` ist der Stat, der die Zuordnung fast gesprengt hätte.** „Attack Speed ×1,25"
ist genrenüblich eine Rate, und eine Rate widerspricht der Intervall-Regel. Der
`Interval`-Modus löst das ohne Sonderregel: Die Karte liefert `mult = 1,25`, das Intervall wird
geteilt, der Spieler sieht weiterhin „×1,25 Angriffsgeschwindigkeit", und der Schuss-Timer
bekommt direkt eine Dauer. Deshalb heißt der Stat `AttackInterval` und nicht `AttackSpeed`.

### 4. `type Stat = f32`

Alias, kein Newtype. f32 trägt sieben signifikante Stellen — genug für den Slice.
Revisions-Auslöser unten.

### 5. Nur Quellen werden persistiert

Ein Save enthält **niemals** einen berechneten Wert: gespeichert werden Workshop-Level, besessene
und ausgerüstete Cards mit ihrem Level, die Slot-Zahl und (falls ein Run fortgesetzt wird) die
In-Run-Upgrade-Level. Alles andere wird beim Laden neu gerechnet.

Das entkoppelt #7 (Save/Load) vollständig von dieser ADR: Jede Formeländerung wirkt rückwirkend
auf bestehende Saves, ohne Migration. Es ist die einzige Festlegung hier, deren spätere Rücknahme
wirklich teuer wäre.

### 6. Herkunft steckt im Ablageort, nicht im Datenmodell

Die Akkumulatoren tragen **keine** Herkunftsmarkierung. Sie sind ein reiner Cache und werden bei
jeder Änderung **vollständig aus den Quellen neu gerechnet** — nie inkrementell addiert oder
subtrahiert. Bei einem Turm und ≤ 5 Slots ist das eine Handvoll Multiplikationen; die einzige
Alternative wäre Buchführung über das Rückgängigmachen einzelner Beiträge, und genau die geht
schief.

Die Herkunft, die man wirklich braucht, ist die Run-Grenze. Sie wird nicht als Feld ausgedrückt,
sondern als Ablageort:

| Lebensdauer | Ablage | Beispiele |
|---|---|---|
| permanent | `Resource` | `Balance`, `Workshop`, `OwnedCards`, `EquippedCards` |
| Run-gebunden | `Component` **an der Turm-Entity** | `RunUpgrades`, `EffectiveStats`, Ultimate-Buff, alle Fähigkeits-Components |

Die Turm-Entity wird **beim Run-Start gespawnt und beim Run-Ende despawnt**. Damit verschwindet
am Run-Ende genau das, was verschwinden muss, ohne dass irgendein Code es aufräumt. Kein
`clear()`, keine Reset-Liste, die man beim nächsten Feature zu erweitern vergisst.

Für die UI-Frage „woher kommen meine 340 % Damage?" gibt es eine Funktion, die die
Neuberechnung mit Zwischenwerten pro Quelle ausführt und das Ergebnis zurückgibt. Sie wird auf
Anforderung aufgerufen, nicht im Gameplay-Pfad, und speichert nichts.

### 7. `EffectiveStats` wird bei Änderung berechnet — aus Nachvollziehbarkeit

`EffectiveStats` ist ein `Component` an der Turm-Entity, kein `Resource`. Genau ein System
schreibt es, und es läuft, wenn eine Quelle sich geändert hat (`is_changed()` auf den
Quell-Resources, `Changed<..>` auf den Quell-Components) — nicht jeden Frame.

Der Grund ist **nicht** Performance. Jeden Frame zu rechnen wäre bei 0,114 ms Gesamtbudget für
die Gameplay-Logik nicht messbar. Der Grund ist, dass es dann genau einen Zeitpunkt gibt, an dem
ein Stat sich ändert: ein Breakpoint, eine Log-Zeile, ein Wert, den man ansehen kann. Bei
Neuberechnung pro Frame wäre jeder falsche Wert ein Beobachtungsproblem statt eines Fehlers an
einer Stelle.

### 8. Card-Effekte sind ein `enum`

```rust
type Stat = f32;

enum CardEffect {
    Modifier { stat: StatKind, kind: ModifierKind, value: Stat },
    Ability(AbilityKind),
}

enum ModifierKind { Flat, Points, Mult }
```

Kein Trait-Object, keine Registry, kein Plugin-Mechanismus. Null externe Autoren, kein
Modding-Ziel (ADR-0001, Slice-Scope). Ein neuer Stat-Modifikator ist eine neue `StatKind`-Variante
plus eine Zeile in `Balance`; der Compiler zeigt jede Stelle, die nachziehen muss. Genau das ist
der Nutzen und nicht der Preis.

### 9. Fähigkeiten sind Components, keine Zahlen

Ein Card-Effekt der Gruppe `Ability` heftet ein eigenes Component an die Turm-Entity —
`DeathRay { duration }`, `SlowAura { factor }` — mit einem eigenen System. Death Ray ist kein
Stat und wird nicht in die Zahlen-Pipeline gepresst. Fähigkeits-Parameter (Dauer, Radius) leben
im Component, nicht in `EffectiveStats`.

Das fängt auch die Modifikatoren ab, die gar nicht am Turm ansetzen: `SlowAura` verändert die
Geschwindigkeit von Gegnern. Als Stat wäre das ein Fremdkörper, als Component am Turm, das
das Gegner-Bewegungssystem liest, ist es die naheliegende Form.

**Fähigkeits-Components dürfen keinen Zustand tragen, der einen Run überdauern soll.** Cooldowns
und Timer im Component sind in Ordnung — sie sollen beim Neuaufbau zurückgesetzt werden.
„Einmal pro Run"-Zustand gehört in eine Run-gebundene Ablage, die nicht bei jedem
Karten-Abgleich neu geschrieben wird.

### 10. Entfernungspfad für Fähigkeits-Components

Eine nicht entfernte Fähigkeits-Component ist der wahrscheinlichste Bug dieser Architektur: Sie
zeigt sich Wochen später als „der Turm hat manchmal noch den Death Ray", und dann ist die
Ursache nicht mehr rückverfolgbar. Der Schutz ist strukturell, nicht disziplinarisch:

**Ein einziges System `sync_tower_abilities` ist der einzige Schreiber von
Fähigkeits-Components.** Es fügt nirgends an der Stelle ein, an der eine Karte gewechselt wird.
Es läuft mit derselben Änderungserkennung wie die `EffectiveStats`-Neuberechnung und gleicht ab:
Für jede `AbilityKind`-Variante wird das Soll (aus den Quellen) mit dem Ist (`Has<T>` an der
Turm-Entity) verglichen, fehlende Components werden per `insert` ergänzt, überzählige per
`remove::<T>()` entfernt. Weil abgeglichen und nicht ereignisweise gepflegt wird, fallen die drei
geforderten Fälle auf denselben Pfad:

1. **Card-Wechsel im laufenden Run** — `EquippedCards` ändert sich → Abgleich läuft → die
   Component der abgelegten Karte wird per `remove::<T>()` entfernt, die der neuen eingefügt.
   Das ist der einzige Fall, in dem überhaupt jemand entfernt.
2. **Run-Ende** — die Turm-Entity wird despawnt. Es gibt nichts zu entfernen; die Components
   verschwinden mit der Entity. Deshalb steht in Punkt 6, dass alles Run-gebundene an der
   Turm-Entity hängt.
3. **Laden eines Saves** — der Save enthält nur Quellen (Punkt 5). Laden heißt: Quellen setzen,
   Turm frisch spawnen, Abgleich einmal vor dem ersten Gameplay-Frame laufen lassen. Eine
   übriggebliebene Component kann es nicht geben, weil die Entity gerade erst entstanden ist.

Dazu eine `debug_assert`-Prüfung am Ende des Abgleichs: Die Menge der Fähigkeits-Components an
der Turm-Entity ist gleich der aus den Quellen abgeleiteten Menge. Bei einem Turm kostet das
nichts und verwandelt den späten, unauffälligen Bug in einen sofortigen Abbruch.

Bevys Lifecycle-Hooks und `RemovedComponents` werden dafür ausdrücklich **nicht** verwendet: Ein
Abgleich, der das Soll kennt, braucht keine Benachrichtigung darüber, was gerade passiert ist.

### 11. Sichtbarkeitsanforderung an jeden neuen Modifikator

Ein Modifikator, dessen Wirkung der Spieler nicht spürt, hat versagt — und keine technische
Prüfung zeigt das an. Der Compiler akzeptiert einen Bonus, der gegen einen Clamp läuft, und ein
Test, der die Formel prüft, ist grün.

**Verbindlich für jeden neuen Modifikator, vor dem Merge:**

1. Der Autor nennt eine Fortschritts-Stelle, an der der Modifikator wirken soll (Welle, Workshop-
   Stand, Card-Level).
2. Er notiert den betroffenen `EffectiveStats`-Wert **vor und nach** dem Modifikator an dieser
   Stelle — mit der ungeclampten Summe, falls ein Clamp beteiligt ist.
3. Er nennt die **beobachtbare** Folge in einer Größe, die die Run-Telemetrie aus ADR-0001
   ohnehin erfasst: Zeit bis Welle N, DPS-Verlauf, Coins pro Minute, überlebte Welle. Die
   Änderung muss dort über der Streuung zwischen zwei Läufen liegen.
4. **Läuft der Modifikator an der genannten Stelle in einen Clamp, ist er abgelehnt** — nicht
   dokumentiert, nicht mit einem Hinweis versehen: abgelehnt oder umskaliert. Ein Bonus, der
   ersatzlos verfällt, ist im Spiel nicht von einem fehlenden Bonus zu unterscheiden.

Punkt 3 ist die einzige Anforderung, die sich nicht am Schreibtisch erfüllen lässt, und deshalb
die einzige, die wirkt.

## Durchgerechnetes Beispiel

> **Alle Zahlen sind Platzhalter.** Die echten Werte entscheidet Ticket #8. Hier zählt der
> Rechenweg, nicht das Ergebnis.

**Damage** (Modus `Direct`), Basis 10, Workshop-Level 12 zu +1,20 je Level, zwei Cards:

| Schritt | Rechnung | Wert |
|---|---|---|
| Basis aus `Balance` | — | 10,00 |
| `flat` = Workshop Damage Lv 12 × 1,20 | 10,00 + 14,40 | 24,40 |
| `points` = 0 (keine Quelle liefert pp auf Damage) | 24,40 × (1 + 0,00) | 24,40 |
| `mult` = Card „Damage" Lv 3 (×2,40) × Card „Berserker" Lv 5 (×1,30) = 3,12 | 24,40 × 3,12 | **76,13** |

Ein In-Run-Upgrade „+15 pp Damage" (hypothetisch, ohne Clamp auf diesem Stat) ergäbe
`24,40 × 1,15 × 3,12 = 87,55` — die Prozentpunkte greifen **vor** den Multiplikatoren, nicht
danach.

**Health Regen** (Basis **0**), zeigt, wozu der flache Akkumulator da ist:
`(0 + 4,00 Workshop) × 1,60 (Card Lv 2) = 6,40 HP/s`.
Ohne flachen Akkumulator: `0 × 1,60 = 0`. Die Karte wäre wirkungslos.

**Ultimate-Cooldown** (Modus `Interval`), Basis 60 s, `caps.cooldown_reduction = 0,60`:
Workshop −8 pp und Card −30 pp ergeben 38 pp → `60 × (1 − 0,38) = 37,2 s`.
Kommt eine dritte Quelle mit −30 pp dazu, ist die Summe 68 pp, geclamped auf 60 pp →
`60 × 0,40 = 24,0 s`. Von den 30 pp der dritten Quelle wirken nur 22, die restlichen 8 verfallen
ersatzlos — eine vierte Quelle wäre komplett wirkungslos. Genau das lehnt die
Sichtbarkeitsanforderung ab.

## Verworfene Alternativen

- **Nur additiv oder nur multiplikativ.** Rein additiv verpufft im Endgame, rein multiplikativ
  lässt Stats mit Basis 0 (Health Regen, später Lifesteal, Thorns) unerreichbar. Beide Formen
  scheitern an je einer Hälfte der Stat-Tabelle.
- **Additiv innerhalb einer Quelle, multiplikativ zwischen Quellen** (die Frage aus dem Ticket).
  Klingt ordentlich, koppelt aber die Rechenregel an die Herkunft: Dieselbe Karte wirkt anders,
  je nachdem, ob ein Workshop-Upgrade denselben Stat trifft. Die drei Akkumulatoren erreichen
  dasselbe Verhalten, ohne dass ein Modifikator wissen muss, wer sonst noch am Stat hängt.
- **Modifikatoren als Liste mit Herkunft, Entfernen durch Subtraktion.** Braucht eine stabile
  Identität pro Modifikator, Buchführung beim Run-Ende und ist gegen Rundungsdrift bei f32 nicht
  robust. Vollständige Neuberechnung kostet bei einem Turm nichts und hat keinen dieser Fehler.
- **Card-Effekte als Trait-Objects oder Registry.** Kauft Erweiterbarkeit ohne externe Autoren.
  Der Preis ist der Verlust der Vollständigkeitsprüfung durch den Compiler — genau die Prüfung,
  die einen vergessenen Stat sichtbar macht.
- **Fähigkeiten als Stat-Werte** (z. B. „Death-Ray-Stärke" als Zahl in `EffectiveStats`). Zwingt
  jede Fähigkeit in eine Skalarform, die sie nicht hat, und lässt `EffectiveStats` um Felder
  wachsen, die kein Gameplay-System liest.
- **`EffectiveStats` als `Resource`.** Funktioniert bei einem Turm, verliert aber die Kopplung
  an die Entity-Lebensdauer — und damit den kostenlosen Reset am Run-Ende, der in Punkt 10 die
  Bug-Klasse verhindert.

## Offene Punkte, die diese ADR nicht entscheidet

- **`MaxHealth` ist der einzige Stat mit einem veränderlichen Ist-Wert daneben.** Steigt
  `MaxHealth` mitten im Run, muss entschieden werden, ob die aktuelle HP mitwächst, den Anteil
  behält oder unverändert bleibt. Das ist keine Frage der Pipeline, sondern des Health-Systems;
  es ist hier nur festgehalten, damit es nicht zwischen den Tickets verschwindet.
- **Bedingte Modifikatoren** („nur gegen Bosse", „skaliert mit erlittenem Schaden" wie
  Berserker). Im Slice gibt es keinen; taucht einer auf, ist er entweder eine `Ability` oder er
  bricht die Zwei-Gruppen-Teilung des `enum` (siehe Revisions-Auslöser 3).

## Konsequenzen

**Positiv**

- Ein Save enthält keine Formel. Balancing- und Formeländerungen wirken rückwirkend, ohne
  Migration.
- Das Run-Ende braucht keinen Aufräum-Code, den man beim nächsten Feature erweitern müsste.
- Ein neuer Stat oder Modifikator erzeugt Compile-Fehler an genau den Stellen, die nachziehen
  müssen.
- Die Stapelregel ist reihenfolgeunabhängig; es gibt keine „richtige" Sortierung von Quellen.

**Negativ**

- Der Clamp ist eine harte Wand. Ohne die Sichtbarkeitsanforderung entstehen wirkungslose
  Modifikatoren, die niemandem auffallen. Die Prüfung ist manuell und damit die schwächste
  Stelle dieser ADR.
- Vollständige Neuberechnung skaliert nicht auf viele Turm-artige Entities mit vielen Quellen.
  Bei einem Turm ist das irrelevant, und die Alternative wäre die Buchführung, die oben
  verworfen wurde.
- Ein neuer Effekt, der weder Stat-Modifikator noch Fähigkeit ist, erzwingt eine Änderung am
  `enum` und an jedem `match`. Das ist beabsichtigt, aber es ist Arbeit.
- Die Ablageregel „Run-gebunden = Component an der Turm-Entity" ist eine Konvention. Sie hält
  nur, solange sie eingehalten wird; ein Run-Zustand, der versehentlich als `Resource` landet,
  überlebt den Run und bringt genau den Bug zurück, den Punkt 10 verhindern soll.

## Revisions-Auslöser

1. **Zahlentyp:** Ein Stat-Wert im Spiel überschreitet **10⁶**, oder eine Anzeige rundet
   sichtbar (zwei Läufe mit gleichem Stand zeigen unterschiedliche letzte Stellen). Dann wird
   `type Stat` neu entschieden — f64 zuerst, Big-Number-Semantik nur, wenn f64 auch reißt.
2. **Mehrere Turm-artige Entities:** Sobald mehr als eine Entity `EffectiveStats` trägt, ist die
   Änderungserkennung pro Entity zu prüfen — global geänderte Quellen müssten dann alle
   betreffen, entity-eigene nur eine.
3. **Dritte Effektgruppe:** Ein Card-Effekt, der weder als `Modifier` noch als `Ability`
   ausdrückbar ist, kippt die Zwei-Gruppen-Teilung. Ein Fall reicht; es ist keine Frage der
   Häufigkeit.
4. **Clamp-Druck:** Wenn an der vorgesehenen Fortschritts-Stelle mehr als eine Quelle je Stat
   regelmäßig am Clamp anschlägt, ist nicht der Modifikator falsch, sondern das
   Prozent-Budget — dann wird die harte Wand gegen abnehmende Erträge neu bewertet.