92 lines
6.0 KiB
Markdown
92 lines
6.0 KiB
Markdown
# @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
|
|
|