Configuration¶

Recommended API. Runtime configuration is user-facing. WorldConfig is primarily for custom hosts and lower-level engine construction.

StorageBackend ¶

Storage engine used for durable world data.

Field	Type	Default
`ICEBERG`	`StorageBackend`	`'iceberg'`
`LANCEDB`	`StorageBackend`	`'lancedb'`

Select the location and backend for durable world data.

Field	Type	Default	Description
`uri`	`str \\| Path`	`'./archetype_db'`	Local path or object-store URI for durable data.
`namespace`	`str`	`'ecs'`	Catalog namespace for world tables.
`backend`	`StorageBackend`	`'lancedb'`	Storage engine. Defaults to LanceDB.
`io_config`	`IOConfig \\| None`	`None`	Native Daft I/O configuration passed to Iceberg storage read/write operations.

Control when buffered world rows are flushed to durable storage.

Field	Type	Default	Description
`flush_rows`	`int`	`1000000`	Flush a table after it accumulates this many rows.
`flush_mb`	`int`	`512`	Flush a table after it reaches this size in megabytes.
`global_mb`	`int`	`1073741824`	Maximum memory budget across cached tables.
`idle_sec`	`float`	`30.0`	Flush a table after this many idle seconds.

Configure one bounded sequence of world ticks.

dev(*, steps=1, debug=True, show_rows=5, metadata=None)

Create a run configuration with interactive diagnostics enabled.

benchmark(
    *, steps, debug=False, show_rows=0, metadata=None
)

Create a quiet run configuration for performance measurement.

Field	Type	Default	Description
`run_id`	`str \\| UUID`	`generated by uuid7`	Stable identifier for this run, generated when omitted.
`num_steps`	`int`	`1`	Number of ticks to execute.
`debug`	`bool`	`False`	Emit per-tick diagnostic panels.
`show_rows`	`int`	`8`	Maximum rows shown in each debug snapshot; zero disables snapshots.
`metadata`	`dict[str, Any] \\| None`	`None`	Optional metadata recorded with the run.

Describe world identity and serializable engine state.

Runtime users normally create worlds through ArchetypeRuntime.world(). Custom hosts use this model when constructing the lower-level engine.

Field	Type	Default	Description
`world_id`	`str \\| UUID \\| None`	`generated by uuid7`	Unique identifier for the world. Auto-generated if omitted.
`name`	`str \\| None`	`None`	Human-readable alias for the world
`run_id`	`str \\| None`	`None`	Active run identifier
`tick`	`int`	`0`	Current simulation tick
`next_entity_id`	`int`	`1`	Next entity ID to assign
`entity2sig`	`dict[int, tuple]`	`generated by dict`	Entity ID → archetype signature mapping
`spawn_cache`	`dict[tuple, list[dict]]`	`generated by dict`	Pending spawn rows keyed by archetype signature
`despawn_cache`	`dict[tuple, list[int]]`	`generated by dict`	Pending despawn entity IDs keyed by archetype signature
`lineage`	`list[tuple[str, str, int]]`	`generated by list`	Ancestor read segments as (world_id, run_id, up_to_tick), ascending. Reads for ticks <= up_to_tick resolve to that ancestor's rows; later ticks belong to this world's own run. Populated by fork.