Creates a new ECSpresso instance.
Default constructor
The current change detection threshold. During system execution, this is the system's last-seen sequence. Between updates, this is the global sequence after command buffer playback. Manual change detection should compare: getChangeSeq(...) > changeThreshold
Command buffer for queuing deferred structural changes. Commands are executed automatically at the end of each update() cycle.
The current tick number, incremented at the end of each update()
The configured fixed timestep interval in seconds.
Get all installed plugin IDs
The interpolation alpha between fixed update steps. Ranges from 0 to <1, representing how far into the next fixed step the current frame is. Use in the render phase for smooth visual interpolation.
Add multiple components to an entity at once.
Add a reactive query that triggers callbacks when entities enter/exit the query match.
Unique name for the query
Query definition with with/without arrays and onEnter/onExit callbacks
Add a resource to the ECS instance.
{ factory, dependsOn?, onDispose? } → factory with dependencies/disposaldirectValue(val) → stores the value as-is (use to store functions/classes without invoking them)Adds a system directly to this ECSpresso instance. The system is registered when initialize() or update() is next called.
Unique name to identify the system
A SystemBuilder instance for method chaining
Disable a system group. Systems in this group will be skipped during update().
The name of the group to disable
Dispose a single resource, calling its onDispose callback if defined
The resource key to dispose
True if the resource existed and was disposed, false if it didn't exist
Dispose all initialized resources in reverse dependency order. Resources that depend on others are disposed first. Calls each resource's onDispose callback if defined.
Toggle diagnostics timing collection. When enabled, system and phase timings are recorded each frame. When disabled, timing maps are cleared and no overhead is incurred.
Enable a system group. Systems in this group will run during update().
The name of the group to enable
Traverse the hierarchy in parent-first (breadth-first) order. Parents are guaranteed to be visited before their children.
Function called for each entity with (entityId, parentId, depth)
Optionaloptions: HierarchyIteratorOptionsOptional traversal options (roots to filter to specific subtrees)
Get all ancestors of an entity in order [parent, grandparent, ...]
The entity ID to get ancestors of
Readonly array of ancestor entity IDs
Get a handle to an asset with status information
Get a child at a specific index
The parent entity ID
The index of the child
The child entity ID, or null if index is out of bounds
Get the index of a child within its parent's children list
The parent entity ID
The child entity ID to find
The index of the child, or -1 if not found
Get all children of an entity in insertion order
The parent entity ID
Readonly array of child entity IDs
Get the current screen name
Get all descendants of an entity in depth-first order
The entity ID to get descendants of
Readonly array of descendant entity IDs
Get all entities with specific components
OptionalchangedComponents: readonly (keyof Cfg["components"])[]OptionalparentHas: readonly (keyof Cfg["components"])[]Get the parent of an entity
The entity ID to get the parent of
The parent entity ID, or null if no parent
Get all resource keys that are currently registered
Array of resource keys
Get the root ancestor of an entity (topmost parent), or self if no parent
The entity ID to get the root of
The root entity ID
Get all root entities (entities that have children but no parent)
Readonly array of root entity IDs
Get the current screen config (immutable), narrowed to a specific screen. Throws if the current screen doesn't match.
Get the current screen config (immutable). Returns a union of all possible config types.
Get the screen stack depth
Get the current screen state (mutable), narrowed to a specific screen. Throws if the current screen doesn't match.
Get the current screen state (mutable). Returns a union of all possible state types.
Get siblings of an entity (other children of the same parent)
The entity ID to get siblings of
Readonly array of sibling entity IDs
Get the single entity matching a query. Throws if zero or more than one match.
Components the entity must have
Components the entity must not have
The single matching entity
Get all system labels that belong to a specific group.
The name of the group
Array of system labels in the group
Check if an entity has a component
Check if a resource exists
Generator-based hierarchy traversal in parent-first (breadth-first) order. Supports early termination via break.
Optionaloptions: HierarchyIteratorOptionsOptional traversal options (roots to filter to specific subtrees)
Initialize all resources and systems This method:
This is useful for game startup to ensure all resources are ready and systems are properly initialized before the game loop begins.
Promise that resolves when everything is initialized
Initialize specific resources or all resources that were added as factory functions but haven't been initialized yet. This is useful when you need to ensure resources are ready before proceeding.
Optional array of resource keys to initialize. If not provided, all pending resources will be initialized.
Promise that resolves when the specified resources are initialized
Install a plugin into this ECSpresso instance. Deduplicates by plugin ID. Composite plugins call this in their install function.
Check if an entity is an ancestor of another entity
The potential ancestor ID
The potential descendant ID
true if entityId is an ancestor of descendantId
Check if an asset is loaded
Check if an entity is a descendant of another entity
The potential descendant ID
The potential ancestor ID
true if entityId is a descendant of ancestorId
Check if a screen is active (current or in stack)
Check if a system group is enabled.
The name of the group to check
true if the group is enabled (or doesn't exist), false if disabled
Mark a component as changed on an entity. Each call increments a global monotonic sequence; systems with changed queries will see the mark exactly once (on their next execution).
The entity ID
The component that was changed
Unsubscribe from an event by callback reference (convenience wrapper for eventBus.unsubscribe)
true if the callback was found and removed, false otherwise
Register a callback when a specific component is added to any entity
Unsubscribe function to remove the callback
Register a callback when a specific component is removed from any entity
Unsubscribe function to remove the callback
Subscribe to changes for a specific resource key.
Unsubscribe function
Create a plugin factory from the built world's types. Returns a definePlugin equivalent with no manual type parameters.
Pop the current screen and return to the previous one
Push a screen onto the stack (overlay)
Register a dispose callback for a component type. Called when a component is removed (explicit removal, entity destruction, or replacement). Later registrations replace earlier ones for the same component type.
Register a required component relationship.
When an entity gains trigger, the required component is auto-added
(using factory for the default value) if not already present.
Enforced at insertion time (spawn/addComponent) only — removal is unrestricted.
Remove a component from an entity. Triggers component-removed and dispose callbacks.
The entity ID
The component to remove
Remove an entity (and optionally its descendants)
Entity ID to remove
Optionaloptions: RemoveEntityOptionsOptions for removal (cascade: true by default)
true if entity was removed
Remove the parent relationship for an entity (orphan it)
The entity ID to orphan
true if a parent was removed, false if entity had no parent
Remove a reactive query by name.
Name of the query to remove
true if the query existed and was removed, false otherwise
Remove a resource from the ECS instance (without calling onDispose)
The resource key to remove
True if the resource was removed, false if it didn't exist
Remove a system by its label Calls the system's onDetach method with this ECSpresso instance if defined
The unique label of the system to remove
true if the system was found and removed, false otherwise
Check if a resource needs initialization (was added as a factory function)
The resource key to check
True if the resource needs initialization
Set the parent of an entity
The entity ID to set as a child
The entity ID to set as the parent
Transition to a new screen, clearing the stack
Create an entity and add components to it in one call
The created entity with all components added
Create an entity as a child of another entity with initial components
The created child entity
Try to get a resource by key. Returns undefined if the resource is not found.
Inspired by Bevy's World::get_resource::<T>() which returns Option<&T>.
Two overloads:
ResourceTypesTry to get a resource by key. Returns undefined if the resource is not found.
Inspired by Bevy's World::get_resource::<T>() which returns Option<&T>.
Two overloads:
ResourceTypesGet the current screen config narrowed to a specific screen, or undefined if not on that screen.
Get the current screen config or undefined. Returns a union of all possible config types, or undefined.
Get the current screen state narrowed to a specific screen, or undefined if not on that screen.
Get the current screen state or undefined. Returns a union of all possible state types, or undefined.
Get the single entity matching a query, or undefined if none match. Throws if more than one entity matches.
Components the entity must have
Components the entity must not have
The single matching entity, or undefined if none match
Update all systems across execution phases. Phases run in order: preUpdate -> fixedUpdate -> update -> postUpdate -> render. The fixedUpdate phase uses a time accumulator for deterministic fixed-timestep simulation.
Time elapsed since the last update (in seconds)
Update the current screen state, narrowed to a specific screen. Throws if the current screen doesn't match.
Update the current screen state.
Move a system to a different execution phase at runtime.
The unique label of the system to move
The target phase
true if the system was found and updated, false otherwise
Update the priority of a system
The unique label of the system to update
The new priority value (higher values execute first)
true if the system was found and updated, false otherwise
StaticcreateCreates a new ECSpresso builder for type-safe plugin installation.
Types are inferred from the builder chain — use .withPlugin(),
.withComponentTypes<T>(), .withEventTypes<T>(), and .withResource()
to accumulate types without manual aggregate interfaces.
A builder instance for fluent method chaining
ECSpresso is the central ECS framework class that connects all features. It handles creation and management of entities, components, and systems, and provides lifecycle hooks.