lsdtools.ecs reference

Lazy public runtime-engine surface; importing this facade loads no DLL.

The runtime engine (``lsd-ecs``) is the native entity-component store every simulation
participant executes on. A package reaches it here -- never ``import lsd_ecs`` -- to declare
components, hold a world of its own, or read the engine's capabilities as data.

A numpy view over one page of a component: ``array[row]`` is the entity with index
``first + row``. Zero-copy; ``check`` refuses the view after a staged commit replaced the
page.

component: Component

array: np.ndarray

stage: np.ndarray | None

first: int

rows: int

count: int

pages: int

layout_epoch: int

check(self) -> ColumnView

self: (unannotated)

A component: ``dtype`` scalars, ``shape`` ``()`` for one per row or ``(k,)`` for a vector.

A ``bytes`` component is an opaque fixed-size struct: ``shape`` is ``(size,)`` and ``align`` its
alignment (a power of two up to 64). ``staged`` keeps a second page the writer fills and commits
(``World.commit``); ``reserve`` allocates the pages for that many entity indices up front.

name: str

dtype: str

dtype = 'float64'

shape: tuple[int, ...]

shape = ()

staged: bool

staged = False

align: int

align = 0

reserve: int

reserve = 0

width(self) -> int

self: (unannotated)

Scalars per row (bytes per row for a bytes component).

itemsize(self) -> int

self: (unannotated)

stride(self) -> int

self: (unannotated)

numpy_dtype(self) -> np.dtype

self: (unannotated)

The dtype of one row: the scalar dtype, or ``V<stride>`` for a bytes component.

Something about a world, a component, a query or a system was refused.

EcsStatusError(self, status: int, label: str, export: str) -> None

A native export answered a status other than ``ok``.

__init__(self, status: int, label: str, export: str) -> None

export: str
label: str
self: (unannotated)
status: int

status: (unannotated)

status = int(status)

label: (unannotated)

label = str(label)

export: (unannotated)

export = str(export)

NONE = 4294967295

NUMERIC_DTYPES: tuple[str, ...]

NUMERIC_DTYPES = ('float64', 'float32', 'int64', 'int32', 'int16', 'int8', 'uint64', 'uint32', 'uint16', 'uint8')

The native engine is not admitted in this process; ``engine_refusal()`` says why.

``lsd_ecs_physics_bridge_v1``: what the physics lane binds (pointers stay the caller's).

A cached set of matching entities.

world: World

id: int

require: tuple[str, ...]

exclude: tuple[str, ...]

entities(self) -> np.ndarray

self: (unannotated)

The matched handles right now (a copy; the query's order until ``sort``).

sort(self) -> None

self: (unannotated)

range(self) -> tuple[int, int] | None

self: (unannotated)

``(first, count)`` when the matches are one run of entity indices (``first + k`` is the
k-th match; a system may then walk the pages' rows directly), else ``None``. Joins keep a
run only at its tail and leaves only of its tail; ``sort`` makes contiguous indices a
run.

An entity handle names a generation the world destroyed.

A column view was used after the pool's layout changed under it.

What a system receives about the step it runs in.

dt: float

time_us: int

tick: int

substeps: int

phase: str

system: int

world: World

id: int

name: str

query: Query | None

phase: str

enable(self, enabled: bool=True) -> None

enabled: bool
self: (unannotated)

run(self, dt: float=0.0, *, substeps: int=1, time_us: int=0) -> None

dt: float
self: (unannotated)
substeps: int
time_us: int

profile(self) -> dict[str, int]

self: (unannotated)

World(self, *, max_components: int=64, entities: int=1024, page_rows: int=0, profile: bool=False, single_page: bool=False) -> None

One native runtime store.

__init__(self, *, max_components: int=64, entities: int=1024, page_rows: int=0, profile: bool=False, single_page: bool=False) -> None

entities: int
max_components: int
page_rows: int
profile: bool
self: (unannotated)
single_page: bool

``single_page`` makes every component one page of exactly ``entities`` rows (any count):
each column is one contiguous array whose row is the entity index, and the world holds at
most ``entities`` entities (the Trip's row layout).

close(self) -> None

self: (unannotated)

__enter__(self) -> World

self: (unannotated)

__exit__(self, *exc) -> None

exc: (unannotated)
self: (unannotated)

closed(self) -> bool

self: (unannotated)

page_rows(self) -> int

self: (unannotated)

single_page(self) -> bool

self: (unannotated)

define(self, component: Component | str, *, dtype: str='float64', shape: tuple[int, ...]=(), staged: bool=False, align: int=0, reserve: int=0) -> Component

align: int
component: Component | str
dtype: str
reserve: int
self: (unannotated)
shape: tuple[int, ...]
staged: bool

Define a component (a ``Component`` or a name plus its shape); returns the
declaration.

components(self) -> tuple[Component, ...]

self: (unannotated)

component_id(self, name: str) -> int

name: str
self: (unannotated)

defined(self, name: str) -> bool

name: str
self: (unannotated)

reserve(self, name: str, rows: int) -> None

name: str
rows: int
self: (unannotated)

Allocate the pages for entity indices below ``rows`` now, so later adds allocate
nothing.

create(self, count: int | None=None) -> int | np.ndarray

count: int | None
self: (unannotated)

Create ``count`` entities (a ``uint64`` array), or one (an ``int``) when ``count`` is
None.

destroy(self, entities: EntityLike) -> None

entities: EntityLike
self: (unannotated)

alive(self, entity: int) -> bool

entity: int
self: (unannotated)

add(self, name: str, entities: EntityLike, values: np.ndarray | None=None) -> None

entities: EntityLike
name: str
self: (unannotated)
values: np.ndarray | None

Give the component to the entities, zeroed or from ``values`` (one row per entity).

remove(self, name: str, entities: EntityLike) -> None

entities: EntityLike
name: str
self: (unannotated)

has(self, name: str, entity: int) -> bool

entity: int
name: str
self: (unannotated)

set(self, name: str, entity: int, value) -> None

entity: int
name: str
self: (unannotated)
value: (unannotated)

Write one row (adding the component when the entity lacks it).

get(self, name: str, entity: int)

entity: int
name: str
self: (unannotated)

One row as a numpy scalar (shape ``()``) or vector (a copy); ``None`` when absent.

column(self, name: str, page: int=0) -> ColumnView

name: str
page: int
self: (unannotated)

A zero-copy numpy view over one page of the component (``rows`` rows from entity index
``first``); rows of entities without the component hold unspecified bytes. The page is
allocated when it does not exist yet.

commit(self, name: str) -> None

name: str
self: (unannotated)

Swap the staged pages of a staged component in.

bind(self, name: str, array: np.ndarray, *, page: int=0, mark: bool=True) -> np.ndarray

array: np.ndarray
mark: bool
name: str
page: int
self: (unannotated)

Make ``array`` the page: the world reads and writes its memory as the component's rows
(``array[row]`` is the entity with index ``first + row``) and never frees it; the world
keeps a reference so the memory outlives every use. ``array`` must be C-contiguous, of the
component's dtype and ``(page_rows, *shape)``; ``mark`` adds the component to the page's
live entities without writing a byte (a read-only array binds as well: the world writes it
only through a system or ``set``). Binding the memory that already is the page moves
nothing (the page's lease epoch holds) and marks again.

bound(self, name: str, page: int=0) -> np.ndarray | None

name: str
page: int
self: (unannotated)

The array bound as the page, or ``None`` when the world allocated the page itself.

records(self) -> np.ndarray

self: (unannotated)

The entity table as a read-only ``(entities, record)`` uint64 view: the mask words, then
the generation word (bit 31 set while free), then padding to the record's power of two.
Valid until the next entity creation.

rows(self, name: str) -> np.ndarray

name: str
self: (unannotated)

The entity indices holding the component, ascending (a copy).

handles(self, indices: np.ndarray) -> np.ndarray

indices: np.ndarray
self: (unannotated)

The current handles of entity indices (from the generation table).

query(self, require: Iterable[str]=(), exclude: Iterable[str]=()) -> Query

exclude: Iterable[str]
require: Iterable[str]
self: (unannotated)

system(self, fn: SystemFn, query: Query, phase: str='step', name: str | None=None) -> System

fn: SystemFn
name: str | None
phase: str
query: Query
self: (unannotated)

Bind ``fn(world, entities, step)`` to the query in one phase; ``entities`` is a view of
the
query's matches valid during the call only.

systems(self) -> tuple[System, ...]

self: (unannotated)

bind_physics(self, name: str, bridge: PhysicsBridge) -> System

bridge: PhysicsBridge
name: str
self: (unannotated)

Bind the physics lane as a native ``step`` system: it steps the physics world once per
fixed step through the bound ``lsd_physics_world_step_scatter_v1`` and scatters the poses
into the scene's transform components. Every pointer in ``bridge`` stays the caller's and
must outlive the world.

rebind_physics(self, system: System, bridge: PhysicsBridge) -> None

bridge: PhysicsBridge
self: (unannotated)
system: System

Point a bound lane at other columns (the same physics world and row count): the body
columns moved, as a swap-in commit of a Trip value moves them.

unbind_physics(self, system: System) -> None

self: (unannotated)
system: System

Release a lane before its physics world or its columns go away: the system never runs
again and ``physics_status`` refuses it.

physics_status(self, system: System) -> tuple[int, int, int]

self: (unannotated)
system: System

The bridge's last step: (physics status, frames done, steps so far).

step(self, steps: int=1, dt: float=1.0 / 60.0, *, substeps: int=1, time_us: int=0) -> None

dt: float
self: (unannotated)
steps: int
substeps: int
time_us: int

Run ``steps`` fixed steps: the before, step and after systems, in definition order. An
exception a Python system raised is re-raised here, after the engine call returned.

run_phase(self, phase: str, dt: float=0.0, *, substeps: int=1, time_us: int=0) -> None

dt: float
phase: str
self: (unannotated)
substeps: int
time_us: int

run(self, system: System, dt: float=0.0, *, substeps: int=1, time_us: int=0) -> None

dt: float
self: (unannotated)
substeps: int
system: System
time_us: int

hash(self) -> int

self: (unannotated)

capture(self) -> bytes

self: (unannotated)

restore(self, capture: bytes) -> None

capture: bytes
self: (unannotated)

counters(self) -> dict[str, int]

self: (unannotated)

set_profiling(self, level: int) -> None

level: int
self: (unannotated)

phase_profile(self, phase: str) -> tuple[int, int]

phase: str
self: (unannotated)

The last run of every enabled system of ``phase``, summed: (nanoseconds, entities
visited).

profile(self, system: System) -> dict[str, int]

self: (unannotated)
system: System

describe(self) -> dict[str, object]

self: (unannotated)

The world as data: counters, components, queries and systems with their profiles.

capabilities() -> dict

The engine as data: whether it is admitted, its artifact and ABI digests, its limits.

engine_refusal()

Why the native engine is not admitted in this process, or None when it is.

entity_generation(entity: int) -> int

entity: int

entity_index(entity: int) -> int

entity: int

make_entity(index: int, generation: int=0) -> int

generation: int
index: int

memory_trim() -> int

Return the blocks closed worlds left for reuse to the OS; the bytes released.

ns_per_entity_system(step_ns: int, entities: int, systems: int=1) -> float | None

entities: int
step_ns: int
systems: int

`per-entity`: simulation-thread nanoseconds per entity per system; None when nothing was
visited.