ECS guide
Entity-component system
Create local schemas, query object-shaped components, and compose ordered systems without giving up caller ownership.
What is an ECS?
An entity-component system (ECS) organizes game state by separating identity, data, and behavior. An entity is a numeric ID, components are small pieces of data such as position or health, and systems are ordinary functions that query entities with the data they need and update them. This makes it easy to process many similar things—such as every projectile or enemy—without putting every behavior in one large game-object class.
For a broader introduction, read Entity-component system on Wikiwand.
Current performance
The current implementation is benchmarked against a shared CPU workload of 1,000,000 entities in Node.js and 100,000 entities in Chromium. It measures dense and sparse queries, structural remove/add operations, snapshot import/export, and teardown. These are workload timings, not a universal frame-rate promise.
Play ECS Arena
Play ECS Arena — a small WebGPU game that makes the ECS lifecycle visible.
Live example
Run a typed world
Create an entity to start the world
World snapshot
{
"format_version": 1,
"entity_policy": "monotonic",
"entities": [],
"components": {
"position": []
}
}What this demonstrates
Component tokens belong to a local schema, and each world owns its membership and component storage. Queries expose only the tokens they request. The example uses detached query snapshots for the reactive list and a caller-controlled update function for movement.
Public types
define_component<Value>()create_world(schema, options?)EntityPolicyandWorldOptionsWorld<Schema>Query<Schema, Included>QueryMatch<Schema, Included>WorldSnapshot<Schema>create_ecs_system_pipeline<Schema>()EcsSystem<Schema>,EcsSystemContext<Schema>, andEcsSystemPipeline<Schema>
Minimum viable example
// Import the world factory and component definition helper.
import { create_world, define_component } from "squander/ecs";
// Describe the data stored by each position component.
type Position = { x: number; y: number };
// Create a typed token that identifies the position component.
const position = define_component<Position>({ name: "position" });
// Create a world whose local schema contains the position token.
const world = create_world({ position });
// Allocate a cheap numeric entity ID.
const entity = world.create();
// Attach the initial position data to the entity.
world.add(entity, position, { x: 0, y: 0 });
// Require position before iterating matching entities.
world.query().with(position).each(({ read, write }) => {
// Read the current component value, then write the updated value.
const { y } = read(position);
write(position).x += y;
});
// Export a storage-independent snapshot of the world.
const snapshot = world.export();
// Restore the snapshot, including its entity IDs and component values.
world.import(snapshot);Caller-owned systems
Systems are ordinary application modules. The optional pipeline helper supplies stable order and one shared timing snapshot, while the caller still chooses when to run it. There is no ambient registration or hidden animation loop.
import { create_ecs_system_pipeline } from "squander/ecs";
const simulation = create_ecs_system_pipeline<typeof world.schema>([
{
update: ({ world: simulation_world, time }) => {
simulation_world.query().with(position).each(({ read, write }) => {
write(position).x += read(position).y * time.delta_seconds;
});
},
},
{
enabled: debug_enabled,
update: ({ world: simulation_world }) => draw_debug_data(simulation_world),
},
]);
// The caller owns the game update boundary.
simulation.run(world, time);Scope and limitations
The ECS uses object-shaped components and dense sparse-set columns today. Structural changes from a query match are deferred until
iteration finishes. Monotonic IDs are the default; generational IDs are available through { entity_policy: "generational" }. Snapshot values must be structured-cloneable. The ECS does not provide a scheduler or system registry. JSON and binary serialization,
migrations, typed columns, and archetype storage remain application or later optimization seams. The pipeline is optional and does not
replace scene lifecycle hooks.