Chess engine

trebuchet

C17

A separate engine in C, small and simple by design, with a network from the shared Reckless trainer. The strongest engine we have measured.

Strength
+144 Elo over Pawnstar 2.2.0 (Trebuchet 1.0.0, one thread, 8+0.08, 2026-11-07)
Licence
GPLv3 or later
Source
GitHub

README.md · on GitHub

Trebuchet was briefly called Zenith until 2026-11-06, and was renamed because another chess program already uses that name. Releases up to 3.0.0 and tags up to v3.0 were made under the old name, and version numbering restarted at 1.0 with the new one.

An independent UCI chess engine in C17 — its own search, move generation and data generation, written from scratch rather than ported — evaluating with the shared Reckless NNUE network.

The source code was written by Claude Code under the close supervision and direction of Jonny Reckless.

Trebuchet pairs a modern alpha-beta search — iterative deepening, principal-variation search, a lockless transposition table, the full pruning/reduction stack, and Lazy SMP — with a king-bucketed neural network evaluation: the shared Reckless NNUE, which every chess engine in the organisation now evaluates with, trained on Leela Chess Zero self-play data. The network shape is Trebuchet's own design, measured here; the weights it ships come from the shared trainer in nnue-training, and the nets it shipped before the release then numbered 3.0.0 were trained on PlentyChess positions — see Provenance of earlier networks.

Goals for the project were:

Usage

Trebuchet is a UCI engine: it speaks the protocol on standard input and output and draws nothing itself, so it is normally run by a host - Reckless Amphitheater, or any other UCI GUI - which is given the path to the binary and starts it. Everything it needs is inside that one file: the network and the opening book are embedded, so there is nothing to install beside it and nothing to configure before it will play.

Driven by hand, the shortest useful session is:

./build/trebuchet
uci                                   # it answers with its name, its options, then uciok
position startpos moves e2e4 e7e5
go movetime 1000                      # or: go depth 12 / go nodes 1000000 / go wtime 300000 btime 300000
stop                                  # if a search is still running
quit

A stop always gets a bestmove: one sent before the first depth has finished is answered with a legal move (never 0000), and one sent straight after go is not lost. Every output line is written in a single call, so readyok cannot land inside an info line.

go perft <depth> counts the moves below the current position instead of searching it, one line per root move and then the total: go perft 3 from the start position reports 8902.

Options

setoption name Hash value 256
Option Default What it is
Hash 64 The transposition table, in MB, 1 to 65536. More helps a long search and a slow time control most.
Threads half the logical CPUs (at least 1) Search threads, 1 to 256. The default gives each thread a real core on SMT machines. The table is shared and everything else is per thread. A score is only reproducible at Threads 1: above that the threads race through the shared table, so the same search can return a different score each time.
Move Overhead 20 Milliseconds held back from every move, for the time a host and the pipe between you take. Raise it if Trebuchet loses on time over a network.
Clear Hash - Empties the table. A host sends ucinewgame between games, which does the same thing.
EvalFile <embedded> A network file to use instead of the embedded one. It passes the same container checks, and the same net loaded this way searches exactly as the embedded one does.
OwnBook false Whether to play from an opening book at all. Off by default, deliberately: testing always runs bookless, so a measurement is of the search and not of the book.
BookFile <embedded> A Polyglot .bin to use instead of the embedded book. See books/README.md; make get-book fetches a free one and prints the two setoption lines.

Eleven further spin options - RfpMargin, NmpDivisor, LmpBase, FutilityBase, FutilityMargin, SeeCaptureMargin, LmrBase, LmrDivisor, SingularMargin, AspirationDelta and HistoryMax - expose the search's own margins and divisors for tuning. They are not settings to improve play by hand: the defaults are what the tuner arrived at, and the bench node signature below is computed with them, so changing one changes the signature and the engine no longer matches the number its own release asserts.

Commands of its own

The same binary answers a few commands as arguments rather than over the protocol:

./build/trebuchet bench [depth]          # fixed-depth search: the node signature, and nps. No depth = the pinned one
./build/trebuchet license                # the licence and the third-party notices
./build/trebuchet moves "<fen>"          # every legal move, in UCI notation
./build/trebuchet san "<fen>" <uci...>   # those moves written in SAN
./build/trebuchet applymoves "<fen>" [uci...]   # the FEN they lead to
./build/trebuchet polykey "<fen>"        # the position's Polyglot book key, 16 hex digits

bench is the one worth knowing: its node count is deterministic at a fixed depth, so it is both a speed measurement and a check that the search is behaving - a build whose signature differs from its release's has changed how it searches. The verification commands that go with it are in Verify.

Architecture

One translation unit per file, flat src/. No globals: all mutable engine state lives in an Engine aggregate (engine.h — the transposition table, the shared search state, the eval cache, and the loaded NNUE net), built by engine_new() and released by engine_delete() in main, passed explicitly everywhere; UCI session state is a UciSession on uci_loop's stack. The Zobrist keys, Q28 ln table, and the leaper/geometry attack tables are generated compile-time constants (tools/generate_tables.py → src/generated/*.inc). The one exception is bitboard.c's ~850KB magic sliding-attack tables, deterministically filled from generated constant multipliers by init_bitboards() — idempotent, called lazily by engine_new(), with no search or PRNG — before any thread exists.

File Contains
src/types.h Color, Piece (NO_PIECE=0..KING=6), Square, packed 16-bit Move + inline accessors, bit helpers
src/platform.h C11 threads.h / pthread thread shim + a monotonic clock
src/bitboard.* precomputed pawn/knight/king attacks, BetweenBB/LineBB, rook/bishop MAGIC bitboards
src/position.* bitboards + mailbox, Zobrist + pawn key, FEN I/O, copy-make, legality/check oracles
src/movegen.* one masked setwise generator: pseudo-legal + single-pass legal instantiations
src/engine.* the Engine aggregate (TT + shared search state + eval cache + NNUE net) + its new/delete
src/eval.* evaluate(): the NNUE forward pass (a net is always loaded); shared eval cache
src/nnue.* king-bucketed quantised NNUE: loader, feature indexing, AVX2 forward, finny refresh cache
src/book.* Polyglot opening book: key computation, probing, weighted move choice
src/tt.* lockless transposition table ({key^data, data} slots, bit-field payload)
src/search.* iterative deepening, PVS, quiescence, the pruning/reduction/extension stack, Lazy SMP
src/uci.* the UCI protocol loop, time manager, and CLI self-test subcommands
src/accumulator.h the NNUE hidden-layer accumulator embedded in Position
src/crc64.h CRC-64/XZ, the RNNUE1 container's integrity check
src/testfmt.h shared output format of the CLI self-test gates
src/version.h the version string, MAJOR.MINOR.BUILD from the git tags (tools/version.sh, stamped by the Makefile)
src/main.c entry + CLI dispatch
datagen/* standalone training-data tools (make datagen): self-play generation + a bulletformat-to-text converter

Board representation

Move generation

One masked setwise generator (generate_moves) is instantiated twice. generate_pseudo uses permissive masks and emits pseudo-legal moves into a caller-provided Move[MAX_MOVES] buffer terminated by a MOVE_NONE sentinel; the search then filters each move with the copy-free legality oracle — position_is_move_legal(move, checkers, pinned), built on precomputed pins and checkers — before it pays for make_move, so illegal and pruned moves never cost a copy. generate_legal instantiates the same skeleton with real check-evasion and pin-ray masks baked into the target sets (per-destination king safety; a full test only for en passant), producing fully legal moves in a single pass with no filter — this backs perft (about 470-530 Mnps on an i9-13900HX, MSYS2 CLANG64 clang, Windows 11, 2026-11-09), datagen, and UCI move parsing. The oracles (position_is_move_legal, pinned_to_king, gives_check_fast, discovered_check_candidates) are differentially validated against the copy-make ground truth (position_is_move_legal_slow) by the legalcheck gate.

Evaluation

A single seam — evaluate(const Position *, EvalCache *), centipawns from the side-to-move's perspective — is the one call site the network replaces.

Fail-soft principal-variation search inside iterative deepening with aspiration windows:

All the pruning/reduction margins live in SearchParams, exposed as UCI spin options and SPSA-tuned (tools/spsa.py); the tuned values are the shipped defaults.

UCI & time management

The protocol loop (uci.c) runs the search on a coordinator thread that spawns the Lazy-SMP helpers; stop sets a shared atomic. Options: Hash, Clear Hash, Threads, Move Overhead, EvalFile, OwnBook/BookFile, plus the tunable search parameters. The same binary exposes the CLI self-tests (bench, perft, legalcheck, seecheck, fuzzcheck, bookcheck, embookcheck, nnuecheck) and the NNUE verification helper (nnueeval); the training-data tools are separate executables built by make datagen. license is a command of the protocol as well as a subcommand (licence is accepted for either): it prints the GPL notice and the ODbL 1.0 attribution the embedded network's training data obliges, so a GUI or a match harness can ask the binary for it. It is the standard command across the Reckless engines, and it prints only - no engine or search state is read or written.

NNUE training pipeline

The trainers live in nnue-training — the single source for the Reckless NNUE: the architecture, the king-bucket map, the RNNUE1 container, both trainers and the data pipeline. Trebuchet is one of its consumers, and the split is producer asserts, consumer verifies — that repository asserts what a net is, and this engine checks every header field against its own compiled constants and refuses loudly, with no fallback, on a mismatch. What lives here is the loader (src/nnue.*), the net tools in tools/, and the engine-side gates.

So the pipeline is datagen (or an external dataset via bullet2text) → the shared trainer → a quantised .nnue in the RNNUE1 container (tools/stamp_net.py) → the engine loader. The shipped net need not come from Trebuchet's own data: any net of the shared shape loads, and the net shipped since the release then numbered 3.0.0, nets/reckless-lc0-runf-sb870.nnue, is trained entirely on Leela Chess Zero self-play data, from the shared Reckless NNUE pipeline — data published under the Open Database License 1.0, whose attribution notice is in THIRD-PARTY-NOTICES.md and printed by ./build/trebuchet license. The nets up to cap2 were trained on PlentyChess positions — see Provenance of earlier networks.

The single source of truth for the feature indexing and quantisation contract is nnue-training's pytorch/features.py, which src/nnue.c must reproduce byte-for-byte; its pytorch/verify.py enforces a 0 cp difference between the engine's integer eval and the Python reference. One file is deliberately copied into this repository — tools/rnnue1.py, verbatim nnue-training/spec/rnnue1.py, because three tools here import it and must run on a CI runner with no network: change it in both or in neither. See NNUE_TRAINING.md for the full contract, and nnue-training's README for how to train.

# the engine's side: data in, net verified and gated here
make datagen         # -> ./build/trebuchet-datagen + ./build/trebuchet-bullet2text
./build/trebuchet-bullet2text <shard.data> data/bullet/shard.txt 0 4   # bulletformat -> text
tools/datagen_parallel.sh 20000 data/run1 32 5000 8                    # or Trebuchet's own self-play
./build/trebuchet nnuecheck nets/reckless-lc0-runf-sb870.nnue           # incremental == full refresh
# the 0-cp contract gate, run from a nnue-training clone:
python3 pytorch/verify.py --net nets/reckless-lc0-runf-sb870.nnue --fens <fens> --engine /path/to/trebuchet/build/trebuchet

./build/trebuchet-datagen generates the engine's own self-play data (fen;stm_score;wdl records) across all cores via tools/datagen_parallel.sh; bullet2text converts a bulletformat dataset to the same text.

Opening book

Standard Polyglot .bin books are supported (src/book.c; the Polyglot Zobrist key computation is validated against the official spec vectors by ./build/trebuchet bookcheck). The repo ships Trebuchet's own book, books/trebuchet-book-r5.bin (487KB, ~14,000 positions) — built entirely from Trebuchet self-play by tools/build_book.py (screen/rescore every move with the engine, self-play playouts for near-ties, negamax backup over the position DAG), worth ~+30 Elo of clock savings and opening variety in self-play gates. Beyond the moves Trebuchet plays, it carries opponent coverage: prepared replies to plausible moves Trebuchet would not choose itself (1. d4, 1. c4, and ~14k others), so it stays in book against foreign repertoires. r5 is the builder's r4 with one move added by hand (tools/add_book_moves.py): 1. d4 at the root, weight 42 beside 1. e4's 115 and 1. c4's 54, so Trebuchet opens 1. d4 about a fifth of the time (42 / 211) and plays on into the ~2,100 positions r4 already held after it. The builder's trebuchet-book-r4.bin and the earlier, coverage-free trebuchet-book-r3.bin are retained alongside. Inspect it with tools/show_book.py (one SAN line of play per row). The book is embedded in every binary (like the net), so setoption name OwnBook value true alone enables it — no BookFile needed; BookFile loads an external book instead. OwnBook stays off by default: testing is bookless. Alternatively supply your own book, or fetch a free one with make get-book (downloads performance.bin from the GPL-3.0 python-chess repo into the gitignored books/):

make get-book                              # -> books/performance.bin (optional convenience)
setoption name BookFile value books/performance.bin
setoption name OwnBook value true          # default false — testing always runs bookless

Provenance & attribution

Trebuchet is written from scratch and shares no source code with any other engine. It uses the same published, textbook techniques every strong engine does — bitboards, magic bitboards, PVS, transposition tables, null-move/LMR/futility pruning, SEE, NNUE, Lazy SMP (see the Chess Programming Wiki) — implemented independently.

License

Trebuchet is free software licensed under the GNU General Public License v3.0 or later (see LICENSE). Copyright © 2026 Jonny Reckless. You may use, modify, and redistribute it under the terms of the GPL; derivative works must remain open under the same license.

Third-party notices are in THIRD-PARTY-NOTICES.md, which ships in every release archive and is printed by ./build/trebuchet license. Chief among them: the network embedded in every binary was trained on Leela Chess Zero self-play data, published under the Open Database License 1.0, and distributing the network obliges the attribution notice that file carries. The network is not itself ODbL-licensed and is not GPL.

← All five engines