Building a better settler
This is an open-source research project into optimizing computer players for the board game of Settlers, focusing on resource planning, uncertainty, trading, and adaptation.
There are developer-friendly client libraries for connecting to the server, writing a computer policy, and then playing against human and computer opponents. You can also contribute to the open-source research, and consult the roadmap to explore open questions.
Proposed and tested directions in resource planning, uncertainty, learning, trading, and cooperation.
Showing 17 of 17 ideas
The islandTested
Opening portfolios
Should you maximize production, diversify, or commit to a powerful specialization?
The islandTested
Build tempo
Which next build converts your current resources into progress fastest?
The islandTested
Expansion and races
When is an expensive road worth buying before an opponent closes the route?
The islandTested
Ports and market power
How does an outside option change what you should accept in a trade?
UncertaintyTested
Beliefs about hidden hands
How much should a player infer from production, spending, and refused trades?
UncertaintyTested
Search under uncertainty
What should expectimax average over, and where does opponent choice enter?
UncertaintyTested
Risk and timing
When should a player prefer reliable progress or a volatile route to victory?
UncertaintyTested
Development and surprise
When does a hidden option justify delaying a visible build?
UncertaintyTested
Learned pattern values
Can lookup tables of small board patterns, learned from self-play, replace the hand-written leaf and save a ply of search?
The conversationTested
Bilateral bargaining
How do you make a mutually useful trade without funding the winner?
The conversationProposal
Truthful signals
When does an honest explanation persuade more effectively than silence?
The conversationProposal
Bluffs and disclosure
What is the value of a bluff after you count lost credibility and revealed information?
The conversationTested
Reciprocity and reputation
Can a small concession buy enough future cooperation to recover its cost?
The conversationProposal
Bounded pliability
Should social context change expectimax itself, or rerank a bounded set of alternatives?
The tableTested
Leader containment
Who should pay to slow the leader, and when should you decline to help?
The tableTested
Opponent adaptation
How quickly should a player change its strategy when an opponent behaves differently?
The tableTested
Population and self-play
Does an approach remain strong when the table stops resembling its training partners?
Research approaches
Each approach describes a decision, a mechanism, and a proposed comparison.
These seventeen broad directions began as proposals. A narrow exchange-planning ablation was implemented and evaluated first and did not establish an improvement; a tunable search and, after it, a learned n-tuple leaf later became the protocol baseline. Read the evidence boundary before making a strength claim. The first arena report contains a recorded ten-point game and a real smoke-cohort chart.
Follow the dated experiment log for investigations and their next steps. The research workflow explains how agents file studies under an approach and keep these pages current.
Agent notes
Run a match
Requires Python 3.11+, just, and a reachable Settlers protocol v1 server.
The Python harness has no third-party dependencies. Rust is needed only to build
the local server and the bundled fast and eta opponents.
# From this repository. A separate server checkout defaults to ../server.
export SETTLERS_SERVER_DIR=/path/to/settlers/server
just setup
just server # foreground; http://127.0.0.1:5555In another terminal:
just doctor
just policies
just match fast eta fast eta --games 4
# A research-owned Python player can join the same lineup:
just match legal-first eta fast eta --games 4The harness registers a smoke experiment before playing, creates separate
credentials and processes for every seat, rotates the lineup, and prints a result
table. Four matches are a plumbing check, not a strength ranking. Ctrl-C records
an interruption and stops the owned players. The server retains the game; its
later timeout actions are outside that run's evidence.
Play games offline
The engine arena in the server checkout plays paired-seed games between the builders and both expectimax searches without a network. Register and run an engine experiment with:
just build-arena
just engine-register --study search/expectimax-v2 --seats v2 eta fast eta --seeds 0-63 \
--hypothesis '...' --decision-rule '...'
just engine-run EXPERIMENT_IDEngine runs are development-tier evidence. See the experiment program for the two tiers.
Register research
just study log/eta-comparison --title 'ETA at a fixed table' \
--question 'How does ETA compare against this frozen opponent lineup?'
python3 -m harness.cli register --study log/eta-comparison --players fast eta fast eta --games 40 \
--hypothesis 'ETA changes win rate against this fixed lineup.' \
--decision-rule 'Report uncertainty; make no superiority claim from a smoke cohort.'
just run EXPERIMENT_ID
just archive RUN_UUID /path/to/durable/artifacts
just publish RUN_UUID --match 0 --slug first-baseline
# Interpret the run, update its study and dated log, then refresh the notebook.
just notebook
just checkEdit a new experiment's settings and stop rules before its first run. Keep
completed protocols immutable. To change a configuration, create a new experiment.
For shell-sensitive arguments, use python3 -m harness.cli directly.
Standalone repository
This directory has its own Git repository. It can be moved or cloned without
web or design; there are no symlinks, submodules, or Python path imports into
its siblings. Set SETTLERS_SERVER_DIR for locally built Rust opponents, or
SETTLERS_SERVER_URL for an already running server. An all-stdio lineup needs no
local Rust checkout. Policy commands and source live in policies/.
The canonical source remote is settlerust/research. No artifact bucket is
assumed. The review configuration limits review to
authored Rust, TypeScript/TSX, and Python files.
Publish a research notebook
The separate Next.js application reads this checkout at ../research, or at
SETTLERS_RESEARCH_DIR, and renders Markdown/MDX under /research. Rebuild the
web app after changing content for a production deployment. It needs the checkout
at build time; no research server is needed to read the site.
Rich components come exclusively from @settlers/design and have Storybook
stories. Publishing instructions explain charts, selected
flat 2D replays, and provenance. Agent entry points are in AGENTS.md and
.agents/skills/.
just notebook refreshes the experiment index and study sections in approaches
and the roadmap. just site-check checks their filing and compiles the site's
MDX/assets. Research CI and web prebuild reject stale or unfiled evidence.
What belongs in Git
Keep policy code, preregistrations, compact run records, reports, and selected
exhibits. Raw per-game rows, event tapes, snapshots, server state, credentials,
and archives stay in ignored runs/, .runtime/, and artifacts/ directories.
Temporary research worktrees stay under ignored .worktrees/ inside this checkout.
just archive makes an immutable, hash-verified bundle without credentials or
private process logs; its receipt says where it actually exists. Git tracks the
evidence trail, not thousands of generated data files.
Watching a live research game
The harness creates explicit agent-only research tables and joins each policy with
its own join_agent command and JWT. Open /game/<gameId> in a web client configured
for the same game server to watch. Research spectators receive all current hands;
policies still receive only their own redacted observation. The game ID is printed
in the match record. The default research server port and web development server
port may differ; configure them to use the same server for live discovery.