Skip to main content

Crate ai_chess

Crate ai_chess 

Source
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 1

The 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 run

Licensed 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
CastlingRights
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.
FeatureDelta
Bounded set of NNUE feature changes caused by one chess move.
FloatNnueNetwork
Trainable floating-point form of the fixed tiny NNUE architecture.
IterationSummary
IterativeSearchReport
Result of iterative deepening under one cumulative budget.
Move
One fully classified chess move.
MoveList
Fixed-capacity legal or pseudo-legal move list.
NnueAccumulator
Incrementally maintainable pair of perspective accumulators.
Piece
A piece’s color and kind.
PieceContribution
Position
Complete, reversible chess position.
QuantizedNnueNetwork
Serialized integer form used by the runtime evaluator.
Score
A search score whose terminal provenance remains visible to the caller.
SearchConfig
Search limits and independently controllable teaching features.
SearchPreset
A named set of search limits and features for interactive play.
SearchReport
Complete result of one fixed-depth search attempt.
SearchStats
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.
EvaluationProfile
Controlled evaluator configurations used by tests and opponent settings.
GameResult
MoveError
MoveKind
Rules-level move classification.
NetworkError
PieceKind
The six orthodox chess piece kinds.
ScoreKind

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 position from 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 depth plies.
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 inside Position.