459 lines
15 KiB
Markdown
459 lines
15 KiB
Markdown
# Win-Condition & Endings Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Priority-ordered, condition-driven endings with an end-of-game summary; the game ends when an ending fires.
|
|
|
|
**Architecture:** `Ending` is data (condition + text), loaded from optional `endings.yaml` into an ordered `World.endings`. `EndingEngine.triggered(ctx)` returns the first matching ending; `Game` checks it each turn after the quest tick, prints the ending + summary, and stops. Reuses the existing condition engine and quest log.
|
|
|
|
**Tech Stack:** Java 25, Maven, JUnit 5 + AssertJ, Lombok, Jackson/SnakeYAML.
|
|
|
|
Spec: [docs/superpowers/specs/2026-05-31-endings-design.md](../specs/2026-05-31-endings-design.md)
|
|
|
|
---
|
|
|
|
## Task 1: Ending model, DTO/factory, World.endings, loading
|
|
|
|
**Files:**
|
|
- Create: `model/Ending.java`, `loader/dto/EndingDto.java`, `loader/EndingFactory.java`
|
|
- Modify: `model/World.java`, `loader/WorldLoader.java`
|
|
- Test: `loader/EndingLoadingTest.java`
|
|
|
|
- [ ] **Step 1: Create `model/Ending.java`**
|
|
|
|
```java
|
|
package thb.jeanluc.adventure.model;
|
|
|
|
import java.util.List;
|
|
|
|
/** A game ending: shown (and ends the game) when its conditions hold. */
|
|
public record Ending(String id, String title, boolean victory, List<Condition> when, String text) {
|
|
public Ending {
|
|
when = when == null ? List.of() : List.copyOf(when);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Add `endings` to `World.java` with back-compat constructors**
|
|
|
|
Add import:
|
|
```java
|
|
import java.util.List;
|
|
```
|
|
Add the field after `quests`:
|
|
```java
|
|
/** Ordered list of endings (first matching one wins). */
|
|
private final List<Ending> endings;
|
|
```
|
|
Replace the existing back-compat constructor with two that both delegate to the full constructor:
|
|
```java
|
|
/** Backward-compatible constructor for worlds without quests or endings. */
|
|
public World(Map<String, Room> rooms, Map<String, Item> items, Map<String, Npc> npcs,
|
|
String title, String welcomeMessage) {
|
|
this(rooms, items, npcs, title, welcomeMessage, Map.of(), List.of());
|
|
}
|
|
|
|
/** Backward-compatible constructor for worlds with quests but no endings. */
|
|
public World(Map<String, Room> rooms, Map<String, Item> items, Map<String, Npc> npcs,
|
|
String title, String welcomeMessage, Map<String, Quest> quests) {
|
|
this(rooms, items, npcs, title, welcomeMessage, quests, List.of());
|
|
}
|
|
```
|
|
(The 7-arg constructor is the Lombok-generated `@RequiredArgsConstructor` over all final fields in declaration order: rooms, items, npcs, title, welcomeMessage, quests, endings.)
|
|
|
|
- [ ] **Step 3: Create `loader/dto/EndingDto.java`**
|
|
|
|
```java
|
|
package thb.jeanluc.adventure.loader.dto;
|
|
|
|
import java.util.List;
|
|
|
|
/** YAML representation of a game ending. */
|
|
public record EndingDto(String id, String title, Boolean victory, List<ConditionDto> when, String text) {
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Create `loader/EndingFactory.java`**
|
|
|
|
```java
|
|
package thb.jeanluc.adventure.loader;
|
|
|
|
import thb.jeanluc.adventure.loader.dto.ConditionDto;
|
|
import thb.jeanluc.adventure.loader.dto.EndingDto;
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
|
|
/** Builds {@link Ending} objects from {@link EndingDto}s. */
|
|
public final class EndingFactory {
|
|
|
|
private EndingFactory() {
|
|
}
|
|
|
|
public static Ending fromDto(EndingDto dto) {
|
|
return new Ending(
|
|
dto.id(),
|
|
dto.title(),
|
|
Boolean.TRUE.equals(dto.victory()),
|
|
ConditionDto.toModelList(dto.when()),
|
|
dto.text());
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Load `endings.yaml` in `WorldLoader.java`**
|
|
|
|
Add imports:
|
|
```java
|
|
import thb.jeanluc.adventure.loader.dto.EndingDto;
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
```
|
|
After the `questDtos` read, add:
|
|
```java
|
|
List<EndingDto> endingDtos = readListOptional(basePath + "/endings.yaml", EndingDto.class);
|
|
```
|
|
After the quest `requireUniqueIds`, add:
|
|
```java
|
|
requireUniqueIds("ending", endingDtos.stream().map(EndingDto::id).toList());
|
|
```
|
|
Build an **ordered** ending list (preserve YAML order) next to the quest map build:
|
|
```java
|
|
List<Ending> endings = new ArrayList<>();
|
|
for (EndingDto dto : endingDtos) {
|
|
endings.add(EndingFactory.fromDto(dto));
|
|
}
|
|
```
|
|
Add the import for `ArrayList` if missing:
|
|
```java
|
|
import java.util.ArrayList;
|
|
```
|
|
Change the `World` construction to the 7-arg form:
|
|
```java
|
|
World world = new World(rooms, items, npcs,
|
|
gameDto.title(), gameDto.welcomeMessage(), quests, endings);
|
|
```
|
|
|
|
- [ ] **Step 6: Write the loading test**
|
|
|
|
`src/test/java/thb/jeanluc/adventure/loader/EndingLoadingTest.java`:
|
|
```java
|
|
package thb.jeanluc.adventure.loader;
|
|
|
|
import org.junit.jupiter.api.Test;
|
|
import thb.jeanluc.adventure.loader.dto.ConditionDto;
|
|
import thb.jeanluc.adventure.loader.dto.EndingDto;
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
|
|
import java.util.List;
|
|
|
|
import static org.assertj.core.api.Assertions.assertThat;
|
|
|
|
class EndingLoadingTest {
|
|
@Test
|
|
void factoryMapsFields() {
|
|
Ending e = EndingFactory.fromDto(new EndingDto("victory", "Won", true,
|
|
List.of(new ConditionDto("manor_secured", null, null)), "You win."));
|
|
assertThat(e.id()).isEqualTo("victory");
|
|
assertThat(e.victory()).isTrue();
|
|
assertThat(e.when()).hasSize(1);
|
|
assertThat(e.text()).isEqualTo("You win.");
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 7: Run tests**
|
|
|
|
Run: `mvn -q test -Dtest=EndingLoadingTest`
|
|
Expected: PASS.
|
|
Run: `mvn -q test`
|
|
Expected: PASS — the real `endings.yaml` does not exist yet, so `readListOptional` returns empty; existing `new World(...)` callers compile via the back-compat constructors.
|
|
|
|
- [ ] **Step 8: Commit**
|
|
|
|
```bash
|
|
git add src/main/java/thb/jeanluc/adventure/model/Ending.java \
|
|
src/main/java/thb/jeanluc/adventure/loader/dto/EndingDto.java \
|
|
src/main/java/thb/jeanluc/adventure/loader/EndingFactory.java \
|
|
src/main/java/thb/jeanluc/adventure/model/World.java \
|
|
src/main/java/thb/jeanluc/adventure/loader/WorldLoader.java \
|
|
src/test/java/thb/jeanluc/adventure/loader/EndingLoadingTest.java
|
|
git commit -m "feat: Ending model + endings.yaml loading (ordered, optional)"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: EndingEngine + Game wiring
|
|
|
|
**Files:**
|
|
- Create: `game/EndingEngine.java`
|
|
- Modify: `game/Game.java`
|
|
- Test: `game/EndingEngineTest.java`
|
|
|
|
- [ ] **Step 1: Write failing test**
|
|
|
|
`src/test/java/thb/jeanluc/adventure/game/EndingEngineTest.java`:
|
|
```java
|
|
package thb.jeanluc.adventure.game;
|
|
|
|
import org.junit.jupiter.api.Test;
|
|
import thb.jeanluc.adventure.io.TestIO;
|
|
import thb.jeanluc.adventure.model.Condition;
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
import thb.jeanluc.adventure.model.Player;
|
|
import thb.jeanluc.adventure.model.Room;
|
|
import thb.jeanluc.adventure.model.World;
|
|
|
|
import java.util.List;
|
|
import java.util.Map;
|
|
|
|
import static org.assertj.core.api.Assertions.assertThat;
|
|
|
|
class EndingEngineTest {
|
|
private GameContext ctx(List<Ending> endings) {
|
|
Player p = new Player(new Room("k", "K", "d"), 0);
|
|
World w = new World(Map.of(), Map.of(), Map.of(), "t", "w", Map.of(), endings);
|
|
return new GameContext(w, p, new TestIO());
|
|
}
|
|
|
|
private Ending ending(String id, boolean victory, String flag) {
|
|
return new Ending(id, id + "-title", victory,
|
|
List.of(new Condition(Condition.Type.FLAG, flag)), id + " text");
|
|
}
|
|
|
|
@Test
|
|
void firstMatchingEndingWinsByOrder() {
|
|
GameContext ctx = ctx(List.of(ending("victory", true, "won"), ending("fled", false, "fled")));
|
|
ctx.getState().set("won");
|
|
ctx.getState().set("fled");
|
|
assertThat(EndingEngine.triggered(ctx).id()).isEqualTo("victory");
|
|
}
|
|
|
|
@Test
|
|
void noEndingWhenNoConditionHolds() {
|
|
GameContext ctx = ctx(List.of(ending("victory", true, "won")));
|
|
assertThat(EndingEngine.triggered(ctx)).isNull();
|
|
}
|
|
|
|
@Test
|
|
void renderIncludesTitleTextAndSummary() {
|
|
GameContext ctx = ctx(List.of(ending("victory", true, "won")));
|
|
ctx.getState().set("won");
|
|
String out = EndingEngine.render(EndingEngine.triggered(ctx), ctx, 7).plainText();
|
|
assertThat(out).contains("victory-title").contains("victory text");
|
|
assertThat(out).contains("Turns: 7").contains("Quests completed: 0 / 0");
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run to verify failure**
|
|
|
|
Run: `mvn -q test -Dtest=EndingEngineTest`
|
|
Expected: FAIL — `EndingEngine` missing.
|
|
|
|
- [ ] **Step 3: Create `game/EndingEngine.java`**
|
|
|
|
```java
|
|
package thb.jeanluc.adventure.game;
|
|
|
|
import thb.jeanluc.adventure.io.text.StyledText;
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
|
|
/** Detects the first matching ending and renders the end-of-game screen. */
|
|
public final class EndingEngine {
|
|
|
|
private EndingEngine() {
|
|
}
|
|
|
|
/** First ending whose conditions hold, in list order; null if none. */
|
|
public static Ending triggered(GameContext ctx) {
|
|
for (Ending e : ctx.getWorld().getEndings()) {
|
|
if (Conditions.all(e.when(), ctx)) {
|
|
return e;
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** Builds the ending screen: title banner, text, and a run summary. */
|
|
public static StyledText render(Ending e, GameContext ctx, int turns) {
|
|
int total = ctx.getWorld().getQuests().size();
|
|
int done = ctx.getQuestLog().completed().size();
|
|
String bar = "═".repeat(Math.max(12, e.title().length() + 6));
|
|
|
|
StyledText.Builder b = StyledText.builder();
|
|
b.heading(bar + "\n").heading(" " + e.title() + "\n").heading(bar + "\n");
|
|
b.plain(e.text().stripTrailing()).plain("\n\n");
|
|
b.dim("Turns: " + turns + "\n");
|
|
b.dim("Quests completed: " + done + " / " + total + "\n");
|
|
b.heading("Rank: " + rank(e, total, done));
|
|
return b.build();
|
|
}
|
|
|
|
private static String rank(Ending e, int total, int done) {
|
|
if (e.victory() && total > 0 && done == total) {
|
|
return "Master of the Manor";
|
|
}
|
|
if (e.victory()) {
|
|
return "Manor Reclaimed";
|
|
}
|
|
return "Escaped — the manor keeps its secrets";
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Wire endings into `Game.java`**
|
|
|
|
In `Game.java` add a `maybeEnd()` method and call it after each `publishHud()`. Add the import:
|
|
```java
|
|
import thb.jeanluc.adventure.model.Ending;
|
|
```
|
|
(`EndingEngine` is in the same `game` package — no import.) Update `run()` so it calls `maybeEnd()` after the initial publish and after the per-iteration publish:
|
|
```java
|
|
public void run() {
|
|
publishHud();
|
|
maybeEnd();
|
|
while (running) {
|
|
String input = ctx.getIo().readLine();
|
|
if (input == null) {
|
|
break;
|
|
}
|
|
ParsedCommand parsed = parser.parse(input);
|
|
if (parsed.verb().isEmpty()) {
|
|
continue;
|
|
}
|
|
Optional<Command> cmd = registry.find(parsed.verb());
|
|
if (cmd.isEmpty()) {
|
|
ctx.getIo().write("I don't understand '" + parsed.verb() + "'. Type 'help'.");
|
|
} else {
|
|
cmd.get().execute(ctx, parsed.args());
|
|
turn++;
|
|
}
|
|
publishHud();
|
|
maybeEnd();
|
|
}
|
|
}
|
|
|
|
private void maybeEnd() {
|
|
Ending e = EndingEngine.triggered(ctx);
|
|
if (e != null) {
|
|
ctx.getIo().print(EndingEngine.render(e, ctx, turn));
|
|
stop();
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 5: Run tests**
|
|
|
|
Run: `mvn -q test -Dtest=EndingEngineTest`
|
|
Expected: PASS.
|
|
Run: `mvn -q test`
|
|
Expected: PASS — `GameTest`'s worlds have no endings (empty list), so `maybeEnd()` is a no-op there.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/main/java/thb/jeanluc/adventure/game/EndingEngine.java \
|
|
src/main/java/thb/jeanluc/adventure/game/Game.java \
|
|
src/test/java/thb/jeanluc/adventure/game/EndingEngineTest.java
|
|
git commit -m "feat(game): EndingEngine + per-turn end check with summary"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: Demo endings + flee door + docs + verification
|
|
|
|
**Files:**
|
|
- Create: `src/main/resources/world/endings.yaml`
|
|
- Modify: `src/main/resources/world/items.yaml`, `rooms.yaml`, `docs/enhancement-ideas.md`
|
|
|
|
- [ ] **Step 1: Create `src/main/resources/world/endings.yaml`**
|
|
|
|
```yaml
|
|
- id: victory
|
|
title: "The Manor Reclaimed"
|
|
victory: true
|
|
when: [{ flag: manor_secured }]
|
|
text: |
|
|
The lights hold steady and the whispers fade to nothing. Whatever held
|
|
this place has loosened its grip. The manor is yours now.
|
|
- id: fled
|
|
title: "Into the Night"
|
|
victory: false
|
|
when: [{ flag: fled }]
|
|
text: |
|
|
You wrench the front door open and bolt into the dark. Safe — but the
|
|
manor keeps its secrets, and they will keep you awake for years.
|
|
```
|
|
|
|
- [ ] **Step 2: Add a "front door" switch to `items.yaml`**
|
|
|
|
Append:
|
|
```yaml
|
|
- id: front_door
|
|
type: switchable
|
|
name: Front Door
|
|
description: The heavy front door. It would let you leave the manor for good.
|
|
state: false
|
|
onText: |
|
|
You haul the front door open and step out into the cold night.
|
|
offText: |
|
|
You ease the door shut again.
|
|
effects:
|
|
- { setFlag: fled }
|
|
```
|
|
|
|
- [ ] **Step 3: Place the door in the kitchen (`rooms.yaml`)**
|
|
|
|
Change the kitchen's items line from:
|
|
```yaml
|
|
items: [letter, lamp]
|
|
```
|
|
to:
|
|
```yaml
|
|
items: [letter, lamp, front_door]
|
|
```
|
|
|
|
- [ ] **Step 4: Mark 3.3 done in `docs/enhancement-ideas.md`**
|
|
|
|
Under the `### 5. Quest-System (NPC-Ausbau)` status block, append:
|
|
```markdown
|
|
> ✅ #3.3 umgesetzt (Branch `feature/endings`): priorisierte, condition-driven
|
|
> Enden (`endings.yaml`) + End-Screen mit Summary (Züge, Quests X/Y, Rang).
|
|
> Demo: Sieg-Ende (`manor_secured`) und Flucht-Ende (Front Door → `fled`).
|
|
> Damit ist das Quest-System (#3) komplett.
|
|
```
|
|
|
|
- [ ] **Step 5: Full suite + end-to-end console**
|
|
|
|
Run: `mvn -q test`
|
|
Expected: PASS.
|
|
|
|
Victory path:
|
|
```bash
|
|
printf 'go south\nuse generator\ngo north\ntake lamp\ngive lamp old_man\n' | mvn -q -DskipTests exec:java@run
|
|
```
|
|
Expected: completing the `restore_power` quest sets `manor_secured`; on the next turn the game prints the **"The Manor Reclaimed"** ending banner, the summary (`Turns: …`, `Quests completed: 1 / 1`, `Rank: Master of the Manor`), and exits — no `quit` needed.
|
|
|
|
Flee path:
|
|
```bash
|
|
printf 'use front_door\n' | mvn -q -DskipTests exec:java@run
|
|
```
|
|
Expected: the **"Into the Night"** ending + summary (`Rank: Escaped …`), then exit.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/main/resources/world/endings.yaml \
|
|
src/main/resources/world/items.yaml \
|
|
src/main/resources/world/rooms.yaml \
|
|
docs/enhancement-ideas.md
|
|
git commit -m "feat(content): victory & flee endings; front-door flee switch"
|
|
```
|
|
|
|
---
|
|
|
|
## Self-Review notes
|
|
|
|
- **Spec coverage:** model+loader (T1), engine+Game wiring+summary (T2), demo+docs (T3). Scoreboards/turn-conditions deferred.
|
|
- **Backward compatibility:** `World` gains 5- and 6-arg back-compat constructors delegating to the 7-arg; existing `new World(...)` callers (tests, prior loader pattern) compile unchanged. `endings.yaml` optional. `GameTest` worlds have empty endings → `maybeEnd()` no-op.
|
|
- **Type consistency:** `EndingEngine.triggered(ctx)`/`render(Ending, ctx, int)`, `Ending.when/victory/title/text`, `World.getEndings`, `EndingFactory.fromDto`, `EndingDto` used consistently.
|
|
- **Layering:** `Ending` (model) carries no `game` dependency; `EndingEngine` (game) depends on model + io.text.
|