For testing and AI experiments
The Rust simulator
You play the JavaScript game in your browser. On the development machine, a Rust copy of the same game runs the rules and all five computer opponents much faster, for tournaments, tests and experiments with new AI players.
The two versions are kept in lockstep: the same rules, the same dice, the same legal moves, and the same choice by every bot in every position. A change to one must land in both, and the checks listed below enforce that on every push.
How much faster
| 400–407× | Search-bot tournaments: Rust on all 32 threads against one JavaScript thread, as the browser plays |
| 188× | Random play through the legal-move list, Rust on 32 threads against one JavaScript thread |
| 30× | Search bots, one thread each |
| 31× | The rules alone, one thread each |
| Work | Rust | JavaScript | Faster |
|---|---|---|---|
| Rules alone, per command, one thread each | 0.44 µs | 13.6 µs | 31× |
| Random play from the legal-move list, one thread each | 177,000 commands/s | 13,100 commands/s | 13.5× |
| Random play, Rust on 32 threads | 2,460,000 commands/s | 13,100 commands/s | 188× |
| Classic against Tactical, 40 full games, one thread each | 1.4 s | 17.5 s | 12× |
| Sequence, Simulation and Apex, 144 three-round games, one thread each | 55.2 s | 1,669 s | 30× |
| The same kind of games, Rust on 32 threads (1,152 games, five runs) | 34.5–35.1 games/s | 0.086 games/s | 400–407× |
| Tournament runners, 16 workers each, the 144 games | 4.7 s | 214 s | 46× |
Rust figures are for the profile-guided build that tools/sim/build-pgo.sh makes. A plain release build is about 7% slower. Classic and Tactical gain least: each of their decisions looks at a position once, so the caches that let the search bots reuse work across similar positions do not apply. The runner comparison is limited by its few longest Apex games; once the short games finish, most workers wait.
How it got faster
A one-thread sample of 14 search-bot games: four Apex games on large boards and ten on small ones. Every step kept every decision identical. The fair dice changed every game, so the steps after them use the same boards and bots with the new dice. JavaScript plays the first sample in 233.5 s and the second in 232.1 s.
| Step | Date | Rust | Faster than JavaScript |
|---|---|---|---|
| First direct port of the JavaScript | Sep 27 | 99 s | 2.4× |
| Board tables, bucket-queue movement search, cached enemy moves | Sep 27 | 27.4 s | 8.5× |
| Reused candidate lists, occupancy grid, cached movement searches | Sep 27 | 15.7 s | 14.9× |
| Ranks computed once, fewer allocations | Sep 28 | 14.8 s | 15.8× |
| The fair dice: new games, same speed | Sep 28 | 14.2 s | 16.3× |
| Walking distances on whole-number buckets, step limits in the board tables | Sep 28 | 13.3 s | 17.5× |
| The enemy threat map on bitsets | Sep 28 | 12.2 s | 19.0× |
| Faster key hashing, fewer allocations, one position signature per step | Sep 28 | 10.8 s | 21.5× |
| Zone-of-control counts kept by the engine | Sep 28 | 9.8 s | 23.7× |
| Position scoring and action selection that skip work they cannot use | Sep 28 | 8.7 s | 26.7× |
| Profile-guided build: the compiler lays out the code by measured use | Sep 29 | 7.9 s | 29.4× |
Tried and removed because they did not help:
- reusing a unit's whole action list, which slowed the sample to 16.6 s;
- skipping distant enemies in the threat map, and reusing the previous threat map;
- smaller caches, and keeping the caches for a whole game instead of a turn (4% slower);
- looking up position values by distance instead of dividing;
- compiling for this CPU's full instruction set, and keys that carry their own hash (under 1% each);
- reusing an enemy's movement search while the hexes it read are unchanged (5% slower).
Where Rust spends its time
Sampled call stacks on the same sample, after the latest step, with the number of calls counted separately.
| Part | Cost |
|---|---|
| Rollouts: the quick playouts inside Sequence, Simulation and Apex | 68% of all time |
| A candidate-action list for a new position (44% of lists are reused) | about 39 µs |
| The enemy threat map for that list | about 10 µs |
| One unit's possible actions | about 7 µs |
| One search for an enemy's stopping cells | about 3.4 µs |
| Movement searches of every kind | 22% of all time |
| Memory allocation | 13% of all time |
| Hashing cache keys | 7% of all time |
The largest cost left is movement searches, half of them for enemies' stopping cells. 61% of those lookups miss the cache, because the key lists every unit near the enemy, including units the search never reaches. A version that remembered what each search had read was tried on 29 September. It turned 37% of those misses into reuse, but checking the roughly 178 hexes a search reads cost more than the searches it saved, and it was 5% slower.
One mid-game turn
One side's whole turn on NECTOR (30×20) at round 6 of Classic self-play from seed 3. Both versions end the turn in exactly the same position.
| Bot | JavaScript | Rust | Faster |
|---|---|---|---|
| Tactical | 0.095 s | 0.006 s | 16× |
| Sequence | 1.07 s | 0.035 s | 31× |
| Simulation | 2.47 s | 0.120 s | 21× |
| Apex | 19.6 s | 0.72 s | 27× |
Fair dice
Every match rolls its own dice: ChaCha20, a cryptographic stream cipher, keyed by a 256-bit seed. However many rolls a player or bot has seen, the next one cannot be predicted without the seed. A match with no seed, which includes every game in the browser and every tournament run started without one, draws a fresh seed from the operating system's random source. A given seed, such as 42, is stretched to 256 bits with SHA-256, so even a short seed cannot be searched.
No bot sees the dice. Bots imagine battles with their own separate generator, seeded from the public position. In Rust the dice cannot be reached from bot code: only the engine's attack rolls them, and only the state fingerprint can read them. In JavaScript a test plays tournament games with every bot and fails if anything other than an attack rolls the match's dice, or if anything reads them while a bot is thinking.
A tournament records its seed, so its games can be replayed exactly. It draws a fresh seed unless given one.
How we check that both versions match
The checks compare whole games, not samples of single rules. They start from 58 recorded games (20,107 commands) on boards from every family: Classic against Tactical played to the end, and short games of Sequence, Simulation, Apex and Marshal. Checks marked "Every push" run in GitHub's test workflow, and a failure holds the release of the live site.
| Check | What must be identical | When |
|---|---|---|
| Rust replay | Each recorded game replays to the same full-state fingerprint after every one of its commands | Every push |
| JavaScript replay | The same games replay in JavaScript to the same fingerprints | Every push |
| Legal moves | Both list the same legal commands, in the same order, at all 20,165 recorded positions | Every push |
| Listed moves are legal | The JavaScript engine accepts every listed command at sampled positions | Every push |
| Random games | 12 games of random legal commands (61,130 commands) end in the same position | Every push |
| Math | Rust's copies of Math.log and Math.tanh equal V8's, bit for bit, on 1,000,000 inputs | Every push |
| Rust bot decisions | The Rust bots choose every recorded command again from each game's board and seed | Every push |
| JavaScript bot decisions | Three recorded games are played again by their JavaScript bots, command for command | Every push |
| Caches | During the Rust bot check, every cached result is recomputed and compared | Every push |
| Tournament import | A 12-game Rust tournament on a fresh seed passes JavaScript's check of seeds, seats, moves and results | Every push |
| Game data | The terrain, units, boards and combat tables Rust reads equal the JavaScript data files | Every push |
| Wide check | 620 more games across all 119 boards: the same states, legal moves and bot commands | Before speed changes |
| Whole tournaments | Rust and JavaScript play the same tournaments to identical archives (476 and 144 games) | Before speed changes |
| Random-play benchmark | Both engines end the same 40 random games identically (76,027 commands) | Before speed changes |
| Turn timing | One bot turn from the same position ends in the same state in both | When timing |
The fingerprint is text built from everything that affects future play: the turn, the side to move, the last turn in which a unit lost a machine or a factory was captured (which starts the count toward a draw), the winner, the dice's position, every unit's type, side, place, strength, experience, remaining movement, action flags and cargo, and every building's owner and stored units.
It includes the dice's position because both versions draw one roll per shot from the same seeded dice. If one of them drew an extra roll, the board could look identical while every later battle came out differently. With the dice's position in the fingerprint, the check fails at the exact command where it happened.
Using it
The simulator lives in sim/ and needs Rust from rustup. From that folder:
cargo run --release -- tournament --out=/tmp/league --opponents=classic,tactical,beam,monte-carlo,apex --boards=0,1,2 --cycles=10 node ../tools/sim/import-rust.cjs /tmp/league cargo run --release -- playout --games=4000 cargo run --release -- replay cargo run --release -- decide --verify-caches
The import step checks every game in JavaScript and writes an archive; each game file opens in the Bot tournament page's replay viewer. For long runs, tools/sim/build-pgo.sh builds the profile-guided binary, checks it against the recorded games, and prints its path. It needs rustup's llvm-tools component. New AI players plug into the engine through two interfaces: one plays whole turns, the other picks one command at a time from the legal-move list. Before the browser offers a new player, it needs a JavaScript twin that decides identically.
Measured on 27–29 September 2026 on an AMD Ryzen 9 5950X (16 cores, 32 threads) with Node 22 and Rust 1.98. More detail on GitHub: the simulator's plan and measurements and running tournaments.