Chessistics/PLAN.md

# Chessistics — Prototype Roadmap

## Phase 1: Core solvability (DONE)

- Black Box Sim pattern: commands self-apply via `DoApply()`/`AssertApplicationConditions()`
- 3 piece types: Rook (orthogonal range 2), Bishop (diagonal range 2), Knight (L-jump)
- Relay chain mechanic with shared relay points (collision-free alternating)
- Transfer system: production → pieces → demands, 4-adjacency, participation tracking
- Victory/defeat: all demands met vs deadline expired

## Phase 2: Cargo-type aware transfers (DONE)

- `CargoFilter` property on `PieceState`: optional `CargoType?` restricting accepted cargo
- Auto-assigned at placement via relay chain tracing (adjacency to production, then shared
  relay points with filtered pieces)
- `TransferResolver` enforces filter: receivers with mismatched `CargoFilter` are skipped
- Forward-direction sorting uses cargo-type-aware `MinDistanceToProduction` to avoid
  wrong sorting when multiple productions exist
- Level 3 restored to dual-cargo (Wood+Stone) with 10R+2K stock
- GDD stock corrections: Level 2 = 6R+1B, Level 3 = 10R+2K
- 60 tests passing including 2 new CargoFilter tests

## Phase 3: Surplus stock and puzzle difficulty tuning

**Goal**: Levels give more pieces than the minimum, creating genuine puzzle space.

- With forward-preferring transfers working, longer chains are viable.
- Design levels where the player has choice: multiple valid solutions with different
  efficiency scores (PiecesUsed, TurnsTaken, CellsOccupied).
- Add scoring/star system based on Metrics.
- Levels 4-6: increasing board size (8x8, 10x10), more complex wall layouts, multiple
  productions and demands.

## Phase 4: New piece — Pion (Pawn)

**Goal**: Add a one-directional piece for asymmetric relay constraints.

- Pion moves forward only (one direction, range 1).
- Cheap to place (low piece cost if scoring is added).
- Creates interesting constraints: must plan direction of cargo flow.
- Test levels specifically designed around Pion usage.

## Phase 5: Network levels and Dame (Queen)

**Goal**: Open-ended logistics puzzles with interconnected supply networks.

- Multiple productions feeding multiple demands through shared infrastructure.
- Dame piece: combines Rook + Bishop movement (range 2, all 8 directions).
- Powerful but expensive — forces cost/benefit tradeoffs.
- Larger boards (12x12+) with complex wall configurations.
- Potential for player-designed levels (level editor data format).

## Phase 6: Godot integration

**Goal**: Playable visual prototype.

- Board renderer: grid, walls, buildings, pieces.
- Drag-and-drop piece placement during Edit phase.
- Step/play/pause simulation controls.
- Event visualization: cargo movement, transfers, delivery animations.
- Victory/defeat screens with Metrics display.