Worlds

A world starts from a scenario: either a name or id from the shared catalogue, or a definition document you own. List what you can reach with the client or the CLI; create your own definition when the catalogue does not fit.

from terrarium import Client

client = Client()
# Catalogue name (the client resolves it to an id, which costs one catalogue read and the observe scope; an id goes straight through):
world = client.worlds.create(scenario="grocery", name="mine")
# Or your own definition document:
world = client.worlds.create(definition={"name": "arena"})

advance(n) returns a receipt and the world ticks asynchronously. The receipt carries start_tick and target_tick. Poll with wait(target_tick) until the world reaches that tick, fails, or settles. step(n) is advance(n) then wait(receipt.target_tick).

receipt = world.advance(8)
world.wait(receipt.target_tick)
# Or the same in one call:
world.step(8)

A concurrent advance that the server refuses raises a conflict rather than retrying: call wait for the in-flight result. Default poll interval is 2 seconds; default wait budget is 30 minutes.

A world snapshot carries a status string. The values you will see:

wait raises when the world fails, carrying last_error. It returns early if the world settles at paused, completed, or exhausted short of the target tick.

world.usage() reads the usage block on the world snapshot. It needs the measure scope. Without that scope the field is absent and the client reports None, not zero. See Authentication.

A spend ceiling pauses a world rather than killing it. The world moves to paused; add funds and advance again when you are ready.

GET /v1/worlds returns a pagination envelope: { "data": [...], "has_more": bool }, with limit (default 100) and after (an id) as query parameters. The SDK's worlds.list() walks pages lazily so callers do not handle cursors by hand.