Quickstart

Quickstart

Five minutes from pip install to watching a trained bot play. For the full API see Getting Started.

---

1. Install

pip install hexbot

You need a C compiler on PATH (cc, gcc, or clang) for the game engine to build on first import. Pre-built wheels ship for most platforms so usually nothing extra is needed.

2. Verify with a single game

from hexbot import HexGame, Bot, Arena

orca = Bot.orca()            # pre-trained checkpoint
heuristic = Bot.heuristic()  # rule-based opponent

result = Arena(orca, heuristic, num_games=1).play()
print(result)

You should see Orca win. It is stronger than the heuristic out of the box.

3. Watch it think

from hexbot import HexGame, mcts_search

game = HexGame()
game.place(0, 0)             # opening stone
game.place(2, 0)
game.place(2, -1)            # opponent's two

result = mcts_search(game, sims=200)
print(f"Best move: {result['best_move']}")
for move, visits in result['top_moves'][:3]:
    print(f"  {move} -> {visits} visits")

4. Play against it

Open the dashboard and play interactively:

python train_dashboard.py

Visit http://localhost:5000 and click the Play tab.

5. Train your own version

python -m orca.train --iterations 10

Ten iterations is a tiny warmup. Real ELO improvements show up around iteration 50+. To watch training live:

python train_dashboard.py

The dashboard shows games being played, loss curves, and ELO over time.

Where to next

• Game Rules for what you are actually playing
• Bot Approaches to write a bot from scratch
• Concepts for what AlphaZero and MCTS mean
• Training Guide to go deeper than 10 iterations