chess/doc/stockfish-extended.md

# 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