Key APIs

No description provided yet.

Open System.System in the docs

Builds one schedule from systems, marker steps, and nested schedules.

Nested schedules are flattened in place, so reusable pieces compose into one ordered step list. The schema is inferred from the first system or nested schedule; Game.Schedule(...) supplies it from the bound game instead, so marker-only schedules are valid there.

Open Schedule.Schedule in the docs

Declares read-only access to a component in a query selection.

A required read slot is both a matching requirement and a typing decision: the entity must have that component, and the resulting slot becomes a ReadCell. Use this for data the system needs to inspect but must not mutate.

Open Query.read in the docs

Creates an explicit query specification.

Use this inside system specs instead of relying on callback parameter inference. The resulting value drives both runtime execution and the derived query result type.

A query spec is purely declarative. It does not access the world by itself; systems receive QueryHandles derived from the spec. In practice this is where you encode the exact shape of one gameplay iteration pass.

Open Query.Query in the docs

Creates a resource-write declaration for a system spec.

Use this when the system owns mutation of one world-level singleton, such as score, UI summaries, accumulated damage, or frame-local caches. Declaring it here makes that authority visible in the system contract before the body is read.

Open System.writeResource in the docs

Defines a component descriptor.

Use this when declaring per-entity data that should participate in queries and typed entity proofs.

Components are the only descriptor kind that can be queried directly with Game.Query.read(...), write(...), or optional(...).

Open Descriptor.Component in the docs

Applies every command queued so far, including commands queued by earlier schedule runs.

Open Schedule.applyDeferred in the docs

Defines a resource descriptor.

Resources represent unique world-level values accessed through explicit system specs.

Use resources for singleton world data such as counters, configuration, global timers, camera summaries, or transient per-frame aggregates that should not be duplicated across entities.

Open Descriptor.Resource in the docs

Starts a staged entity from component entries.

Drafts are plain values: build them anywhere (including small factories), then queue them with commands.spawn(...). Entries may be [Descriptor, value] pairs or results from entryRaw(...); see insert(...) for how failures are reported.

Open Command.spawn in the docs

Declares writable access to a component in a query selection.

Use this when the system is responsible for mutating component state in place. A write slot both requires component presence and exposes the slot as a WriteCell, so mutation capability stays visible in the query spec rather than appearing ad hoc in the loop body.

Open Query.write in the docs

Creates a schema fragment.

Fragments are the composition unit for game modules: each says "this subsystem contributes these components/resources/events/relations" and nothing more. Binding and runtime assembly happen later.

Open Schema.fragment in the docs

Creates a runtime for a fully built schema and a set of external services.

Resources owned by constructed descriptors take raw input and are validated here; when any are provided the runtime comes back as a Result. Otherwise the runtime is returned directly.

The runtime does not own the outer frame loop. It only owns ECS state plus the host-provided services that systems are allowed to depend on.

Open Runtime.make in the docs

Creates a resource-read declaration for a system spec.

Use this for world-level singleton data the system needs to observe but must not mutate, such as delta time, score snapshots, configuration, or aggregated frame input. The resulting context slot is a read-only ReadCell.

Open System.readResource in the docs

Composes one or more fragments and returns one bound Game surface.

Everything created from the returned object carries the same hidden root brand, so systems, schedules, and runtimes from different bound schemas cannot be connected accidentally.

Open Schema.bind in the docs

Creates the successful branch of a Result.

Open Result.success in the docs

Creates the failed branch of a Result.

Open Result.failure in the docs

Builds the descriptor-backed runtime service environment.

This is the runtime-side counterpart to Game.System.service(...). Use it to assemble the host implementations the game exposes to systems, such as clocks, random generators, render bridges, audio sinks, or network clients.

The helper keeps the runtime map keyed by service descriptors instead of ad hoc strings, so the provision site cannot drift from the declaration site.

Open Runtime.services in the docs

Creates an event-write declaration for a system spec.

Emitted events are published when the system completes successfully; a failed run publishes nothing. Readers later in the same schedule see them, and so do readers that run in a later tick.

If the payload needs to name an entity for later work, emit a durable Game.Entity.handle(...) (optionally with an intent component) and let the later reader re-resolve it through lookup.getHandle(...).

Open System.writeEvent in the docs

Creates an event-read declaration for a system spec.

Each run of the reading system sees the events published since its own previous completed run, once, in emission order: events from earlier systems in the same schedule, and events emitted after it ran last time.

Events are kept until every system that reads them has run, so a reader in a schedule ticked less often than the emitter's (a fixed update below the render rate) still receives all of them. Events nobody has read yet are kept for the current and previous runtime.tick(...) call; a reader's first run sees whatever is still kept. A system skipped by its run conditions discards the events published meanwhile. Each stream is capped at Runtime.streamCapacity entries; a reader that missed dropped ones sees lagged() === true.

This is the usual second half of a cross-system flow: one system emits an event, and a later system reads it and re-validates any handles or lookups it needs.

Open System.readEvent in the docs

Creates a condition that only passes in one exact machine state.

Use this to gate systems or schedule entries by the committed gameplay phase. If you need this kind of gating, the value should generally be modeled as a finite-state machine rather than a plain state descriptor.

Open Machine.inState in the docs

Declares maybe-present read-only access to a component in a query specification.

optional(...) is for enrichment, not matching. It keeps the entity set broad while letting one system opportunistically read extra data when present. The returned cell forces an explicit present check before use, so the possibility of absence remains visible in the type surface.

Open Query.optional in the docs

Declares that a system needs a service from the external runtime environment.

Use this for host capabilities that should not live in ECS world storage: clocks, random generators, render bridges, audio sinks, persistence APIs, or network clients. The matching implementation must be supplied when the runtime is created with Game.Runtime.services(...).

Open System.service in the docs

Creates one service provision for Runtime.services(...).

Use this at the runtime assembly boundary to pair a service descriptor with its concrete host implementation. Passing the descriptor first keeps the implementation object contextually typed and makes the dependency relation obvious in docs and code review.

Open Runtime.service in the docs

Defines a service descriptor.

Services are the dependency-injection side of the system model, similar to Effect environment entries.

Use them for capabilities owned by the host instead of the ECS world: clocks, random sources, render/audio bridges, storage, or network clients. Systems request them explicitly with Game.System.service(...), and the runtime provides them through Game.Runtime.services(...).

Open Descriptor.Service in the docs

Converts a current entity into a durable handle for storage.

The handle is storage-safe, not a proof of liveness: resolve it later with lookup.getHandle(...), which fails explicitly when the entity is gone.

Pass an intent component when later code assumes a role such as "player" or "damage source". An intent does not prove the component is still present; it forces resolution through a query that proves it.

Open Entity.handle in the docs

Defines a component descriptor that also knows how to validate raw values.

Use this when the component should never exist in the world in an unvalidated shape, for example vectors, sizes, collider bounds, or other branded domain values.

Open Descriptor.ConstructedComponent in the docs

No description provided yet.

Open Schedule.applyStateTransitions in the docs

Declares queued write access to the next value of a finite-state machine.

This is the system-side request channel for a future phase change. It does not immediately switch the committed state; the queued value is applied only at an explicit Game.Schedule.applyStateTransitions(...) boundary.

Use this instead of writing a plain resource when the transition timing itself is part of the gameplay model, such as restarting a round, leaving a menu, or entering a results screen after reset/setup schedules run.

Open System.nextState in the docs

Creates a schema-bound finite-state machine definition.

This is the intended default for gameplay phases and other discrete modes where the transition boundary itself matters.

Prefer a machine over a plain resource when code depends on:

• queued nextState(...) writes
• explicit applyStateTransitions(...)
• inState(...) gating
• transition events or enter/exit schedules

Open Machine.StateMachine in the docs

Creates one machine initialization provision.

This is the machine-side equivalent of Runtime.service(...): it pairs one machine definition with the committed initial value the runtime should start from before any transition schedule runs.

Open Runtime.machine in the docs

Defines an event descriptor.

Use event descriptors to model append-only messages flowing between systems without exposing untyped channels.

Events are per-reader streams, like change detection: each reading system sees the events published since its own previous run, once, in emission order. A system's events are published when it completes successfully, so later systems in the same schedule see them, and a failed system publishes nothing. Events are kept until every system that reads them has run (see Game.System.readEvent).

Open Descriptor.Event in the docs

Builds the machine initialization environment from machine definitions.

Use this when gameplay phases need a known committed starting state before any schedule runs, for example "Boot", "Menu", or "Playing".

Open Runtime.machines in the docs

Creates one explicit root token for schema-bound long-lived references.

Root tokens exist before schema construction so durable entity handles can be stored in descriptor payload types without widening to Schema.Any.

Open Schema.defineRoot in the docs

Builds one schedule whose systems run only while every condition passes, in addition to their own when conditions: the group equivalent of a system's when, for gating many systems on one mode (playing, paused, a hit-stop) without repeating it on each.

Conditions gate every system in entries, nested schedules included. Marker steps (applyDeferred, applyStateTransitions) in the group still run. A gated system is the same system as far as the runtime is concerned: it shares change detection and event cursors with the original and with any other gated copy, so using one system in two groups of one schedule is a duplicate like any other.

Open Schedule.when in the docs

Stages one outgoing relation edge on an entity draft.

Drafts stay pure: this only records intent so the runtime can attempt to attach the relation when the spawn command is applied.

Open Command.relate in the docs

Validates one reusable authored value through an existing constructor.

Use this for one named authored constant that should cross a constructor boundary now and remain in carried form afterward.

Open Definition.entry in the docs

No description provided yet.

Open Schedule.transitions in the docs

Declares read access to the current committed value of a finite-state machine.

Use this when gameplay logic needs to branch on the current committed phase, but should not see queued next-state writes early. Machines are the intended default for menus, rounds, encounters, pause flows, and other discrete modes whose transition boundary matters.

Open System.machine in the docs

Creates a typed component entry.

Open Command.entry in the docs

Lifts an already validated value into an entry result, keeping the failure visible to spawn(...) / insert(...).

Open Command.entryResult in the docs

Defines a resource descriptor that also knows how to validate raw values.

Open Descriptor.ConstructedResource in the docs

Validates raw input through a constructed descriptor and returns an entry result.

Open Command.entryRaw in the docs

Defines a state component: its value is one of states, validated (so snapshots reject unknown states), and it behaves like any other component (storage, change detection, rollback, traces).

With transitions, its write cell gains transition(from, to): the pair is checked against the graph at compile time, and at runtime the move happens only if the current state is still from, otherwise it returns a StateMismatch failure. Transitions are ordinary component writes: immediate, visible to later systems, rolled back with a failed system.

Open Descriptor.State in the docs

Defines a marker component: no data, only presence ([Player, {}]).

Tags validate on load like any constructed component, so they never block snapshots.

Open Descriptor.Tag in the docs

Declares a filter that matches components added or written since the reading system's previous run.

Any write through a write cell counts, even when the value is equal to the previous one. Writes from a system whose run failed are rolled back and do not count.

Open Query.changed in the docs

Declares read access to relation-mutation failure records.

Open System.readRelationFailures in the docs

Validates a named record of reusable authored values at once.

Successful entries are returned under the same keys. Failed entries remain keyed so authored-data setup can report exactly which constant was invalid.

Use this when one content bundle or level definition should either validate as a whole or report a structured set of authoring failures.

Open Definition.all in the docs

Creates an opaque entity id from a runtime integer id.

This is a low-level constructor used by the runtime and command system. The value it stores is the stable per-runtime numeric identity exposed on EntityId.

Open Entity.makeEntityId in the docs

Declares read access to despawned-entity lifecycle records.

Each run returns the entities despawned since the system's previous run. Records are retained like readRemoved records. Use it when host-owned state must be destroyed even if no single removed component is the canonical trigger. readRemoved is often used alongside this in authoritative host mirrors.

Open System.readDespawned in the docs

Defines a resource descriptor that snapshots skip. Restoring keeps its current value.

Open Descriptor.TransientResource in the docs

Defines the canonical parent/children relationship pair.

The returned relation is the source-of-truth edge component, while related is the reverse collection maintained by the runtime.

Use hierarchy when the relationship must support ordered children, ancestor/descendant traversal, and linked recursive despawn.

Open Descriptor.Hierarchy in the docs

Aggregates several independent results into one explicit result.

Tuple input preserves tuple ordering in both success and failure shapes. Record input preserves the original keys.

The first failure stays explicit in the returned error structure rather than throwing or silently dropping invalid entries.

Open Result.all in the docs

Folds one Result into a plain value.

Use this when you are leaving the Result shape and want one explicit place to handle both branches.

Open Result.match in the docs

Declares read access to removed-component lifecycle records.

Each run returns the entities whose component was removed since the system's previous run (removals are applied when commands are). Records are kept until every system that reads them has run, so a reader in a schedule ticked less often than the one that removes (rendering after several fixed updates) still sees every removal. A system skipped by its run conditions keeps its position, like added/changed, and sees the removals when it runs again. Each log is capped at Runtime.streamCapacity entries; drops show up as missed reads in the debug trace. Systems usually pair this with host cleanup such as removing renderer-owned nodes. readDespawned complements this for whole-entity teardown.

Open System.readRemoved in the docs

Declares a filter that matches components added since the reading system's previous run.

Change detection is per system: every system sees each addition exactly once, on its first run after the addition, independently of other systems. A system's first run sees every existing component as added. This is the usual entrypoint for incremental host sync, such as creating renderer nodes.

Open Query.added in the docs

Adapts a Standard Schema validator into a descriptor constructor, so any compliant validation library can guard constructed components and resources. Validation must be synchronous; a schema that returns a promise fails with an issue instead.

Open Descriptor.fromStandardSchema in the docs

Requires at least one child condition to pass.

Open Machine.or in the docs

Declares read access to committed transition events for one machine.

Transition events are published when a transition commits and read like normal events: each run sees those published since its previous run.

This is one of the clearest signs that the modeled value should be a machine rather than a plain state descriptor.

Open System.readTransitionEvent in the docs

Negates another condition.

Open Machine.not in the docs

Requires every child condition to pass.

Open Machine.and in the docs

Adds entries to a draft. Plain entries return the new draft; if any entry is a Result, the draft is returned as a Result whose error lists every entry's failure (or null).

Open Command.insert in the docs

Defines a component descriptor that snapshots skip.

Restored entities come back without it, so systems that need it rebuild it, for example from an added(...) query.

Open Descriptor.TransientComponent in the docs

Decodes a handle from untrusted data, such as a component value inside a snapshot. Use it in the constructor of a component or resource that stores handles, so restoring validates them like any other value.

A handle only names an entity; it never proves the entity exists. Resolving it with lookup.getHandle(...) stays the checked step, so any positive integer id decodes.

Open Entity.decodeHandle in the docs

Creates a typed entity draft from an id and a proof.

Open Entity.draft in the docs

Creates a condition that passes when the machine changed during the current schedule execution.

Open Machine.stateChanged in the docs

Defines a general relationship pair with direct edges and reverse lookups.

Use a general relation when you need direct source -> target edges plus reverse lookup, but not hierarchy-only behavior such as tree traversal or child reordering.

Open Descriptor.Relation in the docs

Creates a durable handle from a runtime entity id.

This is a low-level constructor used by the bound Game.Entity helpers and by runtime lookup resolution.

Open Entity.makeHandle in the docs

Merges two schema fragments into a larger closed schema.

Duplicate keys and descriptor names are rejected at the type level and at runtime.

Open Schema.merge in the docs