HexSet

HexSet implements a hex-tile trading and building game based on the rules of Settlers of Catan: a NumPy rules engine, ONNX model inference, a browser interface, HTTP and MCP interfaces, Gymnasium and PettingZoo adapters, and batched environments for training and evaluation.

The engine covers resource production, construction, development cards, the robber, victory conditions and player trading. It owns the rules, information sets, encoding, game loops, seating and board pairing, records and replay, and trade evaluation. A training project supplies the model runtime and the learning algorithm through those interfaces; neural-network training and checkpoint export live in the sibling HexN project.

HexSet ships no playing bots. Its entrants are random (uniform over legal actions), retired (an empty seat), the network: and mcts: checkpoint kinds, which need a model runtime, and catanatron, Catanatron's alpha-beta player seated at a HexSet table as an external reference (optional extra). Every other bot is registered in process or joins over the API.

Documentation

Start with guide.md; the rest are listed by name.

Related MCP server: gap

Your own bots

A bot is anything with choose(game) -> Action; trading is an optional gate (hexset.bots.Bot, TradeGate). It reaches a table in process or over the API.

In process. A module registers how to build it when imported:

from hexset.arena import Entrant, register_entrant_kind, register_preset

register_entrant_kind("mybot", lambda entrant, board, rng: MyBot(board, rng))
register_preset("mybot", Entrant("mybot", kind="mybot"))

Every command that names bots takes --runtime <module> (repeatable) and imports it first, in each worker process too:

python -m hexset.bench.duel mybot random --runtime mybots --games 400
python -m hexset.server.web --runtime mybots

HexSetEnv(opponents=("mybot",) * 3, runtime=("mybots",)) seats it in the Gymnasium wrapper. hexset.arena.load_runtime("mybots") is the same import in code; register_spec adds a parsed spelling (mybot:depth=3) beside a preset. A name means one bot: registering a different one under a taken name raises ValueError, HexSet's own names (random, retired, catanatron) and prefixes (network:, mcts:, catanatron:, coalition:, handoff:) are refused, and unregister_* frees a name (docs/guide.md).

Over the API. A bot in any language joins a served table as a player (POST /api/join), reads /api/state and acts through /api/action, as a browser does (docs/api.md). python -m hexset.clients.botclient is an example of such a client. A Python bot that keeps an engine-side game in step with a table hosted elsewhere uses hexset.seat.Seat (docs/hosted.md).

Installation

Requires Python 3.11 or later. From the repository root:

pip install -e .

The base installation requires only NumPy. Install extras for the interfaces you use:

Extras can be combined, for example pip install -e ".[server,gym,test]".

Play in a browser

python -m hexset.server.web

The server listens on http://127.0.0.1:8770 (--host, --port) and opens that URL in a browser unless --no-browser is given. Share a game's URL to invite other players. The New game button asks for the board (spiral, the default, or random) and whether to play the duel rules (15 points, discard above 9, a friendly robber and balanced dice, at two seats). A new game seats its creator and leaves the other seats open: all four without duel rules, and one with them, the other two closed for good. Fill open seats with people or bots, or close a seat with the picker's none option. Play starts once every seat is filled or closed. Until the first move a seat can be closed, reopened or given a bot, except at a duel table; after it the seats are fixed.

The opponent picker lists every preset a --runtime registered, catanatron when its extra is installed, and every *.onnx file in models/ (or $HEXSET_UI_MODELS_DIR) under its filename stem. The directory is rescanned on each listing, so a file dropped there appears without a restart; it must meet the ONNX model contract.

The trade modal makes bank and port trades, offers to other players, and answers to their offers. A bot seat makes as many offers a turn as its own gate declares and waits for manual seats to answer. A manual seat has no card limit beyond its hand, and one holding no resource cards is passed on every offer.

GET /api/table/<code> needs no seat token and returns the whole game: every hand, development card and victory point. Anyone with the game URL can read it, players at that table included, so a served game does not keep hands secret between participants. Reads with a seat token filter hidden information.

Configuration, Docker, journals and recovery are in docs/server.md.

Repository layout

Tests

pip install -e ".[test,server,export,catanatron,gym,browser]"
playwright install chromium
pytest
pytest -m slow

The default run excludes tests marked slow; pytest -m "" runs every marker. Tests for an optional dependency skip themselves when it is absent, so the installed extras decide what a green run covered. docs/testing.md maps each extra to its tests, including the browser tests, which need a Chromium download beyond their extra.

License and attribution

HexSet is licensed under GPL-3.0-only. See LICENSE. Development history is in CHANGELOG.md; each release is also one commit here, whose message is that version's entry.

Dependencies are installed from PyPI or from git, never vendored into this repository, and each carries its own licence; the set and their extras are declared in pyproject.toml. Catanatron is GPL-3.0. The browser interface in hexset/server/static/index.html loads no third-party scripts, stylesheets or web fonts; its system font stack names fonts on the user's device rather than bundling them.

CATAN and SETTLERS OF CATAN are trademarks of Catan GmbH and Catan Studio. HexSet is not affiliated with, endorsed by, or sponsored by either company. The names identify the game whose rules this project implements.