skills/plugins/document-navigator/docs/gaming/games/ecs/README.md

@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

License

MIT © Suaveplan Team