hyperchess-board-ui

HyperChess Core

The open-source engine for HyperChess — a chess variant played on a 12×12 board with two new jumping pieces, the Eagle and the Hawk. This repository contains the complete engine stack: bitboard move generation, a tournament-strength anytime search, an MCTS searcher, a CLI/UCI/REST driver, and a TypeScript + WebAssembly SDK so the engine runs anywhere JavaScript does — browsers, Node.js, serverless, and native.

New to the variant? The full rules live in docs/hyperchess-laws.md. The short version: bigger board, 20 pieces per side, and two raptors whose jump-checks cannot be blocked — only met.

The game in one table

Quick start (npm, 30 seconds)

npm install hyperchess-core

import { createGame, generateLegalMoves, addMove } from 'hyperchess-core';

const game = createGame();                            // standard 12×12 start
console.log(generateLegalMoves(game.board).length);   // every legal opening move
addMove(game, 'g3g5');                                // pawn double-step from rank 3

Want the full Rust engine (search included) in the browser? Add the WASM package and run it in a Web Worker:

import init, { WasmBoard } from 'hyperchess-wasm/web';

await init();
const board = new WasmBoard();
board.apply_move('g3g5');
const best = board.best_move_timed(64, 1000, 0);      // strongest move within 1000 ms

Quick start (Rust)

cargo add hyperchess-rules hyperchess-search

use hyperchess_rules::board::Board;
use hyperchess_search::{SearchLimits, TimedSearcher};
use std::sync::atomic::AtomicBool;

let board = Board::start_pos();
let mut searcher = TimedSearcher::pro();          // full pruning profile
let stop = AtomicBool::new(false);
let mv = searcher.search(&board, &SearchLimits::movetime(64, 1000), &stop);
println!("best: {}", mv.stringify());

Or run the engine binary directly:

cargo run -p hyperchess-driver -- uci        # speak UCI to any compatible GUI
cargo run -p hyperchess-driver -- api        # stateless REST API with OpenAPI docs

The search

The heart of this engine is a single canonical anytime search (TimedSearcher) that every entry point — CLI, UCI, REST, WASM — shares, so the engine plays identically everywhere. It is interruptible by wall clock, node count, or an atomic stop flag, and always returns the best move from the deepest completed iteration:

• Iterative deepening with aspiration windows
• Principal Variation Search (null-window probes, exact re-searches)
• Transposition table with root-safe probing and ply-normalized mate scores
• Countermove refutation table + killer moves + butterfly history with gravity
• The HyperChess-specific raptor bonus: Eagle/Hawk moves entering the enemy king's strike zone are tried early — their jump checks can't be blocked, so they refute more lines than history statistics alone would predict
• Null-move pruning (zugzwang-guarded), check extensions, late-move reductions
• SEE-pruned quiescence with evasion search (no stand-pat while in check)
• An Aggressive profile adding reverse futility, frontier futility, and delta pruning

There is also a full MCTS (UCT) searcher with static-eval rollouts and virtual-loss support for batched (GPU) leaf evaluation.

Zero dependencies

The engine proper — hyperchess-eval, hyperchess-rules, hyperchess-search — has zero external crates in its default build. Randomness comes from the engine's own seeded XorShift64* PRNG (which also makes MCTS runs exactly reproducible), lazy statics use std::sync::LazyLock. What you audit is what runs: the engine's supply-chain surface is this repository. (The optional wasm feature adds only js-sys, for the browser wall-clock; the driver and binding crates naturally carry their own CLI/server/wasm-bindgen dependencies.)

Every technique, every safety invariant, and the reasoning behind them is documented in docs/search-architecture.md.

Repository layout

Each crate and package carries its own README with details.

Documentation

Building from source

Prerequisites: Rust (stable, pinned by rust-toolchain.toml), Node.js ≥ 18, pnpm, and wasm-pack for the WASM SDK.

cargo build --workspace          # all Rust crates
cargo test  --workspace          # full Rust test suite
pnpm install && pnpm run build   # TypeScript packages
pnpm run test

See CONTRIBUTING.md for the full development guide.

Security

The engine is designed to be safe to expose to untrusted input: HFEN/HSAN parsers are bounds-checked, the REST driver is stateless (no session to poison), and the search never trusts a transposition-table move at the root — a hash collision can never inject an illegal move into play. Found something anyway? Please report it privately — see SECURITY.md.

License

GPL-3.0-or-later — the same convention as Stockfish and Fairy-Stockfish. Commercial use is fine; forks and redistributions must stay open. Dual-licensing is available on request.

Embedding note (GPL boundary): the recommended integration pattern for proprietary apps is to run the engine out-of-process — the WASM engine inside a dedicated Web Worker spoken to via postMessage, or the REST driver over HTTP. Your application then communicates with the engine rather than linking against it.

Contributing

Contributions are warmly welcome — engine strength, docs, ports, UI, test positions, all of it. Start with CONTRIBUTING.md and the good first issues. Please note the Code of Conduct.

Acknowledgments

This engine stands on the shoulders of the computer-chess community — Stockfish and the Chess Programming Wiki for the alpha-beta technique canon, the UCT/MCTS research line (Coulom; Kocsis & Szepesvári), and the Rust and WebAssembly ecosystems. The full thank-you list is in ACKNOWLEDGMENTS.md.

Development used orchestrated AI models (Claude, Codex, Gemini) as human-directed drafting and implementation aids — disclosed plainly, with the full provenance policy and correction process, in docs/ATTRIBUTION-AND-TRUST.md.

Citing

If you use HyperChess Core in research, see CITATION.cff.