Jander_Semester2/Semesterprojekt/docs/superpowers/specs/2026-06-01-use-x-on-y-design.md

# Spec: Item-Kombination `use X on Y`

Stand: 2026-06-01. Erste der verbleibenden Mechaniken nach Hauptmenü +
Speichern/Laden. Setzt das in `enhancement-ideas.md` #5b (Mechanik-Spine §4)
festgelegte Item-Kombinations-Feature um. Baut auf der bestehenden
Condition/Effect-Engine, dem datengetriebenen Loader (wie quests/endings) und
dem vorhandenen `UseCommand` auf.

## 1. Kontext & Ziel

v1.0 hat bewusst argloses `use X` ohne Ziel gewählt. Ziel jetzt: **`use X on Y`**
als datengetriebene **Kombinations-Mechanik** — ein Rezept kann Bedingungen
prüfen, Items verbrauchen, ein Item erzeugen, Flags setzen und einen Text
ausgeben. Deckt sowohl Transform (`matches + torch → lit_torch`) als auch
Anwenden-auf-Ziel (`use key on door → effekt`) mit *einem* Modell ab.

Bestätigte Entscheidungen (Brainstorming 2026-06-01):
- **Allgemeine, datengetriebene Rezepte** (requires / consume / produce / effects
  / response / failText) — Superset, nutzt die vorhandene Engine.
- **Operanden** lösen aus **Inventar oder aktuellem Raum** auf (`use key on door`,
  `use matches on torch`).
- **Fehlschlag**: kein Rezept → generische Zeile; Rezept vorhanden aber `requires`
  nicht erfüllt → optionales `failText` (Hinweis), sonst generische Zeile.
- **Demo**: ein minimales Showcase-Rezept (`matches + torch → lit_torch`) plus die
  wenigen dafür nötigen Items, in bestehende Räume gestellt.

## 2. Scope

**In Scope:**
- `UseCommand`-Routing: 0 Args → "Use what?"; 1 Arg → bestehendes Einzel-`use`;
  ≥2 Args → Kombination der ersten beiden Operanden.
- `Combination`-Datenmodell + optionale `combinations.yaml` (geladen wie
  quests/endings über `readListOptional`).
- `CombinationDto` + Factory + `World.combinations` (Map mit kanonischem Paar-Key).
- `Combinations`-Engine (`game`) — Auflösung, Lookup, requires/consume/produce/
  effects/response/failText.
- `WorldValidator`-Regeln: `a`/`b`/`consume`/`produce` referenzieren existierende
  Item-Ids; keine doppelten Paare.
- Minimales Demo-Rezept + Items.
- Tests: Engine, UseCommand-Routing, Loader, Validator.

**Out of Scope:**
- Parser-Änderung — `on`/`with`/`to` sind **bereits** Filler (s. §3); keine neue
  Grammatik nötig.
- Mehrteilige (>2) Rezepte / Kombination aus 3+ Items.
- Mehrwort-Item-Namen-Auflösung (Operanden lösen per Item-Id auf, wie heute).
- Größerer Content-/Rätsel-Ausbau (eigenes Teilprojekt).

## 3. Grammatik & Parsing (keine Änderung nötig)

`CommandParser.FILLERS` enthält bereits `to`, `with`, `on`, `at`, `the`, `a`,
`an`. Daher liefern alle drei Eingaben dieselbe Args-Liste:

```
use matches on torch    → verb=use, args=[matches, torch]
use matches with torch  → verb=use, args=[matches, torch]
use matches torch       → verb=use, args=[matches, torch]
```

`UseCommand` verzweigt nur über die Arg-Anzahl:

```java
if (args.isEmpty()) { io.write("Use what?"); return; }
if (args.size() >= 2) { Combinations.tryUse(ctx, args.get(0), args.get(1)); return; }
// 1 Arg: bestehende Einzel-use-Logik (Inventar dann Raum, item.use(ctx))
```

Bei ≥2 Args zählen die **ersten beiden** Tokens als Operandenpaar.

## 4. Datenmodell (model)

```java
public record Combination(
        String a, String b,            // Operanden-Item-Ids (ungeordnet)
        List<Condition> requires,      // optional; leer = immer erfüllt
        List<String> consume,          // Item-Ids, die entfernt werden
        String produce,                // optional; Item-Id, die ins Inventar kommt (null = keins)
        List<Effect> effects,          // optional; Flag-Mutationen
        String response,               // Erfolgstext
        String failText                // optional; Hinweis bei nicht erfüllten requires
) {
    public Combination {
        requires = requires == null ? List.of() : List.copyOf(requires);
        consume  = consume  == null ? List.of() : List.copyOf(consume);
        effects  = effects  == null ? List.of() : List.copyOf(effects);
    }
    /** Kanonischer, reihenfolge-unabhängiger Schlüssel für ein Item-Paar. */
    public static String key(String x, String y) {
        return x.compareTo(y) <= 0 ? x + "|" + y : y + "|" + x;
    }
    public String key() { return key(a, b); }
}
```

`combinations.yaml` (Demo):
```yaml
- a: matches
  b: torch
  consume: [matches]
  produce: lit_torch
  response: |
    You strike the matches; the torch catches with a low hiss and steady glow.
  # requires/effects/failText optional, hier nicht nötig
```

`World` erhält `Map<String, Combination> combinations` (Key = `Combination.key()`).
Backward-kompatible Konstruktor-Überladung wie bei quests/endings.

## 5. Kombinations-Engine (game/Combinations.java)

Statische Utility wie `Conditions`/`Effects`/`Light`:

```java
public static void tryUse(GameContext ctx, String idX, String idY) {
    Player p = ctx.getPlayer();
    // 1. Beide Operanden auflösen (Inventar zuerst, dann aktueller Raum)
    if (!present(ctx, idX)) { ctx.getIo().write(noSuch(idX)); return; }
    if (!present(ctx, idY)) { ctx.getIo().write(noSuch(idY)); return; }
    // 2. Rezept-Lookup über kanonischen Key
    Combination c = ctx.getWorld().getCombinations().get(Combination.key(idX, idY));
    if (c == null) { ctx.getIo().write("Nothing happens."); return; }
    // 3. requires prüfen
    if (!Conditions.all(c.requires(), ctx)) {
        ctx.getIo().write(c.failText() != null ? c.failText() : "Nothing happens.");
        return;
    }
    // 4. consume → produce → effects → response
    for (String id : c.consume()) { removeFromAnywhere(ctx, id); }
    if (c.produce() != null) {
        Item produced = ctx.getWorld().getItems().get(c.produce());
        p.addItem(produced);
    }
    Effects.applyAll(c.effects(), ctx);
    ctx.getIo().print(/* response als StyledText */);
}
```

Hilfsmethoden:
- `present(ctx, id)` → Inventar **oder** aktueller Raum enthält `id`.
- `removeFromAnywhere(ctx, id)` → `player.removeItem(id)`, sonst
  `currentRoom.removeItem(id)`.
- `noSuch(id)` → "There is no '<id>' here or in your inventory." (wie UseCommand).
- Erzeugtes Item ist in `items.yaml` definiert, aber in **keinem** Raum platziert
  (existiert in `world.getItems()`, „nirgends"), bis es gefertigt wird → dann ins
  Inventar. Save/Load erfasst Item-Platzierung + Switch-Zustände bereits korrekt;
  ungefertigte Items bleiben unplatziert.

## 6. Loader-Anbindung

- `CombinationDto` (Jackson-Record): `a, b, requires, consume, produce, effects,
  response, failText`. `requires`/`effects` via `ConditionDto.toModelList` /
  `EffectDto.toModelList` (vorhanden).
- `WorldLoader`: `readListOptional(basePath + "/combinations.yaml", CombinationDto.class)`.
- `CombinationFactory`: DTO → `Combination`; sammelt in `Map<String, Combination>`
  per `Combination.key()`. Doppelter Key → `WorldLoadException`.
- `World.combinations` + Getter; backward-kompatible Konstruktoren.

## 7. Validierung (WorldValidator)

- `a`, `b`, jede `consume`-Id und (falls gesetzt) `produce` müssen in der
  Item-Registry existieren → sonst `WorldLoadException` mit klarer Meldung.
- Doppelte Paar-Keys → Fehler (im Factory bereits abgefangen; Validator
  dokumentiert die Regel).
- `requires`/`effects` nutzen die bestehende Condition/Effect-Validierung, falls
  vorhanden; sonst rein strukturell.

## 8. Demo-Content (minimal)

- `items.yaml`: `matches` (plain), `torch` (plain, `light: false`), `lit_torch`
  (**plain mit `light: true`**). `Light.isActiveLight` wertet ein Nicht-Switchable
  mit `light: true` als **immer aktive** Lichtquelle (nur SwitchableItems müssen
  „on" sein) — also ist `lit_torch` eine dauerhaft brennende Lichtquelle, ohne
  Toggle. `lit_torch` wird **nicht** in einem Raum platziert (entsteht nur durchs
  Rezept).
- `rooms.yaml`: `matches` und `torch` in erreichbare Räume legen.
- `combinations.yaml`: das eine Rezept aus §4.
- Spielbar nachweisbar: `take matches`, `take torch`, `use matches on torch` →
  `lit_torch` im Inventar (Lichtquelle), `matches` verbraucht.

## 9. Tests

- **`CombinationsTest`**: ungeordneter Match (`X on Y` == `Y on X`); `requires`
  erfüllt/nicht erfüllt (failText vs. generisch); consume aus Inventar **und** aus
  Raum; produce landet im Inventar; effects gesetzt; kein Rezept → "Nothing
  happens."; fehlender Operand → noSuch-Meldung.
- **`UseCommand`-Routing**: 0 Args → "Use what?"; 1 Arg → `item.use` (bestehend);
  2 Args → Combinations-Pfad (über Fake-/TestIO + kleine Welt).
- **Loader**: `combinations.yaml` → `World.combinations` korrekt; Key-Kanonisierung;
  doppeltes Paar → Exception.
- **Validator**: unbekannte `a`/`b`/`consume`/`produce`-Id → `WorldLoadException`.
- Konvention: keine GUI-/YAML-abhängigen Domain-Tests; Engine-Tests bauen Welt
  inline wie `QuestEngineTest`.

## 10. Architektur-Werte / Risiken

- **Datengetrieben**: Rezepte in YAML, kein Hardcoding; gleiche DTO/Domain-Trennung
  wie quests/endings.
- **Geringe Kopplung**: neue `Combinations`-Utility neben `Conditions`/`Effects`;
  `UseCommand` bekommt nur eine Verzweigung. Kein Parser-Eingriff.
- **Reihenfolge-Unabhängigkeit** über kanonischen Key vermeidet doppelte Rezepte.
- **Erzeugte Items** „aus dem Nichts": müssen in `items.yaml` definiert, aber
  unplatziert sein — Validator stellt Existenz sicher; Save/Load erfasst sie nach
  dem Fertigen automatisch.
- Risiko: `produce` eines bereits irgendwo platzierten Items würde dieselbe Instanz
  ins Inventar verschieben (Items sind Singletons). Demo vermeidet das (unplatziert).
  Validator/Doku weist darauf hin.