A Python framework for building AI bots for Hexagonal Tic-Tac-Toe (Connect-6 on an infinite hex grid). Fast C game engine, multiple neural network architectures, AlphaZero training pipeline, and a live training dashboard.
Home of the Orca bot.
Full guides, learning path, and feature reference live on the Wiki. Start with Quickstart or Concepts. Try it now in Colab: Guided tour (~30 min, builds up from game basics to training) or Advanced internals (MCTS math, training loss, optimisations).
Built a great bot with this? Open an issue or get in touch, and I'll feature it here.
Share bots with the community. Download by name, upload your trained checkpoints. Built-in metadata (architecture, ELO, author, description) keeps everything interoperable.
from orca.zoo import Zoo
# See what others have shared
Zoo.list()
# Try someone else's bot
bot = Zoo.download('orca-v3')
# Share yours
Zoo.package('hex_checkpoint_500.pt',
name='my-bot-v1', author='You', elo=1450,
description='Trained 500 iterations with hex-masked')
Zoo.upload('my-bot-v1.pt', name='my-bot-v1')Trained something interesting? Publish it and the next person can pull it with one line. See the Evaluation and Sharing wiki page for the full lifecycle (Arena, Leaderboard, Zoo).
No community bots rated yet. Train one, then Leaderboard().rate(bot, name='my-bot-v1') to land here. See Evaluation and Sharing.
This table is regenerated from leaderboard.json by scripts/update_featured_bots.py (runs in CI on every push to main).
pip install hexbotOr from source (for development):
git clone https://github.com/Saiki77/hexbot-building-framework.git
cd hexbot-building-framework
pip install -e . # core (game engine + torch)
pip install -e '.[dashboard]' # + dashboard UI
pip install -e '.[all]' # everythingThe C engine auto-compiles on first import (cc/gcc/clang required).
from hexbot import HexGame, Bot, Arena
game = HexGame()
game.place(0, 0) # P0: 1 stone first turn
game.place(1, 0) # P1: first of 2
game.place(1, -1) # P1: second stone
# Any function is a bot
def my_bot(game):
return game.legal_moves()[0]
result = Arena(my_bot, Bot.heuristic(), num_games=20).play()Pre-trained AlphaZero-style bot. The included checkpoint is early-stage (65 iterations) - gets significantly stronger with more training.
from hexbot import Bot
orca = Bot.orca()
move = orca.best_move(game)# From game collections (fast bootstrap)
python -m orca.scrape --games 5000 --output games.jsonl
python -m orca.sft --data games.jsonl --then-selfplay 50
# Pure self-play
python -m orca.train --iterations 100
# With web dashboard
python train_dashboard.py| Config | Params | Description |
|---|---|---|
fast |
656K | Quick experiments |
standard |
3.9M | Default Orca (128 filters, 12 ResBlocks) |
hex-masked |
3.9M | Hex-neighbor masked CNN (recommended for hex) |
large |
14.5M | Maximum strength (256 filters) |
orca-transformer |
4.4M | CNN + transformer attention |
hex-gnn |
432K | Graph neural network on hex topology |
multiscale |
1.1M | Local CNN + global attention two-tower |
python -m orca.train --config hex-gnn --iterations 50| Feature | Description |
|---|---|
| SFT Pipeline | Train from game collections (JSONL/CSV/text), chain with self-play |
| Endgame Solver | Deep alpha-beta with transposition cache, integrates with MCTS |
| Opening Book | Trie-based lookup from winning games, blends with MCTS policy |
| 6 Architectures | CNN, transformer, GNN, multiscale, hybrid, fast |
| Mixed Precision | FP16 on CUDA for 2x training speed |
| Distributed | Multi-GPU (DDP) and multi-machine (Ray) |
| Skill Curriculum | 6-level auto-progression: basics through endgame |
| Ensemble | Average N checkpoints with uncertainty estimation |
| Model Zoo | Share and download community models |
| Leaderboard | Rate bots against references, compare head-to-head |
| Plugin System | Register custom bots and network architectures |
| Dashboard | REST + WebSocket API, live game replay, charts |
| 30+ API Functions | NN eval, MCTS search, threats, solver, augmentation |
| # | Approach | Complexity |
|---|---|---|
| 1 | Hand-tuned evaluation | Low |
| 2 | Evolutionary weights | Low |
| 3 | Minimax with alpha-beta | Medium |
| 4 | Monte Carlo playouts | Medium |
| 5 | Neural network (AlphaZero) | High |
| 6 | Hybrid strategies | High |
hexbot.py Framework API (Bot, Arena, 30+ analysis functions)
hexgame.py Game engine (wraps C engine via ctypes)
engine.c 2,300 lines optimized C (bitboard win detection)
bot.py Neural networks, MCTS, training pipeline
dashboard.py Dashboard API (REST + WebSocket)
train_dashboard.py Training dashboard with web UI
pyproject.toml pip install config
orca/
__init__.py Orca bot loader
config.py All tunable parameters
train.py Training pipeline (CLI + library)
sft.py Supervised fine-tuning from games
scrape.py Game downloader
solver.py Endgame solver
openings.py Opening book
curriculum.py Skill-based curriculum
ensemble.py Multi-checkpoint ensemble
distributed.py Multi-GPU / Ray training
zoo.py Model zoo
leaderboard.py Bot rating system
transformer_net.py Transformer architecture
hex_gnn.py Graph neural network
multiscale_net.py Multi-scale architecture
benchmark.py Platform benchmark (compare Mac/CUDA/CPU)
checkpoint.pt Pre-trained weights
docs/ Detailed documentation
examples/ Example bot scripts
Compare performance across platforms:
python -m orca.benchmark --quick # ~30 secondsMeasures: C engine speed, NN inference, MCTS search, self-play, training steps, augmentation.
| Priority | Device | Platform |
|---|---|---|
| 1 | CUDA | NVIDIA GPU (Linux/Windows) |
| 2 | MPS | Apple Silicon (macOS) |
| 3 | CPU | Any platform |
Full docs live on the Wiki (16 pages organized by Learn / Build / Train / Evaluate / Reference).
Good starting points:
| Page | What it covers |
|---|---|
| Quickstart | 5 minutes from pip install to a bot playing |
| Game Rules | Hex Connect-6 rules in 60 seconds |
| Concepts | MCTS, AlphaZero, policy/value, ELO explained |
| Bot Approaches | Six complete bot designs with full code |
| Training Guide | Self-play, SFT, curriculum, distributed |
| Playing Online | Run your bot on hexo.did.science |
| API Reference | All public functions and classes |
| FAQ | Common pitfalls and questions |
Built for the Hexagonal Tic-Tac-Toe community. Contributions welcome.
MIT