# lsdtools.runtime reference
URL: https://lsd.tools/docs/sdk-lsdtools-runtime
Updated: 2026-10-19

SDK distribution **1.0.0**; API contract **1.0**; generator **1.0.0**.

Product source digest: `170db6f659e9f79609ddaaec494ffad41f1d659a96001371132843e0c17a7e27`.

Generated from declared public exports and source syntax. Signatures and annotations are declaration spellings; decorators, factories and annotations are never executed. Class members below are declared members; base classes remain explicit. Source docstrings describe their owning implementation; they do not grant app permissions.

```text
The runtime service's public contract for the packages that author scenes and simulation
systems: lazy, headless.

A scene package's steps call ``build_scene_tables`` and ``scene_layer_payload``; its templates
derive identities with ``scene_id_for``; its declarations name ``OBJECT_NAMESPACE`` and
``SCENE_LAYER_KIND``; its tree seams ask ``member_kind`` which runtime role an entity plays.
A package that plays in a composition registers its participant with ``register_system`` (a
``SimulationSystem`` built per loaded composition, its ``SystemPhases`` around the fixed step,
its ``rank`` among the others) and reaches the loaded scene through the ``SceneRuntime`` the
driver hands its factory; ``BUILT_IN_PARTICIPANTS`` are the names the runtime keeps. Importing
this facade loads no engine, no driver and no view.
```


## `lsdtools.runtime.BUILT_IN_PARTICIPANTS`

Kind: value. Source: `services/runtime/src/lsd_runtime/systems/registry.py:52`.

```python
BUILT_IN_PARTICIPANTS = ('scene', 'lighting', 'ui', 'timeline')
```


Implementation alias: `lsd_runtime.systems.registry.BUILT_IN_PARTICIPANTS`.

## `lsdtools.runtime.CONTRACTS_PIN`

Kind: value. Source: `services/runtime/src/lsd_runtime/flow.py:42`.

```python
CONTRACTS_PIN: Final
```


```python
CONTRACTS_PIN = f'lsd-runtime-scene-v{SCENE_SCHEMA_VERSION}'
```


Implementation alias: `lsd_runtime.flow.CONTRACTS_PIN`.

## `lsdtools.runtime.DEFAULT_SHADER_ID`

Kind: value. Source: `services/runtime/src/lsd_runtime/core_tables.py:56`.

```python
DEFAULT_SHADER_ID: Final
```


```python
DEFAULT_SHADER_ID = 'lsd-shader/standard'
```


Implementation alias: `lsd_runtime.core_tables.DEFAULT_SHADER_ID`.

## `lsdtools.runtime.OBJECTS_DEFAULTS`

Kind: value. Source: `services/runtime/src/lsd_runtime/core_tables.py:104`.

```python
OBJECTS_DEFAULTS: Final
```


```python
OBJECTS_DEFAULTS = {'scale': (1.0, 1.0, 1.0), 'shader': DEFAULT_SHADER_ID, 'enabled': True}
```


Implementation alias: `lsd_runtime.core_tables.OBJECTS_DEFAULTS`.

## `lsdtools.runtime.OBJECT_ARCHETYPE`

Kind: value. Source: `services/runtime/src/lsd_runtime/core_tables.py:54`.

```python
OBJECT_ARCHETYPE: Final
```


```python
OBJECT_ARCHETYPE = 'object'
```


Implementation alias: `lsd_runtime.core_tables.OBJECT_ARCHETYPE`.

## `lsdtools.runtime.OBJECT_NAMESPACE`

Kind: value. Source: `services/runtime/src/lsd_runtime/navigation.py:19`.

```python
OBJECT_NAMESPACE: Final
```


```python
OBJECT_NAMESPACE = 'lsd-runtime/object@1'
```


Implementation alias: `lsd_runtime.navigation.OBJECT_NAMESPACE`.

## `lsdtools.runtime.PureSystemSeek`

Kind: class. Source: `services/runtime/src/lsd_runtime/systems/base.py:87`.

Source docstring:

```text
Explicit capability for state derived entirely from authored inputs and absolute tick.

The owner installs this as ``pure_seek`` during construction. ``apply`` must reproduce
its complete output after Timeline endpoints have been applied, including backward
jumps, without events, history, root integration or external input. Stateful owners
remain on the existing StateOwner/capture path. This is not reload-factory admission.
```


Implementation alias: `lsd_runtime.systems.base.PureSystemSeek`.

### `lsdtools.runtime.PureSystemSeek.apply`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:96`.

```python
apply: Callable[[int], None]
```


## `lsdtools.runtime.REFUSED_COLUMNS`

Kind: value. Source: `services/runtime/src/lsd_runtime/scene_build.py:49`.

```python
REFUSED_COLUMNS: Final
```


```python
REFUSED_COLUMNS = {'shape': _SHAPE_REASON, 'shape_kind': _SHAPE_REASON, 'extent': _EXTENT_REASON, 'ex': _EXTENT_REASON, 'e0': _EXTENT_REASON, 'extent_x': _EXTENT_REASON, 'archetype': "a scene holds runtime objects only: cameras and actors are a camera controller's, lights a lighting entity's"}
```


Implementation alias: `lsd_runtime.scene_build.REFUSED_COLUMNS`.

## `lsdtools.runtime.SCENE_CONTRACT`

Kind: value. Source: `services/runtime/src/lsd_runtime/contracts.py:35`.

```python
SCENE_CONTRACT: Final
```


```python
SCENE_CONTRACT = 'lsd:runtime'
```


Implementation alias: `lsd_runtime.contracts.SCENE_CONTRACT`.

## `lsdtools.runtime.SCENE_FEATURE_KIND`

Kind: value. Source: `services/runtime/src/lsd_runtime/scene_build.py:41`.

```python
SCENE_FEATURE_KIND: Final
```


```python
SCENE_FEATURE_KIND = 'runtime_object'
```


Implementation alias: `lsd_runtime.scene_build.SCENE_FEATURE_KIND`.

## `lsdtools.runtime.SCENE_LAYER_KIND`

Kind: value. Source: `services/runtime/src/lsd_runtime/scene_build.py:39`.

```python
SCENE_LAYER_KIND: Final
```


```python
SCENE_LAYER_KIND = 'runtime_objects'
```


Implementation alias: `lsd_runtime.scene_build.SCENE_LAYER_KIND`.

## `lsdtools.runtime.SCENE_LAYER_VERSION`

Kind: value. Source: `services/runtime/src/lsd_runtime/scene_build.py:40`.

```python
SCENE_LAYER_VERSION: Final
```


```python
SCENE_LAYER_VERSION = 4
```


Implementation alias: `lsd_runtime.scene_build.SCENE_LAYER_VERSION`.

## `lsdtools.runtime.SCENE_PORTS`

Kind: value. Source: `services/runtime/src/lsd_runtime/flow.py:39`.

```python
SCENE_PORTS: Final
```


```python
SCENE_PORTS = ('scene', 'objects')
```


Implementation alias: `lsd_runtime.flow.SCENE_PORTS`.

## `lsdtools.runtime.SCENE_SCHEMA_VERSION`

Kind: value. Source: `services/runtime/src/lsd_runtime/contracts.py:36`.

```python
SCENE_SCHEMA_VERSION: Final
```


```python
SCENE_SCHEMA_VERSION = 4
```


Implementation alias: `lsd_runtime.contracts.SCENE_SCHEMA_VERSION`.

## `lsdtools.runtime.SceneBundle`

Kind: class. Source: `services/runtime/src/lsd_runtime/bundle.py:26`.

Implementation alias: `lsd_runtime.bundle.SceneBundle`.

### `lsdtools.runtime.SceneBundle.scene`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/bundle.py:27`.

```python
scene: pa.Table
```


### `lsdtools.runtime.SceneBundle.objects`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/bundle.py:28`.

```python
objects: pa.Table
```


### `lsdtools.runtime.SceneBundle.feature_reference`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/bundle.py:29`.

```python
feature_reference: Mapping[str, Any]
```


```python
feature_reference = None
```


### `lsdtools.runtime.SceneBundle.from_tables`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:36`.

```python
from_tables(cls, tables: Mapping[str, pa.Table]) -> 'SceneBundle'
```


```python
cls: (unannotated)
tables: Mapping[str, pa.Table]
```


### `lsdtools.runtime.SceneBundle.tables`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:41`.

```python
tables(self) -> dict[str, pa.Table]
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.scene_id`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:45`.

```python
scene_id(self) -> str
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.name`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:49`.

```python
name(self) -> str
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.up_axis`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:53`.

```python
up_axis(self) -> str
```


```python
self: (unannotated)
```


Source docstring:

```text
``"z"`` (LSD's elevation axis) or ``"y"``: the axis gravity, jumps and capsules follow.
```


### `lsdtools.runtime.SceneBundle.rows`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:60`.

```python
rows(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.rows_by_eid`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:63`.

```python
rows_by_eid(self) -> dict[int, dict[str, Any]]
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.row_of_eid`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:66`.

```python
row_of_eid(self) -> dict[int, int]
```


```python
self: (unannotated)
```


Source docstring:

```text
Object eid -> object row (the frame row every consumer joins on).
```


### `lsdtools.runtime.SceneBundle.eid_of`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:70`.

```python
eid_of(self, oid: str) -> Optional[int]
```


```python
oid: str
self: (unannotated)
```


### `lsdtools.runtime.SceneBundle.describe`

Kind: method. Source: `services/runtime/src/lsd_runtime/bundle.py:77`.

```python
describe(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


## `lsdtools.runtime.SceneError`

Kind: class. Source: `services/runtime/src/lsd_runtime/errors.py:23`.

Source docstring:

```text
A scene bundle is internally inconsistent (unknown eids, duplicate seats, no camera).
```


Implementation alias: `lsd_runtime.errors.SceneError`.

Declared bases: `RuntimeServiceError`, `ValueError`.

### `lsdtools.runtime.SceneError.code`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/errors.py:26`.

```python
code = 'scene_error'
```


## `lsdtools.runtime.SceneRuntime`

Kind: class. Source: `services/runtime/src/lsd_runtime/driver.py:182`.

```python
SceneRuntime(self, bundle: Any, *, driver: 'RuntimeDriver') -> None
```


Source docstring:

```text
The loaded scene as the simulation thread holds it: the engine world and its columns.

Every runtime object is an entity of one ``lsd_ecs.World`` whose index is the object's row;
``position`` / ``orientation`` are zero-copy numpy views over the world's ``position`` and
``rotation`` pages (float64, one row per object of the bundle's objects table); ``enabled`` and
the immutable ``shader`` resource ids are what a published state carries beside them. The
participants' systems run as the world's systems (``bind_systems``): the timeline and the
``before_simulation`` phases in the engine's ``before`` phase, every ``step`` in ``step``, the
``after_simulation`` phases in ``after``, one ``world.step`` per fixed step. ``claimed_by(row)``
names the simulation system that moves a row, so no other system writes it. Systems also reach
the driver's input through ``sample_seats``, ask for a reset through ``request_reset`` and run
latest-value work on the simulation thread through ``schedule``.
```


Implementation alias: `lsd_runtime.driver.SceneRuntime`.

### `lsdtools.runtime.SceneRuntime.__init__`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:197`.

```python
__init__(self, bundle: Any, *, driver: 'RuntimeDriver') -> None
```


```python
bundle: Any
driver: 'RuntimeDriver'
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.close`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:285`.

```python
close(self) -> None
```


```python
self: (unannotated)
```


Source docstring:

```text
Release the engine world and every attached one (their column views become invalid).
```


### `lsdtools.runtime.SceneRuntime.bind_systems`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:297`.

```python
bind_systems(self, systems: Sequence[Any], *, timeline: Any) -> None
```


```python
self: (unannotated)
systems: Sequence[Any]
timeline: Any
```


Source docstring:

```text
Bind the participants to the world as its systems, in the driver's phase order.

The timeline advances first in the engine's ``before`` phase, then every participant's
``before_simulation``; every participant's ``step`` runs in ``step`` (the timeline has no
step of its own); every ``after_simulation`` runs in ``after``; then every ``bind_last``
defines the systems that run last in their phase. The participants come in rank order.
One ``world.step`` per fixed step then runs them all in that order, timing each on the
engine's clock.
```


### `lsdtools.runtime.SceneRuntime.step_world`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:364`.

```python
step_world(self, dt: float, substeps: int, time_us: int) -> int
```


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


Source docstring:

```text
One fixed step of the world; returns the engine's before-phase nanoseconds (the input lane).
```


### `lsdtools.runtime.SceneRuntime.begin_wake`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:369`.

```python
begin_wake(self) -> None
```


```python
self: (unannotated)
```


Source docstring:

```text
Remember the engine's counters so the wake reports its own deltas.
```


### `lsdtools.runtime.SceneRuntime.wake_report`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:381`.

```python
wake_report(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


Source docstring:

```text
The engine's numbers for the wake since ``begin_wake``: per-system simulation-thread
time, structural counters as deltas, memory gauges.
```


### `lsdtools.runtime.SceneRuntime.attach_world`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:435`.

```python
attach_world(self, name: str, world: Any) -> None
```


```python
name: str
self: (unannotated)
world: Any
```


Source docstring:

```text
Hold an engine world of a participant's own beside the scene's, during construction.

The world's systems become profiler rows of this scene under ``<name>.<system>``,
nested inside the interval of the scene system that steps the world (so they are listed
beside the scene's rows and never added to the wake's ``ecs.step_ns``); its gauges
(entities, bytes) stay its own and are described under ``attached``. The participant
steps the world itself, from one of the scene world's systems. The world is closed with
the scene.
```


### `lsdtools.runtime.SceneRuntime.attached_worlds`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:452`.

```python
attached_worlds(self) -> Mapping[str, Any]
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.snapshot_world`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:455`.

```python
snapshot_world(self) -> None
```


```python
self: (unannotated)
```


Source docstring:

```text
Read the world's counters for ``describe_world`` (one native call; simulation thread).

The structure behind the description (components, queries, the systems' identities) is
rebuilt only when the layout epoch or a count changed, so a publication pays one counters
read, not a walk of every component page and system profile.
```


### `lsdtools.runtime.SceneRuntime.describe_world`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:507`.

```python
describe_world(self) -> dict[str, Any]
```


```python
self: (unannotated)
```


Source docstring:

```text
The engine world as data (``describe_runtime``'s ``ecs`` block), from the last
``snapshot_world`` and the last wake report; no native call, so any thread may ask.

A system row carries the last wake's ``step_ns``/``calls``/``entities`` when the profiler
recorded that wake (the capture owns the engine's per-wake numbers); the engine's
cumulative profile is never published here.
```


### `lsdtools.runtime.SceneRuntime.apply_windows`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:549`.

```python
apply_windows(self, time_us: int) -> None
```


```python
self: (unannotated)
time_us: int
```


Source docstring:

```text
Gate every member by its play window at ``time_us`` (microseconds since Play).
```


### `lsdtools.runtime.SceneRuntime.refresh_alive`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:555`.

```python
refresh_alive(self) -> np.ndarray
```


```python
self: (unannotated)
```


Source docstring:

```text
``enabled`` after the member gate, in the persistent array the boards publish.
```


### `lsdtools.runtime.SceneRuntime.register_publication_field`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:563`.

```python
register_publication_field(self, name: str, values: np.ndarray) -> None
```


```python
name: str
self: (unannotated)
values: np.ndarray
```


Source docstring:

```text
A system declares fixed-row typed state during construction, before load completes.

The system keeps the same array and writes it only on the simulation thread.
A new shape/schema needs a new loaded world; render frames remain independent.
```


### `lsdtools.runtime.SceneRuntime.sample_seats`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:585`.

```python
sample_seats(self, seats: Sequence[SeatActions], tick: int) -> list[Optional[Sample]]
```


```python
seats: Sequence[SeatActions]
self: (unannotated)
tick: int
```


Source docstring:

```text
One sample per seat from the driver's reader for this fixed step, recorded in the trace.

The driver keeps one sampler per loaded world: its edge state (the sequence each seat
last saw) is part of a capture, and it is reset whenever the reader changes hands.
```


### `lsdtools.runtime.SceneRuntime.last_samples`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:593`.

```python
last_samples(self) -> tuple[int, dict[int, Optional[Sample]]]
```


```python
self: (unannotated)
```


Source docstring:

```text
The tick the driver last sampled seats at and one sample per sampled seat: what a
system that runs after the actors reads instead of sampling again (edges count once).
```


### `lsdtools.runtime.SceneRuntime.sampled_frames`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:604`.

```python
sampled_frames(self) -> list[Optional['SeatFrame']]
```


```python
self: (unannotated)
```


Source docstring:

```text
The live frames the last ``sample_seats`` read, one per seat in that call's order: what
a camera rig reads its own actions from. None for an unbound seat or a replayed trace.
```


### `lsdtools.runtime.SceneRuntime.request_reset`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:610`.

```python
request_reset(self) -> None
```


```python
self: (unannotated)
```


Source docstring:

```text
Restart the world from Play after the current fixed step (an actor's reset action).
```


### `lsdtools.runtime.SceneRuntime.schedule`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:614`.

```python
schedule(self, key: Any, callback: Callable[[], bool]) -> bool
```


```python
callback: Callable[[], bool]
key: Any
self: (unannotated)
```


Source docstring:

```text
Run ``callback`` on the simulation thread at the next wake; a later call with the same
``key`` replaces a pending one (latest value wins, so pointer-rate input never queues).
The callback returns whether it changed what a frame shows; the loop publishes once when
any did and no fixed step published in the same wake. Refused (False) while a seek owns
the world, once the world failed, or after this world was replaced.
```


### `lsdtools.runtime.SceneRuntime.register_capability`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:622`.

```python
register_capability(self, name: str, value: Any) -> None
```


```python
name: str
self: (unannotated)
value: Any
```


Source docstring:

```text
A system offers one named capability to its peers, during construction only.
```


### `lsdtools.runtime.SceneRuntime.row_of`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:636`.

```python
row_of(self, entity_id: str, oid: str) -> Optional[int]
```


```python
entity_id: str
oid: str
self: (unannotated)
```


Source docstring:

```text
The pose row of one member's object, or None when the composition does not play it.
```


### `lsdtools.runtime.SceneRuntime.member_active`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:645`.

```python
member_active(self, entity_id: str) -> bool
```


```python
entity_id: str
self: (unannotated)
```


Source docstring:

```text
Whether the member is inside its play window now (its rows are published).
```


### `lsdtools.runtime.SceneRuntime.register_presentation`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:652`.

```python
register_presentation(self, name: str, state) -> None
```


```python
name: str
self: (unannotated)
state: (unannotated)
```


Source docstring:

```text
Register independent numeric presentation rows before this world is published.

A schema or source change needs a new loaded world. A presentation does not create
scene objects, claim transforms, or add a simulation clock.
```


### `lsdtools.runtime.SceneRuntime.rows`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:674`.

```python
rows(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.claim`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:679`.

```python
claim(self, system: Any, rows: Any) -> None
```


```python
rows: Any
self: (unannotated)
system: Any
```


### `lsdtools.runtime.SceneRuntime.reclaim`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:698`.

```python
reclaim(self, system: Any, rows: Any) -> None
```


```python
rows: Any
self: (unannotated)
system: Any
```


Source docstring:

```text
Make ``rows`` exactly what this system claims, releasing the ones it gave up.

Staging a timeline document can drop a property, and the row it moved must go back to
whoever else may write it rather than staying claimed by a lane that no longer animates it.
```


### `lsdtools.runtime.SceneRuntime.claimed_by`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:710`.

```python
claimed_by(self, row: int) -> Any
```


```python
row: int
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.claimed_rows`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:713`.

```python
claimed_rows(self) -> list[int]
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.emit`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:716`.

```python
emit(self, event_type: str, **data: Any) -> None
```


```python
data: Any
event_type: str
self: (unannotated)
```


Source docstring:

```text
Publish on the driver's bus with the driver's identity (a system's own events).
```


### `lsdtools.runtime.SceneRuntime.bus`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:721`.

```python
bus(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.registry`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:725`.

```python
registry(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.driver_id`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:729`.

```python
driver_id(self) -> str
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.composition_id`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:733`.

```python
composition_id(self) -> str
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.tick`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:737`.

```python
tick(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.time_us`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:741`.

```python
time_us(self) -> int
```


```python
self: (unannotated)
```


Source docstring:

```text
Play time now: microseconds since Play, on the driver's fixed-step clock.
```


### `lsdtools.runtime.SceneRuntime.time_us_at`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:745`.

```python
time_us_at(self, step: int) -> int
```


```python
self: (unannotated)
step: int
```


Source docstring:

```text
The moment of play time fixed step ``step`` reaches on the current clock.
```


### `lsdtools.runtime.SceneRuntime.sim_time_ns`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:750`.

```python
sim_time_ns(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.config`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:754`.

```python
config(self) -> RuntimeConfig
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.cancel`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:758`.

```python
cancel(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.restore_authored`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:761`.

```python
restore_authored(self) -> None
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.pose_hash`

Kind: method. Source: `services/runtime/src/lsd_runtime/driver.py:765`.

```python
pose_hash(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SceneRuntime.bundle`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:200`.

```python
bundle: Any
```


```python
bundle = bundle
```


### `lsdtools.runtime.SceneRuntime.driver`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:201`.

```python
driver: 'RuntimeDriver'
```


```python
driver = driver
```


### `lsdtools.runtime.SceneRuntime.scene_id`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:202`.

```python
scene_id: (unannotated)
```


```python
scene_id = str(bundle.scene_id)
```


### `lsdtools.runtime.SceneRuntime.up_axis`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:203`.

```python
up_axis: (unannotated)
```


```python
up_axis = 1 if str(bundle.up_axis) == 'y' else 2
```


### `lsdtools.runtime.SceneRuntime.world`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:206`.

```python
world: (unannotated)
```


```python
world = World(max_components=64, entities=max(count, 1), single_page=True, profile=True)
```


### `lsdtools.runtime.SceneRuntime.entities`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:212`.

```python
entities: (unannotated)
```


```python
entities = self.world.create(count)
```


### `lsdtools.runtime.SceneRuntime.eid`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:229`.

```python
eid: (unannotated)
```


```python
eid = self._column('eid')
```


### `lsdtools.runtime.SceneRuntime.oid`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:230`.

```python
oid: (unannotated)
```


```python
oid = list(objects.column('oid').to_pylist())
```


### `lsdtools.runtime.SceneRuntime.row_of_eid`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:231`.

```python
row_of_eid: (unannotated)
```


```python
row_of_eid = {int(value): row for row, value in enumerate(self.eid.tolist())}
```


### `lsdtools.runtime.SceneRuntime.position`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:232`.

```python
position: (unannotated)
```


```python
position = self._column('position')
```


### `lsdtools.runtime.SceneRuntime.orientation`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:233`.

```python
orientation: (unannotated)
```


```python
orientation = self._column('rotation')
```


### `lsdtools.runtime.SceneRuntime.shader`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:234`.

```python
shader: (unannotated)
```


```python
shader = tuple((str(shader) for shader in objects.column('shader').to_pylist()))
```


### `lsdtools.runtime.SceneRuntime.enabled`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:235`.

```python
enabled: (unannotated)
```


```python
enabled = self._column('enabled')
```


### `lsdtools.runtime.SceneRuntime.entity_of_row`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:237`.

```python
entity_of_row: tuple[str, ...]
```


```python
entity_of_row = tuple((str(value) for value in objects.column('entity_id').to_pylist())) if 'entity_id' in objects.column_names else (str(driver.composition_id),) * count
```


### `lsdtools.runtime.SceneRuntime.member_gate`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:243`.

```python
member_gate: (unannotated)
```


```python
member_gate = self._column('member_gate')
```


### `lsdtools.runtime.SceneRuntime.alive`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:246`.

```python
alive: (unannotated)
```


```python
alive = self._column('alive')
```


### `lsdtools.runtime.SceneRuntime.property_leases`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:266`.

```python
property_leases: dict[tuple[int, str], Any]
```


```python
property_leases = {}
```


### `lsdtools.runtime.SceneRuntime.presentations`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:267`.

```python
presentations: (unannotated)
```


```python
presentations = MappingProxyType({})
```


### `lsdtools.runtime.SceneRuntime.capabilities`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:270`.

```python
capabilities: dict[str, Any]
```


```python
capabilities = {}
```


### `lsdtools.runtime.SceneRuntime.timeline`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/driver.py:273`.

```python
timeline: Any
```


```python
timeline = None
```


## `lsdtools.runtime.SimulationSystem`

Kind: class. Source: `services/runtime/src/lsd_runtime/systems/base.py:115`.

Source docstring:

```text
A registered system that moves some objects of the scene on every fixed step.
```


Implementation alias: `lsd_runtime.systems.base.SimulationSystem`.

Declared bases: `Protocol`.

### `lsdtools.runtime.SimulationSystem.name`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:118`.

```python
name: str
```


### `lsdtools.runtime.SimulationSystem.claims`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:120`.

```python
claims(self) -> Sequence[int]
```


```python
self: (unannotated)
```


Source docstring:

```text
The object rows this system moves; no other system may write them.

A system that lets an actor drive one of its rows offers ``<name>.drive`` through
``SceneRuntime.register_capability`` (``drive(row, sample, *, axes, force_scale,
jump_impulse, invert_second_axis, up_axis)``), which the camera controller calls for an
actor bound to that row's body; the protocol has no drive method.
```


### `lsdtools.runtime.SimulationSystem.step`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:130`.

```python
step(self, dt: float, substeps: int) -> None
```


```python
dt: float
self: (unannotated)
substeps: int
```


Source docstring:

```text
Advance one fixed step and write the claimed rows' poses into the scene arrays.
```


### `lsdtools.runtime.SimulationSystem.state_hash`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:134`.

```python
state_hash(self) -> int
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SimulationSystem.publish`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:136`.

```python
publish(self, *, final: bool) -> None
```


```python
final: bool
self: (unannotated)
```


Source docstring:

```text
Publish whatever the system publishes (a Trip on the bus, for physics); may be a no-op.
```


### `lsdtools.runtime.SimulationSystem.profile`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:140`.

```python
profile(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SimulationSystem.counters`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:142`.

```python
counters(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SimulationSystem.describe`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:144`.

```python
describe(self) -> Any
```


```python
self: (unannotated)
```


### `lsdtools.runtime.SimulationSystem.close`

Kind: method. Source: `services/runtime/src/lsd_runtime/systems/base.py:146`.

```python
close(self) -> None
```


```python
self: (unannotated)
```


## `lsdtools.runtime.SystemCommands`

Kind: class. Source: `services/runtime/src/lsd_runtime/systems/base.py:67`.

Source docstring:

```text
Owner validation and commit on the existing Driver command lane.

``prepare(operation, detached_payload)`` must validate without mutating the
world and return a zero-argument commit callback. Admission failures preserve
the world; a failed commit invalidates continuation like a failed fixed step.
The host's action/input authority remains responsible for admitting callers.
```


Implementation alias: `lsd_runtime.systems.base.SystemCommands`.

### `lsdtools.runtime.SystemCommands.prepare`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:76`.

```python
prepare: Callable[[str, Any], Callable[[], Any]]
```


### `lsdtools.runtime.SystemCommands.describe`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:77`.

```python
describe: Callable[[], dict] | None
```


```python
describe = None
```


## `lsdtools.runtime.SystemPhases`

Kind: class. Source: `services/runtime/src/lsd_runtime/systems/base.py:26`.

Source docstring:

```text
Optional work around the Driver's existing simulation stage.

``prepare`` binds peer capabilities after every system has claimed its rows,
before Timeline binds properties. All before callbacks run before any ``step``
(input is sampled and actors are driven here); all after callbacks run after
every ordinary ``step`` (cameras are evaluated here). Callbacks are prepared
once per world and use the same thread, fixed dt and publication transaction.
``reconstruct`` rebuilds derived output from restored state at a completed tick;
it does not qualify the owner for an absolute pure seek. ``bind_native`` binds the
owner's native lane to the scene's engine world (``scene.world``) right after its Python
``step`` was bound, so the native system runs after that step's pre-work in the same phase;
an owner with a native lane keeps its Python ``step`` for the work before the native step.
``bind_last`` is called with the scene after every participant's phases and native lanes are
bound, in rank order: an owner that defines its own engine systems there
(``scene.world.system``) runs them last in each phase, after every other participant's work
of that phase, and the driver adopts every new engine system as a profiler row of its own.
```


Implementation alias: `lsd_runtime.systems.base.SystemPhases`.

### `lsdtools.runtime.SystemPhases.prepare`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:45`.

```python
prepare: Callable[[], None] | None
```


```python
prepare = None
```


### `lsdtools.runtime.SystemPhases.before_simulation`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:46`.

```python
before_simulation: Callable[[float, int], None] | None
```


```python
before_simulation = None
```


### `lsdtools.runtime.SystemPhases.after_simulation`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:47`.

```python
after_simulation: Callable[[float, int], None] | None
```


```python
after_simulation = None
```


### `lsdtools.runtime.SystemPhases.reconstruct`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:48`.

```python
reconstruct: Callable[[int], None] | None
```


```python
reconstruct = None
```


### `lsdtools.runtime.SystemPhases.bind_native`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:49`.

```python
bind_native: Callable[[Any], None] | None
```


```python
bind_native = None
```


### `lsdtools.runtime.SystemPhases.bind_last`

Kind: attribute. Source: `services/runtime/src/lsd_runtime/systems/base.py:50`.

```python
bind_last: Callable[[Any], None] | None
```


```python
bind_last = None
```


## `lsdtools.runtime.UP_AXES`

Kind: value. Source: `services/runtime/src/lsd_runtime/core_tables.py:112`.

```python
UP_AXES: Final
```


```python
UP_AXES = ('y', 'z')
```


Implementation alias: `lsd_runtime.core_tables.UP_AXES`.

## `lsdtools.runtime.build_scene_tables`

Kind: function. Source: `services/runtime/src/lsd_runtime/scene_build.py:149`.

```python
build_scene_tables(scene_id: str, objects_in: pa.Table, *, up_axis: str='z', name: str='') -> dict[str, pa.Table]
```


```python
name: str
objects_in: pa.Table
scene_id: str
up_axis: str
```


Source docstring:

```text
The stamped ``scene`` and ``objects`` tables of one scene from its authored objects.
```


Implementation alias: `lsd_runtime.scene_build.build_scene_tables`.

## `lsdtools.runtime.declares_runtime`

Kind: function. Source: `services/runtime/src/lsd_runtime/flow.py:105`.

```python
declares_runtime(entity: Any) -> bool
```


```python
entity: Any
```


Source docstring:

```text
Whether the entity plays a runtime role at all.
```


Implementation alias: `lsd_runtime.flow.declares_runtime`.

## `lsdtools.runtime.declares_scene`

Kind: function. Source: `services/runtime/src/lsd_runtime/flow.py:51`.

```python
declares_scene(entity: Any) -> bool
```


```python
entity: Any
```


Source docstring:

```text
Whether the entity declares exactly one coordinate for every scene port.
```


Implementation alias: `lsd_runtime.flow.declares_scene`.

## `lsdtools.runtime.declaring_step`

Kind: function. Source: `services/runtime/src/lsd_runtime/flow.py:114`.

```python
declaring_step(entity: Any, port: str) -> Any
```


```python
entity: Any
port: str
```


Source docstring:

```text
The step of ``entity`` that declares output ``port`` exactly once, found by its coordinate.

Editors open a member's authored document through the step that declares the participant's
port (a UI entity's ``ui``, an animation entity's ``animation``); they never know the step's
class, which belongs to a package.
```


Implementation alias: `lsd_runtime.flow.declaring_step`.

## `lsdtools.runtime.member_kind`

Kind: function. Source: `services/runtime/src/lsd_runtime/flow.py:80`.

```python
member_kind(entity: Any) -> Optional[str]
```


```python
entity: Any
```


Source docstring:

```text
The one runtime role the entity plays, or None.

Raises ``ValueError`` when the entity declares the outputs of several participants: an
entity owns the objects of one role; what plays beside it is another entity of the same
composition.
```


Implementation alias: `lsd_runtime.flow.member_kind`.

## `lsdtools.runtime.mesh_resources_fingerprint`

Kind: function. Source: `services/runtime/src/lsd_runtime/scene_mesh_resources.py:95`.

```python
mesh_resources_fingerprint(objects, *, base_dir=None)
```


```python
base_dir: (unannotated)
objects: (unannotated)
```


Source docstring:

```text
Content fingerprint for a delivery owner's cache, including paired faces bytes.
```


Implementation alias: `lsd_runtime.scene_mesh_resources.mesh_resources_fingerprint`.

## `lsdtools.runtime.mint_oid`

Kind: function. Source: `services/runtime/src/lsd_runtime/identity.py:39`.

```python
mint_oid(name: Optional[Any], index: int) -> str
```


```python
index: int
name: Optional[Any]
```


Source docstring:

```text
The authored key when the table gave none: the name when present, else ``object_<row>``.
```


Implementation alias: `lsd_runtime.identity.mint_oid`.

## `lsdtools.runtime.object_eid`

Kind: function. Source: `services/runtime/src/lsd_runtime/identity.py:34`.

```python
object_eid(scene_id: str, oid: str) -> int
```


```python
oid: str
scene_id: str
```


Source docstring:

```text
The identity of runtime object ``oid`` of scene ``scene_id``.
```


Implementation alias: `lsd_runtime.identity.object_eid`.

## `lsdtools.runtime.object_feature_reference`

Kind: function. Source: `services/runtime/src/lsd_runtime/navigation.py:23`.

```python
object_feature_reference() -> dict[str, Any]
```


Source docstring:

```text
The detached feature-reference descriptor for runtime objects.
```


Implementation alias: `lsd_runtime.navigation.object_feature_reference`.

## `lsdtools.runtime.register_participant`

Kind: function. Source: `services/runtime/src/lsd_runtime/systems/registry.py:123`.

```python
register_participant(kind: str, ports: Mapping[str, str], *, factory: Optional[Factory]=None, description: str='', rank: int=DEFAULT_RANK) -> None
```


```python
description: str
factory: Optional[Factory]
kind: str
ports: Mapping[str, str]
rank: int
```


Source docstring:

```text
Register (or re-register) the participant called ``kind``.

``ports`` are the pipeline outputs a member entity of this kind declares, ``{port: kind}`` in
declaration order (a ``kind`` is what the host reads from the port: a ``table``, a ``path``
or a ``trip``). A ``factory`` makes the participant a simulation system; a system with no
ports has no member entity and is offered every composition (a probe, a host-owned system).
``rank`` orders the systems (lower binds first; registration order within a rank).
```


Implementation alias: `lsd_runtime.systems.registry.register_participant`.

## `lsdtools.runtime.register_system`

Kind: function. Source: `services/runtime/src/lsd_runtime/systems/registry.py:166`.

```python
register_system(name: str, factory: Factory, *, port: Optional[str]=None, port_kind: str='table', ports: Optional[Mapping[str, str]]=None, description: str='', rank: int=DEFAULT_RANK) -> None
```


```python
description: str
factory: Factory
name: str
port: Optional[str]
port_kind: str
ports: Optional[Mapping[str, str]]
rank: int
```


Source docstring:

```text
Register the simulation system called ``name``: a participant with a factory.

Declare the ports its members' tables travel on as ``ports`` (``{port: kind}``, ordered:
the first names the role) or, for one port, as the ``port`` / ``port_kind`` shorthand.
``rank`` is where its systems bind among the others (physics 100, cameras 200, animation 300,
kernels 400, audio 800, calibration 900; ``DEFAULT_RANK`` otherwise).
```


Implementation alias: `lsd_runtime.systems.registry.register_system`.

## `lsdtools.runtime.scene_id_for`

Kind: function. Source: `services/runtime/src/lsd_runtime/identity.py:45`.

```python
scene_id_for(entity_id: Optional[str], explicit: Optional[str]=None) -> str
```


```python
entity_id: Optional[str]
explicit: Optional[str]
```


Source docstring:

```text
The scene id: the explicit parameter when set, else derived from the owning entity id.
```


Implementation alias: `lsd_runtime.identity.scene_id_for`.

## `lsdtools.runtime.scene_layer_payload`

Kind: function. Source: `services/runtime/src/lsd_runtime/scene_build.py:251`.

```python
scene_layer_payload(authored: Any, objects: pa.Table, scene: Optional[pa.Table]=None, *, base_dir=None) -> LayerPayload
```


```python
authored: Any
base_dir: (unannotated)
objects: pa.Table
scene: Optional[pa.Table]
```


Source docstring:

```text
The ``runtime_objects`` viewer layer: the authored table (the edit target, passed as the
loader's own artifact so an edit rewrites what the scene is built from) beside the built objects.
```


Implementation alias: `lsd_runtime.scene_build.scene_layer_payload`.

## `lsdtools.runtime.stable_eid`

Kind: function. Source: `services/runtime/src/lsd_runtime/identity.py:27`.

```python
stable_eid(owner: str, archetype: str, oid: str) -> int
```


```python
archetype: str
oid: str
owner: str
```


Source docstring:

```text
A deterministic 63-bit id for one row; never zero, never negative, never colliding in practice.
```


Implementation alias: `lsd_runtime.identity.stable_eid`.

## `lsdtools.runtime.unregister_system`

Kind: function. Source: `services/runtime/src/lsd_runtime/systems/registry.py:198`.

```python
unregister_system(kind: str) -> None
```


```python
kind: str
```


Implementation alias: `lsd_runtime.systems.registry.unregister_participant`.

## `lsdtools.runtime.up_axis_defaults`

Kind: function. Source: `services/runtime/src/lsd_runtime/core_tables.py:119`.

```python
up_axis_defaults(up_axis: str) -> dict
```


```python
up_axis: str
```


Source docstring:

```text
The ``up`` vector a scene with this up axis defaults to.
```


Implementation alias: `lsd_runtime.core_tables.up_axis_defaults`.

## `lsdtools.runtime.up_axis_of`

Kind: function. Source: `services/runtime/src/lsd_runtime/scene_build.py:142`.

```python
up_axis_of(scene: Optional[pa.Table], default: str='z') -> str
```


```python
default: str
scene: Optional[pa.Table]
```


Source docstring:

```text
The up axis a built scene table declares (``default`` without one).
```


Implementation alias: `lsd_runtime.scene_build.up_axis_of`.