hexo-engine 0.1.0

Game engine for HeXO — infinite hex tic-tac-toe on an unbounded hexagonal grid
Documentation

hexo-engine

A Rust game engine for HeXO — infinite hex tic-tac-toe played on an unbounded hexagonal grid.

Two players alternate placing stones (2 moves per turn) on a hex grid, competing to form a line of N consecutive stones. The board starts with a single P1 stone at the origin, and legal moves extend dynamically around existing stones.

Game rules

  • P1 opens with a stone at (0, 0), then P2 moves first (2 moves per turn)
  • Players alternate in pairs: P2(2), P1(2), P2(2), ...
  • Legal moves: any empty hex within a configurable radius of any placed stone
  • Win: form N-in-a-row along any of the 3 hex axes
  • Draw: move limit reached with no winner

The default configuration (FULL_HEXO) uses 6-in-a-row, radius 8, and a 200-move limit.

Usage

use hexo_engine::{GameState, GameConfig, Player};

// Standard 6-in-a-row game
let mut game = GameState::new();

// Or configure a smaller variant
let config = GameConfig { win_length: 4, placement_radius: 4, max_moves: 100 };
let mut game = GameState::with_config(config);

// P2 moves first
assert_eq!(game.current_player(), Some(Player::P2));

game.apply_move((1, 0)).unwrap();
game.apply_move((0, 1)).unwrap();

// Now it's P1's turn
assert_eq!(game.current_player(), Some(Player::P1));

// Query game state
let moves = game.legal_moves();         // sorted (q, r) pairs
let count = game.legal_move_count();     // no allocation
let done = game.is_terminal();
let winner = game.winner();

Crates

This workspace contains two crates:

hexo-engine

Core game logic — board representation, move validation, win detection, legal move generation. No dependencies beyond std.

  • Sparse board: HashMap<Coord, Player> — grows with the game, no fixed bounds
  • Incremental legal moves: cached HashSet updated on each move, no full recomputation
  • Efficient win detection: checks only the 3 hex axes through the last-placed stone
  • Configurable: win length, placement radius, and move limit

hexo-mcts

Gumbel AlphaZero MCTS implementation with graph construction for GNN evaluation.

  • Gumbel MCTS with Sequential Halving (Danihelka et al., 2022)
  • Batched neural network evaluation via a pluggable eval_fn
  • Graph construction: converts game states to node/edge tensors (8-dim node features, hex adjacency edges, legal/stone masks)
  • PyO3 bindings (optional python feature) for integration with Python ML pipelines

Interactive TUI

Play HeXO in the terminal:

cargo run --bin play -p hexo-engine --features tui

Controls: click to place, t for theme toggle, r to restart, q to quit.

Coordinates

HeXO uses axial hex coordinates (q, r) with 6 neighbor directions. Hex distance is max(|dq|, |dr|, |dq + dr|).

License

MIT