Examples

Examples

The examples/ folder in the repo has ten ready-to-run scripts that exercise different parts of the framework. Each is small (under 100 lines) and self-contained.

See also: Quickstart | Bot Approaches

---

Running an example

# From the repo root
python examples/play_random.py

Each script uses sys.path.insert(0, '..') so it works whether you pip installed the package or are running from a clone.

What's in there

Script	Purpose	When to read it
bot_vs_bot.py	Random vs heuristic in an Arena, prints win rate	You want to see how Arena works
play_random.py	Heuristic vs random, prints the board move by move	You want to see a game play out in the terminal
custom_eval.py	Hand-tuned bot using evaluate_moves, find_threats, find_winning_moves	You want to write your first non-trivial bot without ML
evolutionary.py	Evolves evaluation weights via tournament selection	You want a learning approach without gradients
play_orca.py	Watch Orca play, or play against it interactively	You want to test the bundled checkpoint
train_bot.py	Five iterations of self-play training	You want a minimal training loop
train_orca.py	Same, using the orca pipeline	You want to call the production pipeline programmatically
dashboard_arena.py	Bot vs bot in the live dashboard	You want the visual version of bot_vs_bot
dashboard_train.py	Train with the dashboard live-updating	You want to watch training rather than reading logs
dashboard_custom_bot.py	Plug your own bot function into the dashboard	You want to A/B test your bot visually

Suggested reading order

If you're new, skim them in this order:

1. play_random.py to see what a game looks like
2. bot_vs_bot.py to see Arena
3. custom_eval.py to write something yourself
4. play_orca.py to see Orca in action
5. train_bot.py to see training
6. dashboard_train.py to see the full visual loop

The remaining four are variants or specialised use cases.

Modifying an example

The pattern is the same across all scripts:

1. Import what you need from hexbot.
2. Create a HexGame or a bot.
3. Call Arena(...).play(), bot.best_move(game), or train(...).
4. Print or save the result.

Copy any example to your own file, change one piece at a time, and you have a working starting point for your own work.