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
• 57 tests passing: unit, solvability, full-level (Levels 1-3)

Key findings from Phase 1

• Transfer direction bug fixed: receiver priority in piece-to-piece transfers now prefers pieces farther from production (pushes cargo forward, not backward).
• GDD stock corrections: Level 2 needs 6R+1B (GDD had 4R+1B), Level 3 simplified to single cargo type with 6R+1K (GDD had 4R+1B+2K for dual-cargo, which is infeasible).
• Cross-route contamination: TransferResolver has no cargo-type filtering — adjacent pieces from different routes transfer cargo regardless of type. On a 6x6 board, two diagonal routes cannot avoid cross-adjacency. Dual-cargo levels require engine support.

Phase 2: Cargo-type aware transfers

Goal: Enable multi-route, multi-cargo-type levels on small boards.

• Add optional cargo-type filter to pieces (or routes), so a piece configured for Wood ignores adjacent Stone and vice-versa.
• Alternative: transfer resolver checks if cargo type matches the demand reachable from the receiver's relay chain (more complex, automatic).
• Simplest approach: production only gives to pieces whose relay chain leads toward a compatible demand. Requires route/chain tracking.
• Test: reintroduce Level 3 dual-cargo variant (Wood + Stone crossing 6x6 board with L-shaped wall).

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.