v0.2.0 transitioned to api-only, extended and improved features, docs and tests added
This commit is contained in:
316
doc/stockfish-extended.md
Normal file
316
doc/stockfish-extended.md
Normal file
@ -0,0 +1,316 @@
|
||||
# Stockfish UCI Protocol Reference
|
||||
|
||||
## UCI Protocol Overview
|
||||
|
||||
Universal Chess Interface (UCI) is a text-based protocol for communication between chess engines and GUIs. Commands are line-based with ASCII encoding.
|
||||
|
||||
## Initialization Sequence
|
||||
|
||||
```
|
||||
→ uci
|
||||
← id name Stockfish 16
|
||||
← id author Stockfish developers
|
||||
← option name Debug Log File type string default
|
||||
← option name Threads type spin default 1 min 1 max 1024
|
||||
← option name Hash type spin default 16 min 1 max 33554432
|
||||
← [... more options ...]
|
||||
← uciok
|
||||
|
||||
→ isready
|
||||
← readyok
|
||||
```
|
||||
|
||||
## Core UCI Commands
|
||||
|
||||
### Engine Identification
|
||||
- `uci` - Initialize UCI mode, engine responds with options and `uciok`
|
||||
- `quit` - Terminate engine process
|
||||
|
||||
### Synchronization
|
||||
- `isready` - Synchronization command, engine responds `readyok` when ready
|
||||
- `ucinewgame` - Clear hash tables and reset for new game
|
||||
|
||||
### Position Setup
|
||||
```
|
||||
position [fen <fenstring> | startpos] [moves <move1> ... <moveN>]
|
||||
```
|
||||
- `startpos` - Standard starting position
|
||||
- `fen <fenstring>` - Custom position in FEN notation
|
||||
- `moves` - Apply moves from position in UCI format (e.g., e2e4, e7e8q)
|
||||
|
||||
### Search Commands
|
||||
|
||||
#### Basic Search
|
||||
```
|
||||
go [searchmoves <move1> ... <moveN>] [ponder] [wtime <ms>] [btime <ms>]
|
||||
[winc <ms>] [binc <ms>] [movestogo <n>] [depth <n>] [nodes <n>]
|
||||
[mate <n>] [movetime <ms>] [infinite]
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `searchmoves` - Restrict search to specific moves
|
||||
- `ponder` - Start pondering mode (thinking on opponent's time)
|
||||
- `wtime/btime` - White/black time remaining (ms)
|
||||
- `winc/binc` - White/black increment per move (ms)
|
||||
- `movestogo` - Moves until next time control
|
||||
- `depth` - Search to fixed depth
|
||||
- `nodes` - Search fixed number of positions
|
||||
- `mate` - Search for mate in N moves
|
||||
- `movetime` - Search for fixed time (ms)
|
||||
- `infinite` - Search until `stop` command
|
||||
|
||||
#### Search Control
|
||||
- `stop` - Stop calculating and return best move
|
||||
- `ponderhit` - Opponent played expected ponder move
|
||||
|
||||
### Engine Options
|
||||
```
|
||||
setoption name <option_name> [value <value>]
|
||||
```
|
||||
|
||||
## Stockfish-Specific Options
|
||||
|
||||
### Search Parameters
|
||||
- `MultiPV` (1-500): Number of principal variations to calculate
|
||||
- `Skill Level` (0-20): Playing strength limitation
|
||||
- `Contempt` (-100 to 100): Draw avoidance tendency
|
||||
- `Analysis Contempt` (Off/White/Black/Both): Contempt perspective
|
||||
- `Move Overhead` (0-5000ms): Time buffer for network/GUI delay
|
||||
- `Slow Mover` (10-1000): Time management aggressiveness
|
||||
- `UCI_AnalyseMode` (true/false): Optimization for analysis
|
||||
- `UCI_Chess960` (true/false): Fischer Random Chess support
|
||||
- `UCI_ShowWDL` (true/false): Show win/draw/loss probabilities
|
||||
- `UCI_LimitStrength` (true/false): Enable ELO limitation
|
||||
- `UCI_Elo` (1320-3190): Target ELO when strength limited
|
||||
|
||||
### Hash Tables
|
||||
- `Hash` (1-33554432 MB): Transposition table size
|
||||
- `Clear Hash`: Clear transposition table
|
||||
- `Ponder` (true/false): Think during opponent's turn
|
||||
|
||||
### Hardware Configuration
|
||||
- `Threads` (1-1024): Search threads (typically CPU cores)
|
||||
- `Use NNUE` (true/false): Neural network evaluation
|
||||
- `EvalFile` (path): Custom NNUE evaluation file
|
||||
|
||||
### Syzygy Tablebases
|
||||
- `SyzygyPath` (path): Directory containing tablebase files
|
||||
- `SyzygyProbeDepth` (1-100): Minimum depth for tablebase probing
|
||||
- `Syzygy50MoveRule` (true/false): Consider 50-move rule
|
||||
- `SyzygyProbeLimit` (0-7): Maximum pieces for probing
|
||||
|
||||
## Debug Commands
|
||||
|
||||
### Board Display
|
||||
```
|
||||
→ d
|
||||
←
|
||||
+---+---+---+---+---+---+---+---+
|
||||
| r | n | b | q | k | b | n | r | 8
|
||||
+---+---+---+---+---+---+---+---+
|
||||
| p | p | p | p | p | p | p | p | 7
|
||||
+---+---+---+---+---+---+---+---+
|
||||
| | | | | | | | | 6
|
||||
[...]
|
||||
+---+---+---+---+---+---+---+---+
|
||||
a b c d e f g h
|
||||
|
||||
Fen: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
|
||||
Key: 8F8F01D4562F59FB
|
||||
Checkers:
|
||||
```
|
||||
|
||||
### Evaluation
|
||||
```
|
||||
→ eval
|
||||
← Total evaluation: +0.25 (white side)
|
||||
← [detailed NNUE evaluation breakdown]
|
||||
```
|
||||
|
||||
### Performance Testing
|
||||
```
|
||||
→ bench [depth] [threads] [hash] [fenfile] [limittype] [evaltype]
|
||||
```
|
||||
Default: `bench 13 1 16 default depth mixed`
|
||||
|
||||
## Search Output Format
|
||||
|
||||
### Standard Info String
|
||||
```
|
||||
info depth <d> seldepth <sd> multipv <n> score <score> nodes <n>
|
||||
nps <n> hashfull <n> tbhits <n> time <ms> pv <move1> ... <moveN>
|
||||
```
|
||||
|
||||
Fields:
|
||||
- `depth` - Current search depth
|
||||
- `seldepth` - Selective search depth
|
||||
- `multipv` - PV number (when MultiPV > 1)
|
||||
- `score cp <n>` - Evaluation in centipawns
|
||||
- `score mate <n>` - Mate in N moves (negative if being mated)
|
||||
- `score lowerbound/upperbound` - Bound type in fail-high/low
|
||||
- `nodes` - Nodes searched
|
||||
- `nps` - Nodes per second
|
||||
- `hashfull` - Hash table saturation (per mill)
|
||||
- `tbhits` - Tablebase positions found
|
||||
- `time` - Search time (ms)
|
||||
- `pv` - Principal variation (best line)
|
||||
- `currmove` - Currently searching move
|
||||
- `currmovenumber` - Move number in root move list
|
||||
- `string` - Free-form engine output
|
||||
|
||||
### Win/Draw/Loss Output (UCI_ShowWDL=true)
|
||||
```
|
||||
info depth 20 score cp 15 wdl 395 604 1
|
||||
```
|
||||
WDL values in per mill: win/draw/loss from current side's perspective.
|
||||
|
||||
### Multi-PV Example
|
||||
```
|
||||
setoption name MultiPV value 3
|
||||
go depth 15
|
||||
|
||||
info multipv 1 depth 15 score cp 31 pv e2e4 e7e5 g1f3
|
||||
info multipv 2 depth 15 score cp 20 pv d2d4 d7d5 g1f3
|
||||
info multipv 3 depth 15 score cp 15 pv g1f3 g8f6 d2d4
|
||||
```
|
||||
|
||||
## Best Move Output
|
||||
```
|
||||
bestmove <move> [ponder <move>]
|
||||
```
|
||||
- `bestmove` - Best move in UCI notation
|
||||
- `ponder` - Expected opponent response for pondering
|
||||
|
||||
Special cases:
|
||||
- `bestmove (none)` - No legal moves (checkmate/stalemate)
|
||||
- `bestmove 0000` - Null move (analysis mode only)
|
||||
|
||||
## Advanced Analysis Techniques
|
||||
|
||||
### Infinite Analysis
|
||||
```
|
||||
position fen <position>
|
||||
setoption name UCI_AnalyseMode value true
|
||||
go infinite
|
||||
[... engine thinks until stop ...]
|
||||
stop
|
||||
```
|
||||
|
||||
### Multi-PV Analysis
|
||||
```
|
||||
setoption name MultiPV value 5
|
||||
position startpos moves e2e4 e7e5
|
||||
go depth 20
|
||||
```
|
||||
|
||||
### Mate Search
|
||||
```
|
||||
go mate 7 # Find mate in 7 moves or less
|
||||
```
|
||||
|
||||
### Fixed Node Search
|
||||
```
|
||||
go nodes 1000000 # Analyze exactly 1M positions
|
||||
```
|
||||
|
||||
### Search Move Restriction
|
||||
```
|
||||
position startpos
|
||||
go searchmoves e2e4 d2d4 g1f3 # Only consider these moves
|
||||
```
|
||||
|
||||
## Time Management
|
||||
|
||||
### Tournament Time Control
|
||||
```
|
||||
position startpos moves e2e4 e7e5
|
||||
go wtime 300000 btime 300000 winc 2000 binc 2000 movestogo 40
|
||||
```
|
||||
5 minutes + 2 second increment, 40 moves to time control.
|
||||
|
||||
### Sudden Death
|
||||
```
|
||||
go wtime 60000 btime 60000 # 1 minute each, no increment
|
||||
```
|
||||
|
||||
### Fixed Time Per Move
|
||||
```
|
||||
go movetime 5000 # Think for exactly 5 seconds
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Analysis Optimization
|
||||
```
|
||||
setoption name Threads value 8
|
||||
setoption name Hash value 4096
|
||||
setoption name UCI_AnalyseMode value true
|
||||
setoption name MultiPV value 1
|
||||
```
|
||||
|
||||
### Rapid/Blitz Optimization
|
||||
```
|
||||
setoption name Move Overhead value 100
|
||||
setoption name Slow Mover value 50
|
||||
setoption name Threads value 4
|
||||
```
|
||||
|
||||
### Endgame Optimization
|
||||
```
|
||||
setoption name SyzygyPath value /path/to/tablebases
|
||||
setoption name SyzygyProbeDepth value 1
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
Common error responses:
|
||||
- `Unknown command: <cmd>` - Invalid UCI command
|
||||
- `Illegal move: <move>` - Move not legal in current position
|
||||
- `Invalid position` - FEN parsing failed
|
||||
- `No such option: <name>` - Unknown engine option
|
||||
|
||||
## Protocol Extensions
|
||||
|
||||
### Chess960 (Fischer Random)
|
||||
```
|
||||
setoption name UCI_Chess960 value true
|
||||
position fen <chess960_fen> moves <move1> ...
|
||||
```
|
||||
|
||||
### Debug Logging
|
||||
```
|
||||
setoption name Debug Log File value debug.txt
|
||||
setoption name Use Debug Log value true
|
||||
```
|
||||
|
||||
### NNUE Evaluation
|
||||
```
|
||||
setoption name Use NNUE value true
|
||||
setoption name EvalFile value nn-[hash].nnue
|
||||
```
|
||||
|
||||
## Typical Usage Patterns
|
||||
|
||||
### Game Analysis
|
||||
1. Set analysis mode and resources
|
||||
2. Load position with game moves
|
||||
3. Run infinite analysis
|
||||
4. Stop and retrieve evaluation
|
||||
|
||||
### Opening Preparation
|
||||
1. Set MultiPV to compare variations
|
||||
2. Load opening position
|
||||
3. Search to fixed depth
|
||||
4. Compare evaluations of candidate moves
|
||||
|
||||
### Endgame Study
|
||||
1. Configure tablebase paths
|
||||
2. Load endgame position
|
||||
3. Search for mate or optimal play
|
||||
4. Verify with tablebase hits
|
||||
|
||||
### Engine Match
|
||||
1. Reset with ucinewgame
|
||||
2. Set time controls
|
||||
3. Apply moves incrementally
|
||||
4. Use ponder for thinking on opponent time
|
||||
Reference in New Issue
Block a user