Documentation

Play in your browser

The homepage runs the real engine in a terminal — no install needed. The browser executes the same deterministic simulation core as the CLI, so a seed and a set of allocations produce the identical world here and on your machine. Play a turn with food=8 wood=4 gold=0 stone=0, or type /help for commands: /new <seed> to start another world, /map to print the terrain, and /replay <recipe> to reproduce any completed run.

Install

Requires Python 3.11 or newer. Install in editable mode with the development extras:

python -m pip install -e .[dev]

This installs the worldsim command and the test tooling. Run the full local verification gate once to confirm the install:

scripts/check.sh

Quick start: play survival-v1

The guided first-run experience is one command:

worldsim play --seed 7

You take control of Aster League / Astermere. The objective: survive eight turns with a population of at least 40 and gain at least 16 wood. Before each turn, allocate exactly 12 non-negative integer labor units across the four resources — in any order:

food=<n> wood=<n> gold=<n> stone=<n>

Unspecified resources default to 0, so food=8 wood=4 is the same as food=8 wood=4 gold=0 stone=0, and food=8 gold=4 means food=8 wood=0 gold=4 stone=0.

For example, food=8 wood=4 gold=0 stone=0 spends 8 units on food and 4 on wood.

After every accepted allocation you see the resources produced, the population and wood progress, and any notable world events. The run ends with an explicit result line and a replay recipe.

Seed 7 is the balanced first-run seed. Not every seed is winnable — survival and decline are both real outcomes depending on the world you draw.

Results and exit codes

• objective_met — turn eight: living settlement, 40+ people, 16+ wood gained.
• objective_unmet — turn eight without meeting the objective.
• population_crisis — early failure when population drops below 20.
• settlement_abandoned — early failure when the settlement is abandoned.

A finished success or failure is a valid outcome and exits 0. Invalid scripted input, or an interrupted interactive session before a result, exits 2.

Replay recipes

Every finished game prints a compact canonical recipe. Rerun any finished game non-interactively, byte-for-byte:

worldsim replay 'survival-v1;seed=7;actions=12,0,0,0|12,0,0,0|8,4,0,0|8,4,0,0|8,4,0,0|8,4,0,0|8,4,0,0|8,4,0,0'

A recipe is survival-v1;seed=<seed>;actions=<food>,<wood>,<gold>,<stone>|... — one action per turn, separated by a single |. The same seed plus the same ordered actions reproduces identical consequences, progress, and result.

The replay recipe grammar is intentionally strict so shared challenges are trustworthy. Invalid recipes are rejected before any turn executes.

Inspect the world map

Open a seed and see where everything is — which settlement sits on rich plain, which on forest, which on hills. The map is a pure function of the seed:

worldsim map --seed 7

Each tile is one character: . plain, F forest, H hills, ~ water, ^ mountain. A settlement site shows the first letter of its faction (A, B, C, ...) in place of its terrain glyph, and the legend names every settlement with the terrain it sits on:

MAP seed 7
Legend: . plain, F forest, H hills, ~ water, ^ mountain
F..HF..^FFHFF.HF
FFHF~.HFFH.~..~F
F..F..~H...HH..A
H~.H~H~HF~H.FFF~
.F..HF.~..FH..F.
^.......~..~FF.F
F..HFH.F....FF^H
.F^HFH.F...HHH.H
H~FF.H..^HFHFH.H
HHHH.~.FHH..F...
H..H~HFFH~HF.FFC
F.F.~.H..HF.B..~
F.~^FF...HHFH..H
...HFHF.H^...H..
....~F~..HF.F.^.
HFH.~F.FFH.H.H.~
Settlements: A Astermere (plain), B Brindlecrest (forest), C Calderhold (hills)

The same seed always produces the same map, so worldsim map --seed 7 is byte-identical on every run — including negative seeds and any faction count. Because each settlement's gather rates come from the terrain at its site, the map is not cosmetic: settlements on different terrain diverge in outcome, so you can read why one region grows while another starves.

Batch designer / debug mode

The original autonomous simulation remains available and byte-deterministic:

worldsim --ticks 12 --seed 7

Flags:

Without --verbose the event log focuses on growth, starvation, and abandonment. With it, you see the complete production log — useful for tuning the food economy and understanding scarcity.

Determinism

Determinism is the core contract. The same seed and inputs must produce byte-identical output. The repository enforces this locally and in CI:

worldsim --ticks 40 --seed 7 > /tmp/run1.txt
worldsim --ticks 40 --seed 7 > /tmp/run2.txt
diff /tmp/run1.txt /tmp/run2.txt   # must produce no output

The scripts/check.sh gate runs linting, the full test suite, and identical-run byte-diffs for batch, verbose, replay, and the terrain map.

The survival scenario proves choice-driven divergence, not hidden randomness: the same seed-7 world reaches a success or a crisis depending on the actions you take, and any completed run can be reproduced exactly from its recipe.

Status

See the changelog for the full history of what has shipped.