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 Terrarium

with Terrarium() as client:
    # A catalogue name costs one catalogue read. An id goes straight through.
    world = client.worlds.create(scenario="grocery", name="mine")

    # You can also supply your own definition document.
    arena = client.worlds.create(definition={
        "schema_version": 2,
        "name": "arena",
        "locations": [{"name": "Town Square"}],
        "agents": [{
            "name": "Ana",
            "persona": "You are waiting for a friend.",
            "location": "Town Square",
        }],
    })

advance(n) queues the ticks and returns an AdvanceJob. The job is an operation bound to the client, so it can wait for itself. Store job.token when another process may need to resume the operation.

from terrarium import Terrarium

with Terrarium() as client:
    world = client.worlds.create(scenario="grocery")
    job = world.advance(8)
    token = job.token

    settled = job.wait()
    print(settled.status, settled.current_tick)

    # A later process can read the same operation from its stored token.
    resumed = client.operations.resume(token)
    print(resumed.status)

step(n) combines advance, wait, and world refresh. Only one advance runs for a world at a time. If another caller already started one, step waits for that work instead of posting a second advance. The default recovery budget is 30 minutes.

from terrarium import Terrarium

with Terrarium() as client:
    world = client.worlds.create(scenario="grocery")
    world.step(8)

An advance job carries its own status. job.wait() follows queued and running jobs until one of the four stopping states below.

A failed job makes wait() raise JobExecutionError. A paused or cancelled job returns its handle before the target tick. The world has a separate status: pending, running, paused, completed, failed, or exhausted. Call world.refresh() before reading that snapshot when another process may have changed it.

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 with data and has_more. It accepts limit and a world id as after. The SDK's worlds.list() walks pages lazily, and page.cursor holds the last world id to store when a later process must resume the walk.