@aura3d/ecs 1.0.6

package/src/CommandBuffer.ts

@@ -0,0 +1,97 @@
+import { ValidationError } from "@aura3d/core";
+import { type ComponentCtor } from "./Component.js";
+import { entityKey, type Entity } from "./Entity.js";
+import { type World } from "./World.js";
+
+export type EntityRef = Entity | { readonly tempId: number };
+
+type Command =
+  | { kind: "create"; tempId: number }
+  | { kind: "destroy"; entity: EntityRef }
+  | { kind: "add"; entity: EntityRef; ctor: ComponentCtor; component: object }
+  | { kind: "remove"; entity: EntityRef; ctor: ComponentCtor };
+
+export class CommandBuffer {
+  private nextTempId = 1;
+  private readonly commands: Command[] = [];
+
+  createEntity(): EntityRef {
+    const ref = { tempId: this.nextTempId };
+    this.nextTempId += 1;
+    this.commands.push({ kind: "create", tempId: ref.tempId });
+    return ref;
+  }
+
+  destroyEntity(entity: EntityRef): void {
+    this.commands.push({ kind: "destroy", entity });
+  }
+
+  add<T extends object>(entity: EntityRef, ctor: ComponentCtor<T>, component: T): void {
+    this.commands.push({ kind: "add", entity, ctor, component });
+  }
+
+  remove<T extends object>(entity: EntityRef, ctor: ComponentCtor<T>): void {
+    this.commands.push({ kind: "remove", entity, ctor });
+  }
+
+  flush(world: World): Entity[] {
+    validateCommands(world, this.commands);
+    const tempEntities = new Map<number, Entity>();
+    const created: Entity[] = [];
+    const commands = this.commands.splice(0, this.commands.length);
+    for (const command of commands) {
+      if (command.kind === "create") {
+        const entity = world.createEntity();
+        tempEntities.set(command.tempId, entity);
+        created.push(entity);
+        continue;
+      }
+      const entity = resolve(command.entity, tempEntities);
+      if (command.kind === "destroy") world.destroyEntity(entity);
+      if (command.kind === "add") world.add(entity, command.ctor, command.component);
+      if (command.kind === "remove") world.remove(entity, command.ctor);
+    }
+    return created;
+  }
+}
+
+function validateCommands(world: World, commands: readonly Command[]): void {
+  const tempAlive = new Set<number>();
+  const deadEntities = new Set<string>();
+
+  for (const command of commands) {
+    if (command.kind === "create") {
+      tempAlive.add(command.tempId);
+      continue;
+    }
+
+    validateEntityRef(world, command.entity, tempAlive, deadEntities);
+    if (command.kind === "remove") world.registry.require(command.ctor);
+    if (command.kind === "destroy") {
+      if ("tempId" in command.entity) {
+        tempAlive.delete(command.entity.tempId);
+      } else {
+        deadEntities.add(entityKey(command.entity));
+      }
+    }
+  }
+}
+
+function validateEntityRef(world: World, ref: EntityRef, tempAlive: Set<number>, deadEntities: Set<string>): void {
+  if ("tempId" in ref) {
+    if (!tempAlive.has(ref.tempId)) throw new ValidationError("TEMP_ENTITY", `Temporary entity is not alive: ${ref.tempId}`);
+    return;
+  }
+
+  world.assertAlive(ref);
+  if (deadEntities.has(entityKey(ref))) throw new ValidationError("ENTITY_NOT_ALIVE", `Entity was already destroyed by this command buffer: ${entityKey(ref)}`);
+}
+
+function resolve(ref: EntityRef, tempEntities: Map<number, Entity>): Entity {
+  if ("tempId" in ref) {
+    const entity = tempEntities.get(ref.tempId);
+    if (!entity) throw new ValidationError("TEMP_ENTITY", `Temporary entity was not created: ${ref.tempId}`);
+    return entity;
+  }
+  return ref;
+}

package/src/Component.ts

@@ -0,0 +1,25 @@
+import { ValidationError } from "@aura3d/core";
+
+export interface ComponentCtor<T = object> {
+  readonly prototype: T;
+  readonly name: string;
+  readonly schema?: ComponentSchema;
+}
+
+export interface ComponentSchema {
+  readonly version: number;
+  serialize?(component: object): unknown;
+  deserialize?(data: unknown): object;
+}
+
+export interface ComponentType<T = object> {
+  readonly id: number;
+  readonly name: string;
+  readonly ctor: ComponentCtor<T>;
+  readonly schema: ComponentSchema;
+}
+
+export function componentName(ctor: ComponentCtor): string {
+  if (!ctor.name) throw new ValidationError("COMPONENT_NAME", "Component classes must have a stable name.");
+  return ctor.name;
+}

package/src/ComponentRegistry.ts

@@ -0,0 +1,38 @@
+import { ValidationError } from "@aura3d/core";
+import { componentName, type ComponentCtor, type ComponentSchema, type ComponentType } from "./Component.js";
+
+export class ComponentRegistry {
+  private nextId = 0;
+  private readonly byCtor = new Map<ComponentCtor, ComponentType>();
+  private readonly byName = new Map<string, ComponentType>();
+
+  register<T extends object>(ctor: ComponentCtor<T>, schema?: ComponentSchema): ComponentType<T> {
+    const name = componentName(ctor);
+    const existingByCtor = this.byCtor.get(ctor);
+    if (existingByCtor) return existingByCtor as ComponentType<T>;
+    if (this.byName.has(name)) throw new ValidationError("DUPLICATE_COMPONENT", `Duplicate component name: ${name}`);
+    const type: ComponentType<T> = { id: this.nextId, name, ctor, schema: schema ?? ctor.schema ?? { version: 1 } };
+    this.nextId += 1;
+    this.byCtor.set(ctor, type as ComponentType);
+    this.byName.set(name, type as ComponentType);
+    return type;
+  }
+
+  get<T extends object>(ctor: ComponentCtor<T>): ComponentType<T> | undefined {
+    return this.byCtor.get(ctor) as ComponentType<T> | undefined;
+  }
+
+  require<T extends object>(ctor: ComponentCtor<T>): ComponentType<T> {
+    const type = this.get(ctor);
+    if (!type) throw new ValidationError("UNREGISTERED_COMPONENT", `Component is not registered: ${componentName(ctor)}`);
+    return type;
+  }
+
+  getByName(name: string): ComponentType | undefined {
+    return this.byName.get(name);
+  }
+
+  list(): ComponentType[] {
+    return [...this.byCtor.values()].sort((a, b) => a.id - b.id);
+  }
+}

package/src/ComponentStore.ts

@@ -0,0 +1,72 @@
+import { Bitset } from "./Bitset.js";
+import { type ComponentCtor, type ComponentType } from "./Component.js";
+import { ComponentRegistry } from "./ComponentRegistry.js";
+import { type Entity } from "./Entity.js";
+import { SparseSet } from "./SparseSet.js";
+
+export class ComponentStore {
+  private readonly stores = new Map<number, SparseSet<object>>();
+  private readonly signatures = new Map<number, Bitset>();
+
+  constructor(private readonly registry: ComponentRegistry) {}
+
+  add<T extends object>(entity: Entity, ctor: ComponentCtor<T>, component: T): void {
+    const type = this.registry.require(ctor);
+    this.storeFor(type).add(entity, component);
+    this.signatureFor(entity).add(type.id);
+  }
+
+  remove<T extends object>(entity: Entity, ctor: ComponentCtor<T>): boolean {
+    const type = this.registry.require(ctor);
+    const removed = this.storeFor(type).delete(entity);
+    if (removed) this.signatureFor(entity).delete(type.id);
+    return removed;
+  }
+
+  get<T extends object>(entity: Entity, ctor: ComponentCtor<T>): T | undefined {
+    const type = this.registry.require(ctor);
+    return this.storeFor(type).get(entity) as T | undefined;
+  }
+
+  has<T extends object>(entity: Entity, ctor: ComponentCtor<T>): boolean {
+    const type = this.registry.require(ctor);
+    return this.storeFor(type).has(entity);
+  }
+
+  deleteEntity(entity: Entity): void {
+    for (const store of this.stores.values()) store.delete(entity);
+    this.signatures.delete(entity.id);
+  }
+
+  signature(entity: Entity): Bitset {
+    return this.signatures.get(entity.id)?.clone() ?? new Bitset();
+  }
+
+  entries<T extends object>(ctor: ComponentCtor<T>): [Entity, T][] {
+    const type = this.registry.require(ctor);
+    return this.storeFor(type).entries() as [Entity, T][];
+  }
+
+  entitiesWith<T extends object>(ctor: ComponentCtor<T>): Entity[] {
+    const type = this.registry.require(ctor);
+    return this.storeFor(type).entities();
+  }
+
+  private storeFor(type: ComponentType): SparseSet<object> {
+    let store = this.stores.get(type.id);
+    if (!store) {
+      store = new SparseSet<object>();
+      this.stores.set(type.id, store);
+    }
+    return store;
+  }
+
+  private signatureFor(entity: Entity): Bitset {
+    let signature = this.signatures.get(entity.id);
+    if (!signature) {
+      signature = new Bitset();
+      this.signatures.set(entity.id, signature);
+    }
+    return signature;
+  }
+}

package/src/ECSProfiler.ts

@@ -0,0 +1,19 @@
+import { type World } from "./World.js";
+
+export interface ECSProfileSnapshot {
+  entities: number;
+  components: { name: string; id: number; count: number }[];
+  version: number;
+}
+
+export function profileWorld(world: World): ECSProfileSnapshot {
+  return {
+    entities: world.entities.size,
+    components: world.registry.list().map((type) => ({
+      name: type.name,
+      id: type.id,
+      count: world.components.entries(type.ctor).length
+    })),
+    version: world.getVersion()
+  };
+}

package/src/ECSSerializer.ts

@@ -0,0 +1,45 @@
+import { ValidationError } from "@aura3d/core";
+import { type ComponentCtor } from "./Component.js";
+import { type Entity } from "./Entity.js";
+import { World } from "./World.js";
+
+export interface SerializedEntity {
+  id: number;
+  generation: number;
+  components: Record<string, unknown>;
+}
+
+export interface SerializedWorld {
+  version: 1;
+  entities: SerializedEntity[];
+}
+
+export function serializeWorld(world: World): SerializedWorld {
+  const entities: SerializedEntity[] = world.entities.entities().map((entity) => {
+    const components: Record<string, unknown> = {};
+    for (const type of world.registry.list()) {
+      const value = world.components.get(entity, type.ctor as ComponentCtor);
+      if (value) components[type.name] = type.schema.serialize ? type.schema.serialize(value) : structuredClone(value);
+    }
+    return { id: entity.id, generation: entity.generation, components };
+  });
+  return { version: 1, entities };
+}
+
+export function deserializeWorld(serialized: SerializedWorld, componentTypes: ComponentCtor[]): { world: World; remap: Map<string, Entity> } {
+  if (serialized.version !== 1) throw new ValidationError("ECS_VERSION", `Unsupported ECS version: ${serialized.version}`);
+  const world = new World();
+  for (const type of componentTypes) world.registerComponent(type);
+  const remap = new Map<string, Entity>();
+  for (const serializedEntity of serialized.entities) {
+    const entity = world.createEntity();
+    remap.set(`${serializedEntity.id}:${serializedEntity.generation}`, entity);
+    for (const [name, data] of Object.entries(serializedEntity.components)) {
+      const type = world.registry.getByName(name);
+      if (!type) throw new ValidationError("ECS_DESERIALIZE_COMPONENT", `Missing component type during ECS deserialize: ${name}`);
+      const component = type.schema.deserialize ? type.schema.deserialize(data) : data;
+      world.add(entity, type.ctor as ComponentCtor, component as object);
+    }
+  }
+  return { world, remap };
+}

package/src/Entity.ts

@@ -0,0 +1,19 @@
+import { ValidationError } from "@aura3d/core";
+
+export interface Entity {
+  readonly id: number;
+  readonly generation: number;
+}
+
+export function entityKey(entity: Entity): string {
+  return `${entity.id}:${entity.generation}`;
+}
+
+export function sameEntity(a: Entity, b: Entity): boolean {
+  return a.id === b.id && a.generation === b.generation;
+}
+
+export function assertEntity(entity: Entity): void {
+  if (!Number.isSafeInteger(entity.id) || entity.id < 0) throw new ValidationError("ENTITY_ID", "Entity id must be a non-negative safe integer.");
+  if (!Number.isSafeInteger(entity.generation) || entity.generation < 0) throw new ValidationError("ENTITY_GENERATION", "Entity generation must be a non-negative safe integer.");
+}

package/src/EntityManager.ts

@@ -0,0 +1,36 @@
+import { ValidationError } from "@aura3d/core";
+import { type Entity } from "./Entity.js";
+
+export class EntityManager {
+  private readonly generations: number[] = [];
+  private readonly alive = new Set<number>();
+  private readonly free: number[] = [];
+
+  create(): Entity {
+    const id = this.free.pop() ?? this.generations.length;
+    this.generations[id] ??= 0;
+    this.alive.add(id);
+    return { id, generation: this.generations[id] };
+  }
+
+  destroy(entity: Entity): boolean {
+    if (!this.isAlive(entity)) return false;
+    this.alive.delete(entity.id);
+    this.generations[entity.id] += 1;
+    if (!Number.isSafeInteger(this.generations[entity.id])) throw new ValidationError("ENTITY_GENERATION_OVERFLOW", "Entity generation overflow.");
+    this.free.push(entity.id);
+    return true;
+  }
+
+  isAlive(entity: Entity): boolean {
+    return this.alive.has(entity.id) && this.generations[entity.id] === entity.generation;
+  }
+
+  get size(): number {
+    return this.alive.size;
+  }
+
+  entities(): Entity[] {
+    return [...this.alive].sort((a, b) => a - b).map((id) => ({ id, generation: this.generations[id] }));
+  }
+}

package/src/Query.ts

@@ -0,0 +1,57 @@
+import { ValidationError } from "@aura3d/core";
+import { Bitset } from "./Bitset.js";
+import { type ComponentCtor } from "./Component.js";
+import { type ComponentRegistry } from "./ComponentRegistry.js";
+import { type ComponentStore } from "./ComponentStore.js";
+import { type Entity } from "./Entity.js";
+import { type EntityManager } from "./EntityManager.js";
+
+export interface QueryOptions {
+  include?: ComponentCtor[];
+  exclude?: ComponentCtor[];
+}
+
+export class Query {
+  private readonly includeMask: Bitset;
+  private readonly excludeMask: Bitset;
+  private readonly include: readonly ComponentCtor[];
+  private readonly exclude: readonly ComponentCtor[];
+
+  constructor(
+    private readonly entities: EntityManager,
+    private readonly store: ComponentStore,
+    registry: ComponentRegistry,
+    options: QueryOptions
+  ) {
+    this.include = options.include ?? [];
+    this.exclude = options.exclude ?? [];
+    this.includeMask = Bitset.from(this.include.map((ctor) => registry.require(ctor).id));
+    this.excludeMask = Bitset.from(this.exclude.map((ctor) => registry.require(ctor).id));
+  }
+
+  matches(entity: Entity): boolean {
+    const signature = this.store.signature(entity);
+    return signature.containsAll(this.includeMask) && !signature.intersects(this.excludeMask);
+  }
+
+  toArray(): Entity[] {
+    if (this.include.length === 1 && this.exclude.length === 0) {
+      return this.store.entitiesWith(this.include[0]!);
+    }
+    return this.entities.entities().filter((entity) => this.matches(entity));
+  }
+
+  forEach(visitor: (entity: Entity) => void): void {
+    for (const entity of this.toArray()) visitor(entity);
+  }
+
+  first(): Entity | undefined {
+    return this.toArray()[0];
+  }
+
+  single(): Entity {
+    const result = this.toArray();
+    if (result.length !== 1) throw new ValidationError("QUERY_SINGLE", `Expected exactly one entity, found ${result.length}.`);
+    return result[0];
+  }
+}

package/src/SparseSet.ts

@@ -0,0 +1,56 @@
+import { entityKey, type Entity } from "./Entity.js";
+
+export class SparseSet<T> {
+  private readonly denseEntities: Entity[] = [];
+  private readonly denseValues: T[] = [];
+  private readonly sparse = new Map<string, number>();
+
+  add(entity: Entity, value: T): void {
+    const key = entityKey(entity);
+    const existing = this.sparse.get(key);
+    if (existing !== undefined) {
+      this.denseValues[existing] = value;
+      return;
+    }
+    this.sparse.set(key, this.denseEntities.length);
+    this.denseEntities.push(entity);
+    this.denseValues.push(value);
+  }
+
+  get(entity: Entity): T | undefined {
+    const index = this.sparse.get(entityKey(entity));
+    return index === undefined ? undefined : this.denseValues[index];
+  }
+
+  has(entity: Entity): boolean {
+    return this.sparse.has(entityKey(entity));
+  }
+
+  delete(entity: Entity): boolean {
+    const key = entityKey(entity);
+    const index = this.sparse.get(key);
+    if (index === undefined) return false;
+    const lastIndex = this.denseEntities.length - 1;
+    const lastEntity = this.denseEntities[lastIndex];
+    const lastValue = this.denseValues[lastIndex];
+    this.denseEntities[index] = lastEntity;
+    this.denseValues[index] = lastValue;
+    this.sparse.set(entityKey(lastEntity), index);
+    this.denseEntities.pop();
+    this.denseValues.pop();
+    this.sparse.delete(key);
+    return true;
+  }
+
+  entries(): [Entity, T][] {
+    return this.denseEntities.map((entity, index) => [entity, this.denseValues[index]]);
+  }
+
+  entities(): Entity[] {
+    return this.denseEntities.map((entity) => ({ ...entity }));
+  }
+
+  get size(): number {
+    return this.denseEntities.length;
+  }
+}

package/src/System.ts

@@ -0,0 +1,20 @@
+import { type World } from "./World.js";
+
+export type SystemPhase = "fixed" | "update" | "late";
+
+export interface SystemContext {
+  readonly deltaTime: number;
+  readonly elapsedTime: number;
+  readonly frame: number;
+}
+
+export interface System {
+  readonly name: string;
+  readonly phase?: SystemPhase;
+  readonly priority?: number;
+  readonly before?: readonly string[];
+  readonly after?: readonly string[];
+  onAdd?(world: World): void;
+  onRemove?(world: World): void;
+  update(world: World, context: SystemContext): void;
+}

package/src/SystemScheduler.ts

@@ -0,0 +1,79 @@
+import { ValidationError } from "@aura3d/core";
+import { type System, type SystemContext, type SystemPhase } from "./System.js";
+import { type World } from "./World.js";
+
+const phaseOrder: SystemPhase[] = ["fixed", "update", "late"];
+
+export class SystemScheduler {
+  private readonly systems = new Map<string, System>();
+
+  add(system: System, world?: World): void {
+    if (this.systems.has(system.name)) throw new ValidationError("DUPLICATE_SYSTEM", `Duplicate system name: ${system.name}`);
+    this.systems.set(system.name, system);
+    system.onAdd?.(world as World);
+  }
+
+  remove(name: string, world?: World): boolean {
+    const system = this.systems.get(name);
+    if (!system) return false;
+    system.onRemove?.(world as World);
+    return this.systems.delete(name);
+  }
+
+  order(phase?: SystemPhase): System[] {
+    const systems = [...this.systems.values()].filter((system) => (system.phase ?? "update") === (phase ?? system.phase ?? "update"));
+    return sortSystems(systems);
+  }
+
+  update(world: World, context: SystemContext): void {
+    for (const phase of phaseOrder) {
+      for (const system of this.order(phase)) system.update(world, context);
+    }
+  }
+}
+
+function sortSystems(systems: System[]): System[] {
+  const byName = new Map(systems.map((system) => [system.name, system]));
+  const graph = new Map<string, Set<string>>();
+  const indegree = new Map<string, number>();
+  const insertion = new Map(systems.map((system, index) => [system.name, index]));
+  for (const system of systems) {
+    graph.set(system.name, new Set());
+    indegree.set(system.name, 0);
+  }
+  for (const system of systems) {
+    for (const dependency of system.after ?? []) addEdge(dependency, system.name);
+    for (const dependent of system.before ?? []) addEdge(system.name, dependent);
+  }
+  const ready = systems
+    .filter((system) => indegree.get(system.name) === 0)
+    .sort(compareSystems);
+  const result: System[] = [];
+  while (ready.length > 0) {
+    const system = ready.shift() as System;
+    result.push(system);
+    for (const dependent of graph.get(system.name) ?? []) {
+      indegree.set(dependent, (indegree.get(dependent) ?? 0) - 1);
+      if (indegree.get(dependent) === 0) {
+        ready.push(byName.get(dependent) as System);
+        ready.sort(compareSystems);
+      }
+    }
+  }
+  if (result.length !== systems.length) throw new ValidationError("ECS_SYSTEM_CYCLE", "ECS system dependency cycle rejected.");
+  return result;
+
+  function addEdge(from: string, to: string): void {
+    if (!byName.has(from)) throw new ValidationError("MISSING_ECS_SYSTEM_DEPENDENCY", `Missing ECS system dependency: ${from}`);
+    if (!byName.has(to)) throw new ValidationError("MISSING_ECS_SYSTEM_DEPENDENCY", `Missing ECS system dependency: ${to}`);
+    const edges = graph.get(from) as Set<string>;
+    if (!edges.has(to)) {
+      edges.add(to);
+      indegree.set(to, (indegree.get(to) ?? 0) + 1);
+    }
+  }
+
+  function compareSystems(a: System, b: System): number {
+    return (a.priority ?? 0) - (b.priority ?? 0) || (insertion.get(a.name) ?? 0) - (insertion.get(b.name) ?? 0);
+  }
+}

package/src/World.ts

@@ -0,0 +1,76 @@
+import { ValidationError } from "@aura3d/core";
+import { type ComponentCtor, type ComponentSchema } from "./Component.js";
+import { ComponentRegistry } from "./ComponentRegistry.js";
+import { ComponentStore } from "./ComponentStore.js";
+import { type Entity } from "./Entity.js";
+import { EntityManager } from "./EntityManager.js";
+import { Query, type QueryOptions } from "./Query.js";
+import { SystemScheduler } from "./SystemScheduler.js";
+import { type SystemContext } from "./System.js";
+
+export class World {
+  readonly entities = new EntityManager();
+  readonly registry = new ComponentRegistry();
+  readonly components = new ComponentStore(this.registry);
+  readonly systems = new SystemScheduler();
+  private version = 0;
+
+  registerComponent<T extends object>(ctor: ComponentCtor<T>, schema?: ComponentSchema): void {
+    this.registry.register(ctor, schema);
+  }
+
+  createEntity(): Entity {
+    this.version += 1;
+    return this.entities.create();
+  }
+
+  destroyEntity(entity: Entity): boolean {
+    this.assertAlive(entity);
+    const destroyed = this.entities.destroy(entity);
+    if (destroyed) {
+      this.components.deleteEntity(entity);
+      this.version += 1;
+    }
+    return destroyed;
+  }
+
+  add<T extends object>(entity: Entity, ctor: ComponentCtor<T>, component: T): void {
+    this.assertAlive(entity);
+    if (!this.registry.get(ctor)) this.registry.register(ctor);
+    this.components.add(entity, ctor, component);
+    this.version += 1;
+  }
+
+  remove<T extends object>(entity: Entity, ctor: ComponentCtor<T>): boolean {
+    this.assertAlive(entity);
+    const removed = this.components.remove(entity, ctor);
+    if (removed) this.version += 1;
+    return removed;
+  }
+
+  get<T extends object>(entity: Entity, ctor: ComponentCtor<T>): T | undefined {
+    this.assertAlive(entity);
+    return this.components.get(entity, ctor);
+  }
+
+  has<T extends object>(entity: Entity, ctor: ComponentCtor<T>): boolean {
+    this.assertAlive(entity);
+    return this.components.has(entity, ctor);
+  }
+
+  query(options: QueryOptions): Query {
+    return new Query(this.entities, this.components, this.registry, options);
+  }
+
+  update(context: SystemContext): void {
+    this.systems.update(this, context);
+  }
+
+  getVersion(): number {
+    return this.version;
+  }
+
+  assertAlive(entity: Entity): void {
+    if (!this.entities.isAlive(entity)) throw new ValidationError("ENTITY_NOT_ALIVE", `Entity is not alive: ${entity.id}:${entity.generation}`);
+  }
+}