# @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.

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```bash
bun add @suaveplan/ecs
```

## Quick start

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

## Quality gates

```bash
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