Building a Xiangqi AI: Game Engine & Move Search Explained

A Xiangqi AI game engine is software that plays Chinese chess at or above expert strength by combining three parts: a fast move generator that encodes the 9×10 board and its unusual rules, a search algorithm that looks many moves ahead, and an evaluation function that scores each resulting position. Modern engines pair alpha-beta search with a compact, efficiently updatable neural network (NNUE), while AlphaZero-style systems learn to play entirely from self-play. The practical result is a program that can examine millions of positions per second and, on commodity hardware, play well above the level of most human masters.

Below is a build-oriented walkthrough of how these engines actually work — board representation, move search, evaluation, and the engineering traps unique to Xiangqi — written for product teams who want to ship a real playing engine, not just a demo.

What is a Xiangqi AI game engine made of?

Xiangqi (象棋), or Chinese chess, is played on a 9×10 grid of intersections — 90 points rather than chess's 64 squares — split by a central "river" with a 3×3 "palace" at each end. The pieces move differently from Western chess: the cannon captures only by jumping a single screen piece, the horse can be "hobbled" (blocked) by an adjacent piece, elephants cannot cross the river, and the two generals may never face each other on an open file (the "flying general" rule).

Any competent engine is built from four cooperating modules:

• Board and move representation — how positions and legal moves are stored and generated quickly.
• Search — the game-tree exploration that decides which move to play.
• Evaluation — a function that turns a leaf position into a single number (who is winning, and by how much).
• Time and rules management — clock control plus Xiangqi's repetition, perpetual-check and perpetual-chase rules.

Get these four right and everything else — opening books, endgame tables, a UCCI/UCI-style protocol for a GUI — is incremental. Get board representation or the repetition rules wrong and the engine will lose games it should draw or make illegal moves under tournament conditions.

How do you represent the board and generate moves?

Chess engines lean on 64-bit bitboards because a chessboard has exactly 64 squares. Xiangqi has 90 points, so a single 64-bit integer will not cover the board. Engine authors typically use one of two proven approaches:

• Mailbox / array boards — a simple 90-cell (often padded 16×11) array indexed by point, easy to debug and fast enough for many use cases.
• Multi-word bitboards — the board is split across two or more machine words, or represented as a 128-bit value, so piece attacks can be computed with bit operations and precomputed lookup tables.

Move generation must respect the pieces' geometric quirks: horse and elephant moves depend on whether an intermediate point is occupied ("leg" and "eye" blocking), and cannon captures require exactly one screen between attacker and target. Most engines precompute attack tables and use "magic"-style or plain lookup indexing so generating all legal moves for a position costs microseconds. A Zobrist hash — one random 64-bit key per (piece, point) combination, XORed together — gives every position a near-unique fingerprint used for the transposition table and repetition detection.

Which search algorithm powers move selection?

The workhorse of classical game engines is alpha-beta pruning, a refinement of minimax that discards branches which cannot affect the final decision. On top of raw alpha-beta, strong Xiangqi engines stack the same battle-tested techniques used in top chess programs:

• Iterative deepening — search to depth 1, then 2, then 3, reusing results to order moves and to stop cleanly when time runs out.
• Transposition tables — cache evaluated positions by Zobrist key so identical positions reached by different move orders are not re-searched.
• Move ordering — try captures, killer moves and history-heuristic moves first so pruning triggers earlier.
• Quiescence search — extend the search through forcing captures and checks to avoid the "horizon effect," where a threat is hidden just beyond the search depth.
• Null-move pruning and late-move reductions — spend less effort on lines that are almost certainly bad.

The alternative family is Monte Carlo Tree Search (MCTS) guided by a neural network, the approach popularised by AlphaZero. Instead of exhaustively pruning, MCTS repeatedly samples promising lines, guided by a network that outputs a move-probability policy and a position value. Xiangqi's average branching factor (roughly the high-30s) and game length make both families viable, and the strongest open engines today lean on the alpha-beta-plus-NNUE combination for raw speed.

How does the evaluation function decide who is winning?

Search only tells you which positions are reachable; evaluation tells you which are good. There are two dominant strategies, and the current state of the art blends them.

Handcrafted evaluation

The traditional method sums human-designed terms: material values (a chariot is worth far more than a soldier, and a soldier gains value once it crosses the river), piece-square tables, king safety inside the palace, mobility, and control of key files. It is transparent and easy to tune, but it caps out at the knowledge the designers encoded.

NNUE — a network built for search

NNUE (Efficiently Updatable Neural Network) is a shallow network whose input layer updates incrementally as pieces move, so it is cheap enough to call at every leaf of a fast alpha-beta search. It captures positional patterns a human never hand-codes while keeping the millions-of-nodes-per-second throughput that classical search needs. Training an NNUE evaluator for Xiangqi requires a large corpus of scored positions — usually generated by an existing engine's self-play — and a data pipeline for labelling and validation. This kind of applied machine learning work is where a specialist team earns its keep: the network architecture is standard, but the data engineering and evaluation loop determine final strength.

Can self-play reinforcement learning master Xiangqi?

Yes. The AlphaZero blueprint — a single deep network trained purely by playing millions of games against itself, guided by MCTS — has been reproduced for Xiangqi by research and open-source teams. The engine starts knowing only the rules, plays random-ish games, and gradually reinforces the moves that lead to wins. There is no human game database required, which is attractive for a game with fewer public datasets than Western chess.

The trade-off is compute. Self-play at scale is GPU-hungry and can take substantial cluster time to reach elite strength, whereas an NNUE bootstrapped from an existing engine reaches high strength on a fraction of the hardware. For most commercial products — a mobile app, a teaching tool, an in-game opponent — the pragmatic path is alpha-beta with a trained NNUE, reserving full self-play RL for teams that specifically want a from-scratch, patent-clean model. Both routes benefit from disciplined data science around training-data quality, Elo measurement and regression testing between versions.

Classical vs neural vs hybrid: which approach fits your product?

As of 2026, if you are building a consumer product, the hybrid column is almost always the right default: it delivers elite strength while running comfortably inside a mobile app or a web worker with no server-side GPU bill.

What are the hardest engineering challenges unique to Xiangqi?

Several problems trip up teams porting chess knowledge to Chinese chess:

• Repetition and perpetual rules — Xiangqi does not treat all threefold repetitions as draws. Perpetual check and perpetual chase are typically losses for the offending side under Asian federation rules, and encoding these correctly in search is genuinely intricate.
• The flying-general constraint — the generals facing each other on an open file is illegal, which subtly affects move legality and endgame tactics.
• Blocking geometry — horse "legs" and elephant "eyes" mean attacks are not purely a function of piece and target; the intervening points matter, complicating both move generation and evaluation.
• Endgame knowledge — many Xiangqi endgames are theoretically known; encoding them or building endgame tablebases materially improves practical strength.
• Protocol and UX — supporting a UCCI/UCI-style engine protocol so the core talks cleanly to a GUI, mobile front end or web board, plus adjustable difficulty that feels human rather than randomly weak.

Performance work is unglamorous but decisive: cache-friendly data layouts, incremental Zobrist and NNUE updates, and careful multi-threading (lazy SMP) are what separate a hobby engine from one that competes. General-purpose large language models from OpenAI, Google/Gemini or Anthropic's Claude are not game-tree engines and should not be asked to pick moves in a serious build — but long-context reasoning models are genuinely useful for developer tooling: refactoring the move generator, writing test harnesses and explaining lines to players.

Building a production Xiangqi AI with SpiderHunts Technologies

Shipping a game engine is as much a software-engineering problem as an AI one: you need a fast, correct core, a training and evaluation pipeline, and a front end that players across the USA, UK and Europe actually enjoy using. SpiderHunts Technologies has built AI and game-adjacent systems since 2015, and the same discipline that produces a strong engine — measurable Elo gains, reproducible training runs, regression tests between versions — is exactly what SpiderHunts Technologies applies to client projects.

A typical engagement moves through four phases: a correct rules-and-move-generation core with a full legality test suite; an evaluation strategy (handcrafted, NNUE, or self-play RL) chosen against your compute budget; a training and benchmarking loop with honest strength measurement; and integration into your app via a clean engine protocol. Teams that want the model embedded in a larger platform lean on our custom software development practice for the surrounding product.

Whether you are a games studio in Europe, an edtech company in the UK teaching Xiangqi strategy, or a US startup adding a Chinese-chess mode, SpiderHunts Technologies can help you decide between the classical, neural and hybrid paths — and then build the one that fits your hardware, timeline and quality bar.

Frequently Asked Questions

What algorithm do Xiangqi AI engines use to choose a move?

Most strong engines use alpha-beta pruning, a refinement of minimax that discards branches that cannot change the outcome. It is layered with iterative deepening, transposition tables, move ordering and quiescence search. The alternative is neural-network-guided Monte Carlo Tree Search, the AlphaZero approach.

Why can't you use standard 64-bit bitboards for Xiangqi?

A Xiangqi board has 90 points (9×10) rather than chess's 64 squares, so a single 64-bit integer cannot represent it. Engines instead use mailbox arrays or split the board across two or more machine words, often a 128-bit representation, to keep bitwise move generation fast.

What is NNUE and why does it matter for a Xiangqi engine?

NNUE (Efficiently Updatable Neural Network) is a shallow network whose inputs update incrementally as pieces move, so it is cheap to evaluate at every leaf of a fast search. It captures positional patterns humans never hand-code while preserving the millions-of-positions-per-second throughput that alpha-beta needs, which is why it defines the current state of the art.

Do I need a GPU cluster to build a strong Xiangqi AI?

Not necessarily. Full AlphaZero-style self-play training is GPU-hungry and can take substantial cluster time. A hybrid engine using alpha-beta plus an NNUE bootstrapped from existing self-play data reaches elite strength on far less hardware and runs on CPUs, including mobile phones.

What makes Xiangqi harder to program than Western chess?

Xiangqi has rules with no chess equivalent: cannons capture by jumping a screen, horses and elephants can be blocked by adjacent points, generals cannot face each other on an open file, and perpetual check or chase can be a loss rather than a draw. Encoding these repetition rules correctly in search is the trickiest part.

How long does it take to build a production Xiangqi engine?

It depends on the target strength and platform, but a typical project moves through four phases: a correct move-generation core with a legality test suite, an evaluation strategy chosen against your compute budget, a training and benchmarking loop, and integration into your app via a clean engine protocol. Hybrid alpha-beta plus NNUE is usually the fastest route to a shippable product.