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:
- Keep the source code relatively small and simple.
- Use C for portability and speed.
- Use an NNUE based evaluator.
- Train the evaluation weights as part of the project.
- Competitive play strength (greater than or equal to pawnstar).
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 digitsbench 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
-
Bitboards —
colors[2]andpieces[7](indexed byPiece; theNO_PIECEslot holds the occupied-squares bitboard) — plus aboard[64]piece-type mailbox (color comes fromcolors) for O(1) piece lookup, all kept in sync by the add_piece/remove_piece/move_piece primitives. - Zobrist hashing maintained incrementally, with a separate pawn-only key used by the eval correction history in search.
-
Copy-make.
Positionis a value type: the search copies the parent and appliesmake_moveto the copy, "undoing" simply by discarding it — there is no undo stack and nounmake_move. The NNUE accumulator is embedded inPositionand updated incrementally by the same primitives, so the copy carries a ready-to-use accumulator. (An in-place make/unmake was measured slower: the accumulator's feature-column reads dominate, and unmake would double them to save a cheap copy.) -
Sliding attacks via magic bitboards: the multipliers are generated offline (
make tables) and the attack tables filled deterministically at startup — portable, instant init.make pext(TREBUCHET_USE_PEXT) swaps in a BMI2_pext_u64index instead: bit-identical output, ~2% faster on Intel Haswell+/AMD Zen3+, but microcoded-slow on AMD Zen1/2 — so magic is the portable default and PEXT is opt-in for fast-BMI2 release builds.
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.
-
NNUE (primary): a king-bucketed 768×8 → 1024 → 8 output heads SCReLU perspective network. A
perspective whose own king sits on files e–h is mirrored horizontally (
square ^ 7) onto files a–d; the (mirrored) king square selects one of 8 input buckets (4 files × 2 board-halves), offsetting its 768-feature block, and the total piece count selects one of 8 material output heads. The accumulator is maintained incrementally insidePositionand carries its net binding (position_init(pos, net); the net itself is heap-loaded and owned by theEngine). A king move that changes a side's bucket or mirror state triggers a refresh accelerated by a per-thread finny cache (owned by eachSearcher, bound into its root position: a per-(perspective, mirror, bucket) cached accumulator plus the board it was built from, so a rebuild applies only piece diffs). The integer forward pass is AVX2-vectorised, and a shared lockless eval cache memoises results (its biggest win is qsearch stand-pat). Thennuecheckgate proves the incremental accumulator is bit-identical to a full refresh. -
Embedded by default: the shipped net is generated into a C array at build time (
tools/embed_net.py->build/embedded_net.o) and linked into every binary, so a bare executable is full strength with no external files;EvalFileswaps in another net at runtime. A net that fails any of the container's checks is refused with no fallback: the net already loaded keeps playing, and the engine says so on both streams — the loader's verdict (the field, the file's value and the engine's) and which net is in play instead, asinfo stringlines on stdout for a GUI and on stderr for a match harness. (The former PeSTO hand-crafted fallback was removed with the embedded default; it remains in git history.)
Search
Fail-soft principal-variation search inside iterative deepening with aspiration windows:
-
Transposition table — lockless for Lazy SMP: 16-byte
{key ^ data, data}slots with an XOR torn-read guard, relaxed atomics, and a bit-field payload; depth-preferred replacement with generation aging. Mate scores cross the boundary as distance-from-node. - Move ordering — TT move → captures (MVV-LVA) → promotions → killers → countermove → butterfly + continuation history; clearly losing captures are pruned by SEE rather than ordered late.
- Quiescence — captures and promotions only, SEE-pruned, with stand-pat.
- Pruning & reductions — null-move (adaptive reduction), reverse futility, futility, late-move pruning, late-move reductions (log-based table), SEE pruning, internal iterative reductions, and a pawn-keyed eval correction history.
- Extensions — check extensions and singular extensions (a TT-move exclusion search).
- Mate-distance pruning; repetition, fifty-move, and insufficient-material draw detection.
-
Lazy SMP — independent whole-tree searches share the lockless TT and eval cache; everything else
(history tables, killers, PV) is per-thread.
Threadsscales to 256.
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.
-
NNUE network: the shape Trebuchet designed and measured (king-bucketed, horizontally-mirrored 768×8→1024→8 SCReLU), now the shared Reckless NNUE that every engine in the organisation evaluates with, in the
RNNUE1container they all read. The network 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, and comes from the shared Reckless NNUE training pipeline (nnue-training) rather than from any trainer of this engine's own — which is why its file name saysreckless-lc0, the pipeline and the data, and not this engine's. No other engine's code is included or derived.Training-data attribution (ODbL 1.0). That data is published at https://storage.lczero.org/files/training_data/ under the Open Database License 1.0, with its contents under the Database Contents License 1.0. A trained network is an ODbL Produced Work, and distributing one obliges a notice naming the source:
Position data from the Leela Chess Zero self-play training data (https://storage.lczero.org/files/training_data/), run test91, used under the Open Database License 1.0 (http://opendatacommons.org/licenses/odbl/1.0/).
Position data from the Leela Chess Zero self-play training data (https://storage.lczero.org/files/training_data/), run test60, used under the Open Database License 1.0 (http://opendatacommons.org/licenses/odbl/1.0/).
The pool was 62.83 %
test91and 37.17 %test60. The obligation is the notice: ODbL does not require the network to be ODbL-licensed, and the network is not GPL merely because GPLv3 code trained it or reads it. The full notice, and every other notice this engine owes, is in THIRD-PARTY-NOTICES.md;./build/trebuchet licenseprints it from the binary.Provenance of earlier networks. This engine's networks up to and including cap2 were trained on positions from a public self-play dataset generated by PlentyChess, by Yoshie2000 — up to 2.15 billion positions. That data is no longer used, and those nets are no longer in the tree, so no release ships one. The attribution is kept here deliberately: those networks were measurably stronger for having been trained on that data, and the record should show where they came from. The full lineage, with every measurement as it was made, is in NNUE_TRAINING.md.
-
Opening book: the Polyglot key constants come from the public book-format specification; the book Trebuchet ships and embeds,
books/trebuchet-book-r5.bin, is built entirely from Trebuchet's own self-play, and no third-party book is bundled. -
Every notice in one place: THIRD-PARTY-NOTICES.md — the ODbL training-data notice, the Ethereal perft reference counts, the Polyglot format specification, and the earlier networks' data. It ships in every release archive beside the engine and the licence.
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.