Expand description
§ai-chess
A small chess rules and search library with classical and NNUE evaluation.
Play against the Wasm engine here: https://thegustafson.com/games/chess
§Self-play
The selfplay binary runs deterministic paired-color matches. Each opening is
played twice with the engines swapping White and Black.
cargo run --release --bin selfplay -- \
--a maximum --b expert --games 12 --opening-plies 6 --seed 1The six built-in profiles are beginner, easy, medium, hard, expert,
and maximum. They all use Tiny NNUE so the matches isolate search strength;
each defines a maximum depth, node budget, time limit, and search features. Use
the --a-* and --b-* options shown by selfplay --help to override them,
including the evaluator when you want to compare evaluation methods. Library
users can read the same settings with search_preset or SEARCH_PRESETS.
§Use it
Add the crate to your project:
[dependencies]
ai-chess = "0.1"use ai_chess::{EvaluationProfile, Position, SearchConfig, iterative_search};
let position = Position::default();
let config = SearchConfig::classical(4, EvaluationProfile::TinyNnue)
.with_nodes(100_000);
let result = iterative_search(position, config);
assert!(result.result.best_move.is_some());The crate includes legal move generation, FEN and UCI notation, reversible moves, perft, iterative deepening, quiescence search, and transposition tables. The included binary speaks UCI.
cargo test
cargo runLicensed under the MIT License.
Re-exports§
pub use evaluation::Evaluation;pub use evaluation::EvaluationProfile;pub use evaluation::PieceContribution;pub use evaluation::evaluate;pub use evaluation::piece_contributions;
Structs§
- Candidate
- Castling
Rights - Four-bit set of orthodox castling permissions.
- Engine
- One UCI session shared by the native executable and the browser Worker.
- Evaluation
- A fully traceable score, always from the side-to-move’s perspective.
- Feature
Delta - Bounded set of NNUE feature changes caused by one chess move.
- Float
Nnue Network - Trainable floating-point form of the fixed tiny NNUE architecture.
- Iteration
Summary - Iterative
Search Report - Result of iterative deepening under one cumulative budget.
- Move
- One fully classified chess move.
- Move
List - Fixed-capacity legal or pseudo-legal move list.
- Nnue
Accumulator - Incrementally maintainable pair of perspective accumulators.
- Piece
- A piece’s color and kind.
- Piece
Contribution - Position
- Complete, reversible chess position.
- Quantized
Nnue Network - Serialized integer form used by the runtime evaluator.
- Score
- A search score whose terminal provenance remains visible to the caller.
- Search
Config - Search limits and independently controllable teaching features.
- Search
Preset - A named set of search limits and features for interactive play.
- Search
Report - Complete result of one fixed-depth search attempt.
- Search
Stats - Square
- One chess square in little-endian rank-file order (
a1 == 0). - Undo
- Opaque record containing every field changed by one move.
Enums§
- Color
- One of the two chess sides.
- Evaluation
Profile - Controlled evaluator configurations used by tests and opponent settings.
- Game
Result - Move
Error - Move
Kind - Rules-level move classification.
- Network
Error - Piece
Kind - The six orthodox chess piece kinds.
- Score
Kind
Constants§
- NNUE_
FEATURES - NNUE_
HIDDEN - NNUE_QA
- NNUE_QB
- SEARCH_
PRESETS - The built-in strength ladder, ordered from least to most search work.
Functions§
- builtin_
nnue - divide
- Returns the per-root-move breakdown of
perft. - evaluate
- Evaluates
positionfrom its side-to-move perspective. - iterative_
search - Iteratively deepen while retaining the TT and previous root move. A node budget is cumulative and exact; an interrupted iteration never replaces the last complete result.
- iterative_
search_ with_ history - Iteratively deepens with the game keys preceding
position. - nnue_
feature_ index - Shared feature transformer index, normalized into
perspective’s view. - perft
- Counts legal move sequences to exactly
depthplies. - piece_
contributions - Returns one traceable classical contribution per occupied square.
- search
- Search one fixed depth. Root candidates receive full windows so their displayed scores are comparable rather than incidental alpha-beta bounds.
- search_
preset - Finds a built-in strength preset by its lowercase name.
- search_
with_ history - Search with the real game keys that precede
position. The current key is appended, allowing exact threefold detection in a session without putting browser-specific history insidePosition.