# Implementation Plan — Steps 4 through 8

Cross-references: `architecture.md` (design), `requirements.md` (REQ-* citations).

## Status

| Step | Scope | State |
|------|-------|-------|
| 1 | Config loading (Formula, ConfigLoader, all config structs) | ✅ done |
| 2 | Simulation shell + TickDriver + entity id allocator + event queues | ✅ done |
| 3 | Belt subsystem (placement, port interface, per-tile v1, splitter routing, clearTiles, visual iteration) | ✅ done |
| 4 | Buildings + placement + belt↔building transport | ✅ done |
| 5 | Scrap + ships skeleton (data + spawning, no AI) | ⬜ next |
| 6 | Ship behavior systems + movement arbitration | ⬜ |
| 7 | Waves, threat accumulation, combat resolution, deaths & loot | ⬜ |
| 8 | UI layer (GameWorldView, visuals.toml, panels, build/demolish, speed controls) | ⬜ |

Tick order reference (architecture.md §Tick Order):
1. Wave scheduler — step 7
2. Threat accumulation — step 7
3. Belt→building pull — step 4
4. Building production — step 4
5. Building→belt push — step 4
6. Belt tick — step 3 ✅
7. Ship behavior systems — step 6
8. Combat resolution — step 7
9. Deaths & loot — step 7
10. `tickMovement` — step 6
11. Scrap despawn — step 5

Each new subsystem slots into `Simulation::tick()` in this exact order.

---

## Step 4 — Buildings + placement + belt↔building transport

Covers REQ-BLD-*, REQ-MAT-*. Introduces the first stateful gameplay loop: miners pull nothing, produce ore, push onto belts; smelters pull ore, produce ingots; etc.

### New types (`src/lib/sim/`)

```cpp
struct InputBuffer {
    std::map<ItemType, int> counts;
    std::map<ItemType, int> caps;       // per-material; = 2× per-cycle requirement
};

struct OutputBuffer {
    std::vector<Item> items;
    int capacity;                        // 2× per-cycle output; 1× for ReprocessingPlant
};

struct Production {
    std::string recipeId;
    Tick completesAt;
    std::vector<Item> chosenOutputs;     // resolved at cycle start for reprocessing
};

struct Building {
    EntityId id;
    QPoint tile;                         // origin of footprint (top-left)
    QSize footprint;
    Rotation rotation;
    BuildingType type;
    float hp;
    float maxHp;
    std::string recipeId;                // current recipe; empty = none selected
    InputBuffer inputBuffer;
    OutputBuffer outputBuffer;
    std::optional<Production> production;
};
```

### Surface-mask parsing (new utility in `src/lib/config/`)

```cpp
struct ParsedSurfaceMask {
    QSize footprint;
    std::vector<QPoint> bodyCells;      // relative to tile origin
    std::vector<Port> outputPorts;      // tile = adjacent cell OUTSIDE footprint
                                        // direction = away from building
    std::vector<QPoint> shipDockCells;  // 'S' cells — for salvage bay / shipyard
};

ParsedSurfaceMask parseSurfaceMask(const std::vector<std::string>& rows,
                                   Rotation rotation);
```

Conventions (inferred from `buildings.toml`):
- `A` = body cell
- `S` = ship dock cell (part of footprint; shipyard/salvage bay)
- `>`, `<`, `^`, `v` = direction marker on cell ADJACENT to body, NOT part of footprint
- space = empty within bounding box
- Rotation transforms the grid 90°/180°/270° around the mask origin

### Placement + BuildingSystem

Either a new `BuildingSystem` class in `src/lib/sim/` or methods on `Simulation`. Recommended: a `BuildingSystem` owned by `Simulation`, mirroring `BeltSystem`'s pattern.

```cpp
class BuildingSystem {
public:
    BuildingSystem(const GameConfig& config, BeltSystem& belts,
                   std::function<EntityId()> allocateId,
                   std::mt19937& rng);

    // Placement (called by UI commands in Step 8)
    EntityId place(BuildingType type, QPoint tile, Rotation rotation);
    void     demolish(EntityId id);
    void     setRecipe(EntityId id, const std::string& recipeId);

    // Tick hooks — called from Simulation::tick() in the correct order
    void tickBeltPull();     // step 3
    void tickProduction();   // step 4
    void tickBeltPush();     // step 5

    // Queries (for UI)
    const Building* find(EntityId id) const;
    std::vector<Building> all() const;   // for rendering
};
```

Belts and splitters are registered with `BeltSystem` directly from `BuildingSystem::place` when type == Belt or Splitter — these don't get `Building` instances (architecture.md §Buildings).

### Production cycle (REQ-MAT-CYCLE)

In `tickProduction`:
```
for each building with recipeId set:
    if building has active production:
        if currentTick >= production.completesAt:
            deposit chosenOutputs into outputBuffer
            clear production
        continue

    // idle: try to start a new cycle
    recipe = config.findRecipe(recipeId)
    if inputs available in buffers AND outputs fit in outputBuffer:
        consume inputs
        if reprocessing: roll chosenOutputs via discrete_distribution on probabilities
        else: chosenOutputs = recipe.outputs (expanded by amounts)
        // re-check fit for reprocessing (chosen output must fit)
        production = {recipeId, currentTick + secondsToTicks(recipe.durationSeconds), chosenOutputs}
```

Reprocessing uses `Simulation`'s `std::mt19937` + `std::discrete_distribution<>`. Do NOT use the legacy `WeightedRandomGenerator` (uses `auto` and float precision).

### Belt↔building interaction

`tickBeltPull` (step 3): for each building with `recipeId`, walk its footprint's edges; for each adjacent tile, construct `Port{adjTile, directionFromBeltToBuilding}` and call `belts.tryTakeItem(port)`. Accept if the item matches a required input AND the per-material buffer has space.

`tickBeltPush` (step 5): for each output port on each building with items in outputBuffer, call `belts.tryPutItem(port, item)`. On success, remove from buffer.

### Files

**New:**
- `src/lib/sim/Building.h`
- `src/lib/sim/BuildingSystem.h` / `.cpp`
- `src/lib/config/SurfaceMask.h` / `.cpp`
- `src/test/BuildingTest.cpp`
- `src/test/SurfaceMaskTest.cpp`

**Modified:**
- `src/lib/sim/Simulation.h` / `.cpp` — own `BeltSystem` + `BuildingSystem`; call their tick hooks in order
- `src/lib/sim/CMakeLists.txt`
- `src/lib/config/CMakeLists.txt`
- `src/test/CMakeLists.txt`

### Tests

- **Surface mask:** all four rotations of miner, smelter, splitter; output ports land on correct adjacent cells
- **Placement:** place miner, verify footprint occupies expected tiles; demolish removes it
- **Belt registration:** placing a Belt calls `BeltSystem::placeBelt`; demolishing calls `removeTile`
- **Miner cycle:** miner with `mine_iron_ore` recipe deposits iron_ore into outputBuffer after recipe duration ticks
- **Smelter cycle:** feed iron_ore into input buffer, 2 ore → 1 ingot in output after duration
- **Output buffer cap:** buffer fills to 2×, production stalls
- **Reprocessing cap:** buffer holds exactly 1× (REQ-MAT-OUTPUT-BUFFER-REPROCESSING)
- **Reprocessing RNG:** seed-deterministic weighted output pick; N trials match expected distribution within tolerance
- **Belt pull:** belt adjacent to smelter input edge delivers ore; smelter input buffer increments
- **Belt push:** miner outputBuffer drains onto adjacent belt each tick when space available
- **Recipe change:** `setRecipe` clears input + output buffers (REQ-MAT-INPUT-BUFFER, REQ-MAT-OUTPUT-BUFFER)

---

## Step 5 — Scrap + ships skeleton

Data structures + spawning only. No AI yet. Covers REQ-RES-SCRAP-DROP, REQ-SHP-STATS, REQ-BLD-SHIPYARD scaffolding.

### New types

```cpp
struct Scrap {
    EntityId id;
    QVector2D position;         // tile units; ship-center convention
    int amount;
    Tick despawnAt;
};

struct Weapon       { float damage; float range; float fireRateHz;
                      float cooldownTicks; std::optional<EntityId> currentTarget; };
struct SalvageCargo { int capacity; int current; };
struct RepairTool   { float ratePerTick; std::optional<EntityId> currentTarget; };

struct ThreatResponse { float engagementRange; /* CombatStance, CombatTargetPriority */
                        std::optional<EntityId> currentTarget; };
struct ScrapCollector { std::optional<QVector2D> scrapTarget; EntityId deliveryBay; };
struct RepairBehavior { /* RepairTargetPriority */ std::optional<EntityId> currentTarget; };
struct HomeReturn     { float retreatHpFraction; QVector2D homePos; };

struct Ship {
    EntityId id;
    QVector2D position;
    QVector2D velocity;
    float hp;
    float maxHp;
    int level;
    std::string blueprintId;    // matches ShipDef::id

    std::optional<Weapon>       weapon;
    std::optional<SalvageCargo> cargo;
    std::optional<RepairTool>   repairTool;
    std::optional<ThreatResponse> threatResponse;
    std::optional<ScrapCollector> scrapCollector;
    std::optional<RepairBehavior> repairBehavior;
    std::optional<HomeReturn>     homeReturn;

    MovementIntent intent;
};
```

### `ShipSystem` / `ScrapSystem`

Small classes owned by `Simulation`:
- `ShipSystem::spawn(ShipDef, level, QVector2D position)` — builds a Ship from the config by evaluating per-role formulas at `level`; components present iff corresponding `ShipDef` sections are present
- `ShipSystem::forEach(…)` — for Step 6 behavior systems to iterate
- `ScrapSystem::spawn(QVector2D position, int amount)` — tick step 9 caller
- `ScrapSystem::tickDespawn()` — step 11

Still no AI tick hooks; `Simulation::tick()` gains step 11 only.

### Tests

- **Ship spawn:** combat ship has Weapon + ThreatResponse; salvage ship has SalvageCargo + ScrapCollector; stats evaluated from formulas at given level
- **Component absence:** salvage ship has no Weapon; combat ship has no SalvageCargo
- **Scrap spawn + despawn:** scrap created with `despawnAt = currentTick + secondsToTicks(world.scrapDespawnSeconds)`; after that many ticks `tickDespawn` removes it
- **Entity ids:** spawned ships/scrap receive strictly increasing ids from `Simulation::allocateId` (needs to be exposed to `ShipSystem`/`ScrapSystem` via constructor callback)

### Files

New: `Scrap.h`, `Ship.h`, `ShipSystem.h/.cpp`, `ScrapSystem.h/.cpp`, `ShipTest.cpp`, `ScrapTest.cpp`.
Modified: `Simulation.*`, `src/lib/sim/CMakeLists.txt`, `src/test/CMakeLists.txt`.

---

## Step 6 — Ship behavior systems + movement arbitration

All four behaviors + `tickMovement`, one at a time with focused tests. Movement intent priority (architecture.md §Movement Arbitration):

```
HomeReturn > ThreatResponse > RepairBehavior > ScrapCollector
priorities: 4          3                 2              1
```

Behaviors write `MovementIntent{priority, target}` on the ship; higher priority overwrites lower. `MovementIntent` is cleared at the start of the ship behavior step.

### Sub-steps (independent commits recommended)

**6a. `tickHomeReturn`** — if `hp/maxHp < retreatHpFraction`, write intent toward `homePos` with priority 4.

**6b. `tickThreatResponse`** — acquire enemy target within `engagementRange` if none; hold existing target if still valid. If target in weapon range, fire (emit FireEvent, apply damage to target's hp, start cooldown — stays in Step 7 combat resolution if we want to centralize damage; for modularity, fire here). Else write intent toward target, priority 3.

**6c. `tickRepairBehavior`** — find damaged friendly target; move toward if out of repair range, repair if in range. Priority 2.

**6d. `tickScrapCollector`** — if cargo full, intent = `deliveryBay.tile`; else find nearest scrap, intent = scrap.position. On arrival, consume scrap (calls into `ScrapSystem`), increment cargo. Priority 1.

**6e. `tickMovement`** — for each ship with an intent, advance position toward `intent.target` by `speedPerTick` (from ShipDef speed formula). No pathfinding v1 — straight line.

### Design decision: combat resolution split

Two options for where fire/damage happens:
- (A) Inside `tickThreatResponse` — simpler, atomic
- (B) In a separate `tickCombatResolution` step 8 — matches architecture.md exactly

Recommend (B) for fidelity to architecture.md. `tickThreatResponse` only sets target + writes movement intent. Step 7 runs combat resolution across ships + stations uniformly.

### Tests

- Intent priority: ship with low hp + weapon + enemy in range routes to homePos, not enemy
- Target acquisition: closest enemy within engagementRange; unchanged while still valid
- Repair ship finds damaged ally, moves in, repairs
- Salvage ship picks up scrap, returns when cargo full, cargo empties at delivery bay
- Movement: ship travels exactly `speed × secondsToTicks(duration)` tiles over N ticks

---

## Step 7 — Waves + threat + combat + deaths & loot

Fills tick steps 1, 2, 8, 9. Covers REQ-WAV-*, REQ-SHP-FIRING-*, REQ-DEF-*, REQ-PSH-*, REQ-RES-SCRAP-DROP.

### Tick step 1 — Wave scheduler

```
- advance m_waveTimer by 1 tick
- if between waves: at wave trigger (random gap within world.waves.gap_min/max_seconds),
  compute wave composition by drawing ship picks up to threat budget
  (REQ-WAV-TRIGGER, REQ-WAV-THREAT-COST) using world.waves.threat_rate_formula
- schedule spawn times across spawn_duration_seconds
- spawn any enemy ships whose scheduled tick has arrived
```

Ships eligible for waves: those with `threat.costFormula(elapsedSeconds) > 0`.

### Tick step 2 — Threat accumulation

`m_threatLevel += max(0.0, world.waves.threatRateFormula.evaluate(elapsedSeconds)) × kTickDurationSeconds`.

### Tick step 8 — Combat resolution

Unified across ships + defence stations (player + enemy). Each shooter has {damage, range, fireRateHz, cooldown, currentTarget}. If target in range and cooldown ≤ 0:
- apply damage to target's hp
- emit `FireEvent{shooter.id, target.id, currentTick}` into `Simulation::m_fireEvents`
- set cooldown = `kTickRateHz / fireRateHz`

Stations fire per REQ-DEF-PLAYER-FIRE and REQ-PSH-STATION-FIRE; stats from config formulas at their level / generation.

### Tick step 9 — Deaths & loot

- For each entity with hp ≤ 0: drop scrap at position (REQ-RES-SCRAP-DROP); amount from ShipDef.loot.scrapDrop or station scrap formula
- Track enemy defence station "sets": if a full set destroyed this tick, award player one blueprint (REQ-DEF-BLUEPRINT-DROP); emit `BlueprintDropEvent`
- Remove dead entities (ships, scrap, buildings)

### Push mechanic (REQ-PSH-*)

When enemy wave progresses beyond contest zone: `world.push` expansion triggers, enemy defence station set spawns at new front, scaling_factor applied to formulas. This may belong in a dedicated `PushSystem` or fold into the wave scheduler. Decide at implementation time.

### Files

New: `WaveSystem.h/.cpp`, `CombatSystem.h/.cpp`, maybe `PushSystem.h/.cpp`, corresponding `*Test.cpp`.
Modified: `Simulation.*` to wire in tick steps 1, 2, 8, 9; `ShipSystem` to expose iteration; `BuildingSystem` to expose defence stations for combat.

### Tests

- Threat accumulates per second from the formula
- Wave spawn count matches threat budget / ship cost
- Fire event emitted + drainable + cleared
- Shooter on cooldown does not fire
- Ship at hp ≤ 0 drops scrap; scrap amount matches ShipDef
- Full enemy station set destroyed → BlueprintDropEvent with correct newLevel / wasNewUnlock
- Damage to HQ decrements HQ hp — game-over condition emitted when hp ≤ 0 (if we model it that way)

---

## Step 8 — UI layer

Big step. Break into sub-phases to keep each commit reviewable.

### 8a. Visuals config + window scaffolding

- New `visuals.toml` (REQ-UI, architecture.md §Rendering → Visual Parameters) — per-type fill/outline/glyph entries
- `src/ui/VisualsConfig.h/.cpp`, `src/ui/VisualsLoader.h/.cpp` — fail-fast on missing entries for any known sim id
- Main window widget: header bar + central game view + right-hand selected-building panel (QDockWidget or split layout)
- Wire `QApplication` + `Simulation + TickDriver` into `main.cpp` replacing the current stub
- Sim + UI share one thread; paintEvent reads sim state directly (no locks — architecture.md §Threading)

### 8b. GameWorldView (render only, no input)

- `QOpenGLWidget` subclass with `QPainter` drawing
- `QTimer` @ 60 Hz → `update()` + advances sim via `TickDriver::advance(elapsedMs, gameSpeedMultiplier)` → calls `sim.tick()` N times
- Layer order per architecture.md §Layer Order (tiles → buildings → belt items → scrap → ships → beams → overlays → screen-space)
- Scroll via `scrollXTiles` float, A/D keyboard input, clamped per REQ-GW-SCROLL-LIMIT
- Mouse→world conversion: `worldX = mouseX / 20 + scrollXTiles`
- Beam renderer: keeps `FireEvent`s for 0.3 s wall time (9 ticks @ 30 Hz), drops if either end entity is gone
- Blueprint toasts: keeps `BlueprintDropEvent`s for configured toast duration

### 8c. Input → sim commands

- Tile click: select building / select belt tiles (box drag)
- Builder mode: open from build button grid; shows ghost on cursor; click places construction site (REQ-BLD-PLACE); drag-to-place for belts (REQ-BLD-DRAG)
- Demolish mode: click building → demolish (confirm), returns refund (REQ-BLD-DEMOLISH)
- Selected-building panel: recipe picker, clear-belt button (REQ-UI-BELT-CLEAR), splitter filter config, demolish button
- Speed controls: 0 / 0.5× / 1× / 2× / 4× (REQ-UI-SPEED) — bound to spacebar pause + number keys

### 8d. Header bar + polish

- Resource counters (building blocks, blueprint collection)
- Threat meter
- Wave countdown
- FPS / speed indicator
- Minor polish: hover highlights, keyboard shortcuts, tooltip on build buttons

### Files

New: `src/ui/` populated — `MainWindow.*`, `GameWorldView.*`, `HeaderBar.*`, `BuildButtonGrid.*`, `SelectedBuildingPanel.*`, `VisualsConfig.*`, `VisualsLoader.*`, `Toast.*`, etc.
Modified: `src/ui/CMakeLists.txt` — flip from INTERFACE library to regular static library; enable AUTOMOC; add `Q_OBJECT` macros where needed. `src/app/main.cpp` — construct sim + main window.

### Tests

UI code is largely visual; prioritize:
- Visuals loader fail-fast on missing entries
- Simulation + TickDriver integration test: at 1×, 60 render frames produce ~30 sim ticks (approximately — tolerate ±1 for accumulator residue)
- Manual smoke test checklist (in-repo markdown) for builder mode, demolish, recipe change, clear belt, speed toggling

---

## Things to revisit as needed

- **Pathfinding for ships:** straight-line in v1 is fine given open space; only revisit if enemy defence stations create obstacles
- **Belt segment compression (v2):** only if v1 per-tile profiling is bad
- **Worker thread for sim:** only if paint stalls become visible; `drain*` APIs already support it
- **ECS migration for ships:** only if component iteration becomes a bottleneck
- **Belt curves rendering:** derive from consecutive belt tile directions; sim logic is unaffected