Add game framework tests and planning docs
This commit is contained in:
@@ -0,0 +1,382 @@
|
||||
# UI Move List and Playback Mode Plan
|
||||
|
||||
## Goal
|
||||
|
||||
Add UI support for:
|
||||
|
||||
- A fixed-size move list panel on the left side of the board.
|
||||
- Two move columns: White move and Black move, with turn number on the left.
|
||||
- Standard PGN/SAN notation display.
|
||||
- Scroll support when the move list is longer than the visible panel.
|
||||
- A move-list button that copies the current game as PGN to the clipboard.
|
||||
- A playback-only vertical analysis bar between the board and move list.
|
||||
- A board-orientation control that can render from White's perspective or Black's perspective.
|
||||
- A new playback mode where pieces cannot be moved, and the user can step through a loaded game.
|
||||
- In edit mode, a UI control to choose whose move is next.
|
||||
- Mode-specific paste behavior:
|
||||
- Edit mode: `Ctrl+V` pastes FEN.
|
||||
- Playback mode: `Ctrl+V` pastes PGN.
|
||||
- Play mode: no FEN/PGN paste.
|
||||
|
||||
## Collaboration rule
|
||||
|
||||
The assistant should manage only UI/application-side changes for this feature.
|
||||
|
||||
Do **not** edit files under `src/chess/` unless explicitly requested.
|
||||
|
||||
When UI work needs chess-layer functionality, stop and describe the required chess API/data shape so the project owner can implement it.
|
||||
|
||||
## Current state
|
||||
|
||||
- `BoardState` owns the current chess position.
|
||||
- `src/chess/game.zig` has a basic `Game` framework with:
|
||||
- `initial_state`
|
||||
- `state`
|
||||
- `moves`
|
||||
- `time_control`
|
||||
- `clocks`
|
||||
- `status`
|
||||
- UI currently uses `current_state` directly in `src/main.zig`.
|
||||
- Existing modes are:
|
||||
- `play`
|
||||
- `edit`
|
||||
- Existing paste behavior parses clipboard as FEN regardless of mode.
|
||||
- FEN copy is available via `Ctrl+C`.
|
||||
- Desired copy behavior: `Ctrl+C` should continue to copy FEN in every mode. PGN copy should use an explicit move-list button, not replace `Ctrl+C`.
|
||||
|
||||
## Desired architecture
|
||||
|
||||
Eventually, UI should treat `Game` as the game/session model:
|
||||
|
||||
```text
|
||||
UI/App
|
||||
├── current mode: play | edit | playback
|
||||
├── active Game
|
||||
├── playback cursor / ply index
|
||||
├── move list scroll offset
|
||||
├── board orientation: white perspective | black perspective
|
||||
├── analysis display state for playback mode
|
||||
└── rendering state
|
||||
```
|
||||
|
||||
The chess layer should provide enough data for the UI to display moves and reconstruct positions, but the UI should not implement chess notation rules itself.
|
||||
|
||||
## Stage 0: Board orientation and edit-side-to-move controls
|
||||
|
||||
### UI work
|
||||
|
||||
- Add app/UI state for board orientation:
|
||||
|
||||
```text
|
||||
white perspective: current rendering
|
||||
black perspective: visually flipped board, with White pieces/ranks at the top and Black pieces/ranks at the bottom
|
||||
```
|
||||
|
||||
- This must be a purely visual transform.
|
||||
- Keep the same chess square numbering and logical coordinates:
|
||||
- `a1` is still square `0`
|
||||
- White still starts on ranks 1 and 2 logically
|
||||
- Black still starts on ranks 7 and 8 logically
|
||||
- Update all board visual mappings consistently:
|
||||
- square rendering
|
||||
- piece rendering
|
||||
- coordinate labels
|
||||
- mouse hit-testing
|
||||
- hover/selection/check/checkmate highlights
|
||||
- valid/legal move dots
|
||||
- dragging source/target display
|
||||
- promotion popup placement
|
||||
- Add a UI control to toggle orientation, probably near the mode buttons or move list panel.
|
||||
- In edit mode, add a control to choose whose move is next:
|
||||
- White to move
|
||||
- Black to move
|
||||
- Changing side-to-move in edit mode should update only the current board state's active color/turn field and then rebuild rendering.
|
||||
- In non-edit modes, the side-to-move selector should either be hidden or disabled.
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
No chess-rule changes are required for board orientation. It is visual only.
|
||||
|
||||
For edit-side-to-move, the UI needs mutable access to the current position's active color. If `BoardState.turn` remains public, no new chess API is required. If you later make it private, add a small setter such as:
|
||||
|
||||
```zig
|
||||
pub fn setTurn(self: *BoardState, color: piece.Color) void
|
||||
```
|
||||
|
||||
## Stage 1: Add playback mode UI shell
|
||||
|
||||
### UI work
|
||||
|
||||
- Add `playback` to the app/input mode enum.
|
||||
- Add a third mode button, likely labeled `VIEW` or `PGN`/`REPLAY`.
|
||||
- In playback mode:
|
||||
- ignore board clicks/drags for moving pieces
|
||||
- no palette editing
|
||||
- no legal-move highlight generation
|
||||
- Keep reset behavior available or decide whether reset resets the active game/playback.
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
None.
|
||||
|
||||
## Stage 2: Make paste mode-specific
|
||||
|
||||
### UI work
|
||||
|
||||
Change clipboard paste behavior:
|
||||
|
||||
- If mode is `.edit`:
|
||||
- parse clipboard as FEN
|
||||
- replace current board state/game position
|
||||
- If mode is `.playback`:
|
||||
- send clipboard text to a future PGN import function
|
||||
- for now, log that PGN paste is not yet implemented if chess API is missing
|
||||
- If mode is `.play`:
|
||||
- ignore paste or log debug message
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
Eventually needed:
|
||||
|
||||
```zig
|
||||
pub fn loadPgn(allocator: std.mem.Allocator, pgn_text: []const u8) !Game
|
||||
```
|
||||
|
||||
or equivalent parse API.
|
||||
|
||||
For stage 2, this can be stubbed from the UI side with no chess changes.
|
||||
|
||||
## Stage 3: Move list panel with placeholder/static data
|
||||
|
||||
### UI work
|
||||
|
||||
- Define a fixed rectangle left of the board.
|
||||
- Render panel background and border.
|
||||
- Render column headers, for example:
|
||||
|
||||
```text
|
||||
# White Black
|
||||
```
|
||||
|
||||
- Add a visible PGN copy button inside or attached to the move list panel.
|
||||
- Clicking it should copy the current game PGN to the clipboard once chess-layer PGN export exists.
|
||||
- Until PGN export exists, the button can be visually present but log that export is not implemented.
|
||||
- Render rows using temporary/static strings or currently available move placeholders.
|
||||
- Establish layout constants:
|
||||
- panel left/right/top/bottom
|
||||
- row height
|
||||
- turn-number column x
|
||||
- white column x
|
||||
- black column x
|
||||
- max visible rows
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
None for placeholder rendering.
|
||||
|
||||
## Stage 4: Record/display move notation from played games
|
||||
|
||||
### UI work
|
||||
|
||||
- Replace direct `current_state.move(...)` calls with `game.makeMove(...)` once `Game` is wired into `main.zig`.
|
||||
- Read `game.moves` and draw move rows.
|
||||
- Update the move list after every played move.
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
The `Game` move history should expose display notation for each ply.
|
||||
|
||||
Suggested shape:
|
||||
|
||||
```zig
|
||||
pub const MoveRecord = struct {
|
||||
from: bitboard.Square,
|
||||
to: bitboard.Square,
|
||||
promotion: ?piece.PieceType,
|
||||
san: []const u8, // or fixed buffer / owned slice
|
||||
time_remaining: u32,
|
||||
};
|
||||
```
|
||||
|
||||
If avoiding heap allocation in each move record, possible alternatives:
|
||||
|
||||
```zig
|
||||
san: [16]u8,
|
||||
san_len: u8,
|
||||
```
|
||||
|
||||
The chess layer should generate SAN before mutating the board, because SAN depends on the pre-move position.
|
||||
|
||||
Needed API could be:
|
||||
|
||||
```zig
|
||||
pub fn makeMove(self: *Game, allocator: std.mem.Allocator, from: Square, to: Square, promotion: ?PieceType) !void
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```zig
|
||||
pub fn formatSanMove(allocator: std.mem.Allocator, state_before: BoardState, from: Square, to: Square, promotion: ?PieceType) ![]u8
|
||||
```
|
||||
|
||||
## Stage 5: Playback analysis bar
|
||||
|
||||
### UI work
|
||||
|
||||
- Add a vertical analysis bar between the board and the move list panel.
|
||||
- The analysis bar should be visible only in playback mode.
|
||||
- The bar is divided into a White section and a Black section.
|
||||
- When analysis is equal, the White/Black divide should be centered.
|
||||
- When White is winning, the White portion grows and the divide moves toward Black's side.
|
||||
- When Black is winning, the Black portion grows and the divide moves toward White's side.
|
||||
- The bar is purely display; it should not affect board state or move legality.
|
||||
- Initial placeholder behavior can render the bar at 50/50 until analysis data exists.
|
||||
- Later, map engine evaluation scores to a display fraction.
|
||||
|
||||
Suggested visual mapping:
|
||||
|
||||
```text
|
||||
score = 0.00 pawns -> 50% White / 50% Black
|
||||
score > 0, White better -> White section larger
|
||||
score < 0, Black better -> Black section larger
|
||||
```
|
||||
|
||||
Use a bounded/nonlinear mapping so very large evaluations do not immediately consume the whole bar. For example, later UI code could map centipawns to a normalized value with a clamp or sigmoid-like curve. Exact mapping can be tuned visually.
|
||||
|
||||
### Chess/engine-layer needs
|
||||
|
||||
No chess-layer changes are needed for placeholder rendering.
|
||||
|
||||
Eventually, playback analysis needs external UCI analysis data:
|
||||
|
||||
```text
|
||||
score cp <centipawns>
|
||||
score mate <moves>
|
||||
pv <principal variation moves>
|
||||
```
|
||||
|
||||
The UI only needs a normalized analysis value or raw score from the UCI analysis client.
|
||||
|
||||
## Stage 6: Scrolling move list
|
||||
|
||||
### UI work
|
||||
|
||||
- Track `move_list_scroll_row` or similar state in `main.zig`.
|
||||
- Add mouse wheel handling when cursor is over the move panel.
|
||||
- Clamp scroll offset between `0` and `max(0, total_rows - visible_rows)`.
|
||||
- Optional later: visual scrollbar.
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
None.
|
||||
|
||||
## Stage 7: Playback cursor and stepping
|
||||
|
||||
### UI work
|
||||
|
||||
- Add `playback_ply_index` app state.
|
||||
- In playback mode:
|
||||
- Right arrow: advance one ply
|
||||
- Left arrow: go back one ply
|
||||
- Home: first position
|
||||
- End: final position
|
||||
- Render the board for the current playback ply, not necessarily the final game state.
|
||||
- Highlight or mark the current row/ply in the move list.
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
Need a way to reconstruct board state at an arbitrary ply.
|
||||
|
||||
Possible API:
|
||||
|
||||
```zig
|
||||
pub fn stateAtPly(self: *const Game, ply_index: usize) board.BoardState
|
||||
```
|
||||
|
||||
or, if allocation/errors are involved:
|
||||
|
||||
```zig
|
||||
pub fn replayToPly(self: *const Game, ply_index: usize) !board.BoardState
|
||||
```
|
||||
|
||||
This can replay from `initial_state` through the first `ply_index` moves.
|
||||
|
||||
## Stage 8: PGN paste/import and PGN copy/export
|
||||
|
||||
### UI work
|
||||
|
||||
- In playback mode, `Ctrl+V` gets clipboard text and passes it to chess PGN parser.
|
||||
- Keep `Ctrl+C` as FEN copy in every mode.
|
||||
- Add click handling for the move-list PGN copy button.
|
||||
- When the PGN copy button is clicked, copy exported PGN to the clipboard.
|
||||
- On success:
|
||||
- replace active game with parsed game
|
||||
- set mode to playback or remain playback
|
||||
- set playback cursor to final ply or start; choose behavior intentionally
|
||||
- reset move-list scroll
|
||||
- On failure:
|
||||
- log a warning
|
||||
- keep current game unchanged
|
||||
|
||||
### Chess-layer needs
|
||||
|
||||
PGN parser that returns a `Game` with move history and final state, plus PGN export for the current game.
|
||||
|
||||
Suggested API:
|
||||
|
||||
```zig
|
||||
pub fn initFromPgn(allocator: std.mem.Allocator, pgn_text: []const u8, time_control: TimeControl) !Game
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```zig
|
||||
pub fn parsePgn(allocator: std.mem.Allocator, pgn_text: []const u8) !Game
|
||||
```
|
||||
|
||||
Suggested export API:
|
||||
|
||||
```zig
|
||||
pub fn formatPgn(allocator: std.mem.Allocator, game: Game) ![]u8
|
||||
```
|
||||
|
||||
or as a method:
|
||||
|
||||
```zig
|
||||
pub fn formatPgn(self: *const Game, allocator: std.mem.Allocator) ![]u8
|
||||
```
|
||||
|
||||
Parser should understand at least:
|
||||
|
||||
- move numbers: `1.`, `1...`
|
||||
- SAN moves
|
||||
- castling: `O-O`, `O-O-O`
|
||||
- captures: `x`
|
||||
- promotion: `=Q`, `=R`, `=B`, `=N`
|
||||
- check/checkmate suffixes: `+`, `#`
|
||||
- game termination markers: `1-0`, `0-1`, `1/2-1/2`, `*`
|
||||
- comments and tags can be added later if desired
|
||||
|
||||
Reference: Steven J. Edwards, *Portable Game Notation Specification and Implementation Guide*, especially movetext/SAN sections.
|
||||
|
||||
## Stage 9: Optional polish
|
||||
|
||||
- Auto-scroll move list to latest move in play mode.
|
||||
- Click a move row in playback mode to jump to that ply.
|
||||
- Show current move highlight.
|
||||
- Add scrollbar.
|
||||
- Show numeric eval next to the analysis bar.
|
||||
- Show best line/PV next to or below the move list.
|
||||
- Add richer PGN copy/export options, such as including/excluding tag pairs.
|
||||
- Display game result in the move panel.
|
||||
- Show time remaining per move later if clocks are implemented.
|
||||
|
||||
## Immediate next action
|
||||
|
||||
Start with Stage 0, then Stage 1 and Stage 2 in UI-only files:
|
||||
|
||||
- `src/board_input.zig`
|
||||
- `src/text_render.zig`
|
||||
- `src/main.zig`
|
||||
|
||||
Do not modify `src/chess/` for these stages.
|
||||
Reference in New Issue
Block a user