World handle

Recommended API. Create entities, run simulations, query history, and manage one world.

RuntimeWorld

RuntimeWorld

Operate one world through an ArchetypeRuntime.

Handles are lazy and safe to create before the world exists. The first operation activates the world. A handle also carries the identity used for authorization; as_actor() creates another view with a different identity while sharing the same world lifecycle.

world_id property

world_id

Return the durable world identifier after activation.

name property

name

Return the handle's local world name.

spawn async

spawn

Create an entity and return its reserved identifier.

ingest async

ingest

Persist an external fact exactly once per external identity.

Facts become durable immediately and do not join the active simulation. Repeating an identity with the same payload returns the original receipt; repeating it with a different payload raises an error.

spawn_many async

spawn_many

Create several entities in one batch.

Each entity's first persisted row contains its supplied components. Processors first apply on the following tick.

Parameters:

Name	Type	Description	Default
entities	list[list[Component]]	Component lists, one for each entity.	required

Returns:

Type	Description
list[int]	A list of entity IDs in the same order as entities.

spawn_batch async

spawn_batch

Spawn many copies of one component template.

spawn_batch(foo, 10000) is shorthand for building 10,000 component lists and sending them through the existing gated spawn_many batch path. The template components are deep-copied per entity so later mutation of one component instance cannot alias another spawned row.

Parameters:

Name	Type	Description	Default
*components_or_count	Component | int	Component templates, followed by a positional count; e.g. spawn_batch(Position(x=1), 10000).	()
count	int | None	Keyword count for multi-component archetypes; e.g. spawn_batch(Position(), Velocity(), count=10000).	None

Returns:

Type	Description
list[int]	A list of entity IDs in spawn order.

reserve_ids async

reserve_ids

Reserve entity identifiers without creating entities.

The returned IDs are drawn from the same monotonic counter as spawn / spawn_many, so interleaved calls produce disjoint ranges. Use spawn_reserved() to materialize a reserved ID.

Parameters:

Name	Type	Description	Default
n	int	Number of identifiers to reserve. Must be at least one.	required

Returns:

Type	Description
list[int]	Reserved identifiers in ascending order.

spawn_reserved async

spawn_reserved

Create an entity with a previously reserved identifier.

Parameters:

Name	Type	Description	Default
entity_id	int	A previously reserved ID (from reserve_ids).	required
*components	Component	Initial component values.	()

Raises:

Type	Description
ValueError	If entity_id is already registered.

despawn async

despawn

Remove an entity.

update async

update

Replace values on component types already held by an entity.

add_components async

add_components

Add component types to an entity.

remove_components async

remove_components

Remove component types from an entity.

add_processor async

add_processor

Install a processor on this world.

remove_processor async

remove_processor

Remove every installed processor of a type.

step async

step

Advance one tick.

run async

run

Advance the world by a number of ticks and return the run result.

run_episode async

run_episode

Run until an episode termination condition or step limit is reached.

run_rollout async

run_rollout

Run several episodes on forks of this world.

autoresearch async

autoresearch

Run an autoresearch loop with this world as the base save state.

Each iteration prepares an optional candidate, runs a rollout, and compares its score with the persisted incumbent. This base world is never mutated. Reusing config.experiment_id resumes the loop, and episode worlds remain available for inspection by default.

grade async

grade

Run graders against this world's append-only history.

Graders receive one lazy Daft DataFrame. Returned values are ephemeral; use evaluate() when the outcome needs a durable receipt.

evaluate async

evaluate

Persist one evaluation receipt for an evaluation identity.

The receipt is pinned to the current snapshot and grader contract. Repeating an evaluation identity returns its original receipt without grading again. Use a new identity for another nondeterministic trial.

info async

info

Get an immutable snapshot of world state.

fork async

fork

Create a copy-on-write fork and return its handle.

destroy async

destroy

Destroy the live world while retaining its durable rows.

shutdown async

shutdown

Close this handle without destroying the world.

query async

query

Return append-only history for entities with the requested components.

The result contains every matching tick, not only current state.

history async

history

Return recent audit-log rows for this world.

list_processors async

list_processors

Return summaries of installed processors.

list_hooks async

list_hooks

Return summaries of installed hooks.

add_hook async

add_hook

Install a hook on an active world.

Hooks needed during activation should be passed to runtime.world().

remove_hook async

remove_hook

Remove a hook by handle.

list_resources async

list_resources

Return summaries of installed resources.

as_actor

as_actor

Return a handle sharing this world but using another identity.