Class SystemBuilder<Cfg, Queries, Label, SysGroups, ResourceKeys, Singletons>

Add a query definition to the system.

When mutates is declared, every iterated entity is automatically markChanged'd for each listed component after the system's process() returns. Components in with but absent from mutates are narrowed to Readonly<T> in the iteration entity type.

Add a singleton query — a named query that yields a single FilteredEntity | undefined instead of an array. Surfaces on the process context's queries object alongside regular queries.

When multiple entities match, the first is returned (no error). Use the instance-level getSingleton / tryGetSingleton helpers on ECSpresso if you need strictness guarantees.

When mutates is declared, the resolved entity is automatically markChanged'd for each listed component after the system's process() returns. Components in with but absent from mutates are narrowed to Readonly<T> in the iteration entity type.

Exclude this system from running in specified screens. System will be skipped during update() when the current screen is in this list.

Add this system to a group. Systems can belong to multiple groups. When any group a system belongs to is disabled, the system will be skipped.

Set the execution phase for this system. Systems are grouped by phase and executed in order: preUpdate -> fixedUpdate -> update -> postUpdate -> render

Restrict this system to only run in specified screens. System will be skipped during update() when the current screen is not in this list.

Require specific assets to be loaded for this system to run. System will be skipped during update() if any required asset is not loaded.

Allow this system to run even when all queries return zero entities. By default, systems with queries are skipped when no entities match.

Set event handlers for the system These handlers will be automatically subscribed when the system is attached

Set the onDetach lifecycle hook Called when the system is removed from the ECS

Register a callback that fires once per entity the first time it appears in a query's results. Fires before process. Automatic cleanup when entity leaves the query so re-entry fires the callback again.

Set the onInitialize lifecycle hook.

Fires exactly once per system. For systems added before initialize(), the hook is awaited inside initialize() itself. For systems added after initialize() has returned, the hook fires on registration (at the next update()'s finalize step) — async hooks run fire-and-forget, so don't rely on completion ordering against the first process call.

Set the priority of this system. Systems with higher priority values execute before those with lower values. Systems with the same priority execute in the order they were registered.

Set the system's process function that runs each update. The callback receives a single context object { queries, dt, ecs, resources? }. The context is pre-allocated per system and reused every frame.

Inline-query terminator: define a single query and a per-entity callback in one call. Collapses the common addQuery + setProcess + for-loop pattern into a single chain step.

Only valid on a builder with no prior queries or process function — TypeScript narrows this to never otherwise, and a runtime guard throws for untyped callers. For multi-query systems use addQuery + setProcess.

When mutates is declared, the callback may return false to skip the auto-mark for that specific entity. Returning true, undefined, or any other value stamps all components listed in mutates. Components in with but absent from mutates are narrowed to Readonly<T> on the per-entity iteration type.

Declare resource dependencies for this system. Resources are resolved once (on first process call) and the same object is reused every frame. The resolved resources are available as ctx.resources in setProcess.