World handle

Package	Value
Distribution	archetype-ecs
Import package	archetype

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. The trusted runtime path is actor-free; authorization belongs to remote adapters at the dispatcher ingress boundary.

active_world_id property

active_world_id

Return the durable identity without activating this lazy handle.

world_id property

world_id

Return the durable world identifier after activation.

name property

name

Return the handle's local world name.

library

library

Construct one installed world-scoped library adapter.

spawn async

spawn

Create an entity and return its reserved identifier.

ingest_artifacts async

ingest_artifacts

Copy files into the artifact store and index their metadata.

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.

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 result 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. Durable receipts require an Iceberg-backed world; use grade() for ephemeral scoring on other storage backends.

info async

info

Get an immutable snapshot of world state (live or cold).

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.

artifacts async

artifacts

Return this run's common file-artifact index.

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.