HexSet

HexSet implements a hex-tile trading and building game based on the rules of Settlers of Catan: a NumPy rules engine, heuristic bots, 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 are maintained separately, in the sibling HexN project.

Games are hosted here even when the opponent comes from elsewhere: HexSet owns the rules, the legal actions and the ledger, and Catanatron is an external reference opponent seated at a HexSet table.

Documentation

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

Related MCP server: chess-mcp

Heximax

Heximax is HexSet's built-in search bot and the default opponent. It uses a budgeted expectimax/max^n search over the seat's information set, with move weights that adapt to public trading activity.

All games against Catanatron's depth-two alpha-beta player (AB2), hosted in the HexSet engine. The duel variant (rules.DUEL_VARIANT_GAME) is colonist.io's ranked 1v1 format, and it is a two-seat game type: a GameType carries the seat counts its ruleset is played at, so the engine will not deal it to a four-seat table. docs/heximax.md has the search, the evaluation terms, the measurement conditions and the endpoint pins.

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 opens a browser at http://127.0.0.1:8770. Share a game's URL to invite other players. Each new game starts with its creator seated and the remaining seats open. Fill them with people or bots, or close unused seats with the picker's none option. Play waits until every seat is filled or closed. Closed seats can be reopened before the first move; the participating seats are fixed once play starts.

The opponent picker lists heximax, catanatron when its extra is installed, and the models found in models/. A compatible .onnx file dropped there appears in the next listing under its filename stem; the requirements are the ONNX model contract.

The trade modal supports bank and port trades, offers to other players, and responses to their offers. How many cards a player trade moves is each seat's own declared limit — a manual seat is bounded only by the cards it holds. A bot makes as many offers a turn as its own gate asks for and waits for manual seats to answer before continuing. A seat with no resource cards passes automatically.

Games have a public spectator view that reveals all hands, development cards, and victory points. Anyone with the game URL can access it, including players at that table. Seat-specific responses filter hidden information, but the public view means a server game does not enforce secrecy between participants.

Running it anywhere but a local default -- ports, Docker, journals and the recovery rules -- is docs/server.md.

Repository layout

Tests

pip install -e ".[test,server,export,catanatron,gym]"
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 which extras are installed decides what a green run covered: docs/testing.md maps each extra to what it tests, and covers 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, and the base evaluator in hexset/catanatron/speedups.py is derived from it — that file names the upstream revisions it reproduces. 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.