wayfinderak/zig-chess
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add game framework tests and planning docs

Browse Source
This commit is contained in:
wayfinderak
2026-05-20 20:18:55 -08:00
parent 145bc948dd
commit a5476ccdd7
6 changed files with 1201 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/uci-engine-architecture-plan.md
+448
View File
@@ -0,0 +1,448 @@
# UCI Engine Architecture Plan
## Goal
Support two families of executables:
1. **GUI/UI executable**
- Renders and tracks games.
- Lets humans play/edit/replay games.
- Can let people play against bots.
- Can spawn bot/engine executables as subprocesses on demand.
- Speaks UCI to engine subprocesses.
- Can optionally use a user-selected external UCI engine, such as Stockfish, for playback analysis.
- Eventually stores games in a database.
2. **Bot/engine executables**
- No GUI.
- Implement chess engine logic.
- Speak UCI over stdin/stdout.
- Can be launched by the GUI.
- Can also run as long-lived processes connected to external services such as lichess.org through a service adapter.
## Important terminology
In UCI terminology, the **engine** is the side that implements the UCI command loop over stdin/stdout.
The GUI/app is the **UCI controller/client**:
```text
GUI/controller
├── starts engine process
├── writes UCI commands to engine stdin
├── reads UCI responses from engine stdout
└── applies bestmove to the current game
```
The engine executable is the **UCI engine/server-like process**:
```text
Engine
├── reads commands from stdin
├── maintains/searches position
├── writes info/bestmove responses to stdout
└── exits on quit
```
Avoid naming the GUI-side wrapper a "server" in code. Prefer names like:
```text
UciEngineClient
UciController
EngineProcess
```
## Desired long-term process architecture
```text
┌─────────────────────┐
│ zig-chess-gui │
│ │
│ - Vulkan UI │
│ - game tracking │
│ - human input │
│ - playback │
│ - database later │
│ - UCI client │
└──────────┬──────────┘
│ UCI stdin/stdout
▼
┌─────────────────────┐
│ zig-chess-engine-* │
│ │
│ - evaluation │
│ - search │
│ - move selection │
│ - UCI command loop │
└─────────────────────┘
```
Future external-service architecture:
```text
┌─────────────────────┐
│ lichess-adapter │
│ │
│ - lichess API │
│ - account/game I/O │
│ - UCI client │
└──────────┬──────────┘
│ UCI stdin/stdout or socket/process bridge
▼
┌─────────────────────┐
│ zig-chess-engine-* │
└─────────────────────┘
```
Key design principle:
```text
GUI ───────────────┐
├── UCI ── engine executable
Lichess adapter ───┘
```
The engine should not know whether it is being used by the GUI, a test harness, or a lichess adapter.
## Suggested source layout
Possible future layout:
```text
src/
├── chess/ // board/game/FEN/PGN/legal moves
├── main.zig // current GUI entry point, or later src/gui/main.zig
├── uci/
│ ├── protocol.zig // shared UCI parse/format types
│ ├── client.zig // GUI/service side: controls engine process
│ └── server.zig // engine side: stdin/stdout command loop
├── engine/
│ ├── engine.zig // common engine interface
│ ├── eval.zig // static evaluation
│ ├── search.zig // search algorithms
│ └── perft.zig // move-generator validation tooling
└── bots/
├── random.zig // random/legal-move bot executable
├── material.zig // material-eval bot executable
└── search.zig // stronger search bot executable
```
This layout can evolve. The important boundary is that engine executables communicate with outside controllers through UCI.
## Build targets
Eventually `build.zig` should produce multiple executables, for example:
```text
zig-chess-gui
zig-chess-random-bot
zig-chess-material-bot
zig-chess-search-bot
```
The GUI target links rendering/UI code.
The engine targets should avoid linking Vulkan/windowing code.
## Analysis engine policy
The GUI should support an optional external UCI engine for real-time analysis during game playback.
Primary intended use case:
```text
Playback mode
├── user steps through game
├── GUI sends current position to analysis engine
├── analysis engine returns eval/PV/best line
└── GUI displays analysis to the user
```
This analysis engine is separate from project bot engines:
- It is for user-facing analysis only.
- It must not be used by project bot engines as their search/evaluation implementation.
- Project bots should have their own evaluation/search logic.
- The GUI should treat the analysis engine as just another external UCI process.
### Stockfish licensing policy
Stockfish is GPL-3.0 licensed. Because this project is intended to be MIT licensed, do **not** bundle Stockfish directly into the executable or source distribution by default.
Preferred approaches:
1. **User-provided engine path**
- User installs Stockfish or another UCI engine separately.
- GUI stores/configures the path.
- GUI launches it as an external process.
2. **Optional download flow**
- GUI can offer to download Stockfish or guide the user through downloading it.
- The download should be explicit and optional.
- The UI should clearly identify the engine and its license before download/use.
- Keep downloaded engine files outside the MIT-licensed source tree/release bundle unless licensing obligations are intentionally handled.
3. **Generic UCI analysis engine support**
- Do not hard-code Stockfish as the only option.
- Any compatible UCI engine path should work.
### Analysis engine UI/config needs
Eventually the GUI should provide:
- analysis engine executable path
- enable/disable analysis
- analysis depth or movetime
- optional thread/hash settings via UCI options
- current eval display
- principal variation display
- best move display
- start/stop analysis when stepping through playback
Suggested app-side abstraction:
```text
AnalysisEngine
├── engine_process / UciEngineClient
├── executable_path
├── enabled
├── depth or movetime limit
├── latest_score
├── latest_pv
└── latest_bestmove
```
## UCI protocol responsibilities
### GUI/client side
The GUI should be able to:
- Spawn an engine executable.
- Send UCI commands.
- Read engine output asynchronously or incrementally.
- Track engine readiness.
- Track available engine options.
- Send current game position.
- Request a move/search.
- Stop a search.
- Shut down the engine process cleanly.
Common commands sent by GUI:
```text
uci
isready
ucinewgame
position startpos
position startpos moves e2e4 e7e5
position fen <fen fields> moves ...
go depth 5
go movetime 1000
stop
quit
```
Common responses parsed by GUI:
```text
id name <name>
id author <author>
option name <name> type <type> ...
uciok
readyok
info depth 3 score cp 20 nodes 1234 time 10 pv e2e4 e7e5
bestmove e2e4
bestmove e2e4 ponder e7e5
```
### Engine/server side
Each engine executable should:
- Read one line at a time from stdin.
- Parse UCI commands.
- Maintain an internal position.
- Search when given `go`.
- Print `bestmove ...` when done.
- Print `info ...` optionally during search.
- Respond to `stop` promptly.
- Exit on `quit`.
## First milestone: minimal UCI engine executable
Implement an engine executable that supports only:
Input:
```text
uci
isready
quit
```
Output:
```text
id name ZigChess Random Bot
id author WayfinderAK
uciok
readyok
```
No search or move generation required yet.
Purpose:
- Prove executable separation.
- Prove stdin/stdout loop.
- Prove GUI/test harness can launch and communicate with engine.
## Second milestone: GUI-side engine process wrapper
Implement a UI/application-side wrapper that can:
- Start an engine executable by path.
- Send `uci`.
- Wait for `uciok`.
- Send `isready`.
- Wait for `readyok`.
- Send `quit` on shutdown.
Suggested name:
```zig
UciEngineClient
```
or:
```zig
EngineProcess
```
This code belongs on the GUI/controller side, not inside the engine bot.
## Third milestone: position and bestmove
Add UCI support for:
```text
position startpos
position startpos moves e2e4 e7e5
position fen <fen> moves ...
go depth 1
bestmove <move>
```
For the first engine, `go depth 1` can simply pick the first legal move or a random legal move.
Move format is UCI long algebraic coordinate format:
```text
e2e4
e7e8q
e1g1
```
This is different from SAN/PGN notation.
## Fourth milestone: reusable protocol module
Create shared parse/format helpers for UCI text:
```text
src/uci/protocol.zig
```
Potential responsibilities:
- Parse GUI-to-engine commands.
- Parse engine-to-GUI responses.
- Format moves as UCI coordinate moves.
- Parse UCI coordinate moves into from/to/promotion.
- Format `position ...` commands from a `Game` move list.
Keep protocol parsing separate from subprocess management and separate from search/evaluation.
## Fifth milestone: stronger engines
Once the protocol boundary works:
- random legal move engine
- material evaluation engine
- shallow search engine
- alpha-beta search engine
- improved move ordering
- transposition table
- time management
Each stronger engine can be its own executable or selected by options/config.
## Future lichess adapter
Do not put lichess-specific code inside the engine.
Instead, later create a separate adapter/service that:
- talks to lichess.org APIs
- manages authentication/account events
- receives games/moves from lichess
- launches or connects to an engine executable
- sends positions/search commands via UCI
- sends engine moves back to lichess
This keeps engines reusable by:
- GUI
- lichess adapter
- local match runner
- tournament harness
- tests/benchmarks
## Future playback analysis milestone
After the generic UCI client exists, add analysis support to playback mode:
1. Let the user configure an external UCI engine path.
2. Start that engine as an analysis process.
3. Send `uci` / `isready` handshake.
4. When playback cursor changes, send:
```text
position fen <current playback FEN>
go depth <n>
```
or:
```text
position fen <current playback FEN>
go movetime <ms>
```
5. Parse `info` lines for score and PV.
6. Display the latest analysis in the UI.
7. Send `stop` when the user moves to another ply or disables analysis.
8. Send `quit` when closing the app or changing engine path.
Keep this separate from bot-vs-human play. The analysis engine is an advisor for the user, not the implementation of project bots.
## References
Primary UCI reference:
- Stefan Meyer-Kahlen, **Universal Chess Interface (UCI)** protocol, April 2006. Commonly distributed as `uci.txt` and mirrored by chess-programming resources. Covers `uci`, `isready`, `position`, `go`, `stop`, `quit`, `info`, `bestmove`, and engine options.
Stockfish licensing/reference:
- Official Stockfish repository: https://github.com/official-stockfish/Stockfish
- Stockfish `Copying.txt`: GNU General Public License v3.0, https://github.com/official-stockfish/Stockfish/blob/master/Copying.txt
- Because the project goal is MIT licensing, Stockfish should be user-provided or optionally downloaded rather than bundled by default.
Useful related notation distinction:
- UCI moves are coordinate moves such as `e2e4` or `e7e8q`.
- PGN/SAN moves are display/game-record notation such as `e4`, `Nf3`, `O-O`, `Qxf7#`.
- The GUI move list should display PGN/SAN.
- Engine communication should use UCI coordinate moves.