@suaveplan/ecs - Archetype-based Entity Component System with Uint32 bitset queries, phase-ordered system scheduler, entity-ID recycling, Zod-validated component schemas, structured errors, and OpenTelemetry instrumentation

Archetype-based Entity Component System with Uint32-backed bitset queries, phase-ordered system scheduling, entity-ID recycling, Zod-validated component schemas, structured errors, and OpenTelemetry instrumentation. Universal — runs identically in Bun, Node, and the browser.

Documentation tree

archetype — An Archetype represents the unique combination of component types shared by a group of entities. All entities with th…
- archetype — An Archetype represents the unique combination of component types shared by a group of entities. All entities with th…
bitset — BitSet is the foundational mask primitive used by archetypes, queries, and the component registry inside `@suaveplan/…
- bitset — BitSet is the foundational mask primitive used by archetypes, queries, and the component registry inside `@suaveplan/…
component-registry — ComponentRegistry translates ComponentSchema references into stable integer IDs. These IDs are used as bit position…
- component-registry — ComponentRegistry translates ComponentSchema references into stable integer IDs. These IDs are used as bit position…
entity-pool — EntityPool is the entity-ID allocator. It hands out positive integer IDs on allocate(), recycles freed IDs on `free…
- entity-pool — EntityPool is the entity-ID allocator. It hands out positive integer IDs on allocate(), recycles freed IDs on `free…
errors — EcsError is the typed error class for every failure mode raised by @suaveplan/ecs. It extends SuaveplanError from…
- ecs-error — EcsError is the typed error class for every failure mode raised by @suaveplan/ecs. It extends SuaveplanError from…
observability — This module owns the OpenTelemetry instruments used by @suaveplan/ecs. There are two metrics — `ecs.entity.lifecycle_…
- otel — This module owns the OpenTelemetry instruments used by @suaveplan/ecs. There are two metrics — `ecs.entity.lifecycle_…
query — Query compiles a declarative QueryDescriptor (include / optional exclude schemas) into bitset masks and evaluat…
- query — Query compiles a declarative QueryDescriptor (include / optional exclude schemas) into bitset masks and evaluat…
schema — defineComponent is the canonical factory for ComponentSchema objects. It produces a deep-frozen descriptor pairing…
- schema — defineComponent is the canonical factory for ComponentSchema objects. It produces a deep-frozen descriptor pairing…
system — A system is the unit of behaviour in an ECS — a function that runs over every entity matching a query and mutates com…
- system — A system is the unit of behaviour in an ECS — a function that runs over every entity matching a query and mutates com…
world — World is the central container for an ECS instance. It owns the component registry, entity pool, archetype graph, que…
- world — World is the central container for an ECS instance. It owns the component registry, entity pool, archetype graph, que…

Install

bun add @suaveplan/ecs

Quick start

import { createWorld, defineComponent, defineSystem } from "@suaveplan/ecs";

const Position = defineComponent("Position", { x: 0, y: 0 });
const Velocity = defineComponent("Velocity", { dx: 1, dy: 0 });

const world = createWorld();
world.addSystem(defineSystem({
    name: "physics",
    query: { include: [Position, Velocity] },
    execute: ({ entities, world, dt }) => {
        for (const entity of entities) {
            const p = world.getComponent(entity, Position)!;
            const v = world.getComponent(entity, Velocity)!;
            world.setComponent(entity, Position, {
                x: p.x + v.dx * dt,
                y: p.y + v.dy * dt,
            });
        }
    },
}));

const player = world.spawn();
world.addComponent(player, Position);
world.addComponent(player, Velocity);
world.execute(1 / 60);

Modules

bitset/ — Uint32Array-backed bitset primitive.
component-registry/ — stable-ID registry for component schemas.
entity-pool/ — entity-ID allocator with recycling and generations.
archetype/ — column-oriented storage with O(1) swap-remove.
query/ — bitset-driven query compiler.
system/ — phase-priority system scheduler.
schema/ — defineComponent factory with optional Zod validator.
world/ — central container; spawn/despawn, components, queries, systems, snapshot/restore.
errors/ — EcsError and the ECS_CODES registry.
observability/ — OTel counters and histograms.
types/ — every public type alias and interface.

Quality gates

bunx turbo lint typecheck test --filter=@suaveplan/ecs
bunx turbo test:coverage --filter=@suaveplan/ecs   # 100% statement+branch+function+line
bun run docs:check --filter=@suaveplan/ecs

6.0 KiB Raw Blame History