@aura3d/ecs 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura3d/ecs",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,7 +12,38 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@aura3d/core": "1.4.0",
-    "@aura3d/math": "1.4.0"
-  }
+    "@aura3d/core": "1.4.2",
+    "@aura3d/math": "1.4.2"
+  },
+  "description": "Entity identity, components, sparse-set and archetype storage, queries, command buffers, systems, scheduling, serialization, and transform components.",
+  "keywords": [
+    "aura3d",
+    "3d",
+    "browser-3d",
+    "web-3d",
+    "typescript",
+    "ecs",
+    "entity-component-system",
+    "game-dev",
+    "systems",
+    "queries",
+    "component-storage"
+  ],
+  "homepage": "https://aura3d.auraone.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/auraoneai/aura3d.git",
+    "directory": "packages/ecs"
+  },
+  "bugs": {
+    "url": "https://github.com/auraoneai/aura3d/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ]
 }

package/src/Archetype.ts

@@ -1,23 +0,0 @@
-import { Bitset } from "./Bitset.js";
-import { type Entity } from "./Entity.js";
-
-export class Archetype {
-  readonly signature: Bitset;
-  private readonly members = new Map<number, Entity>();
-
-  constructor(signature: Bitset) {
-    this.signature = signature.clone();
-  }
-
-  add(entity: Entity): void {
-    this.members.set(entity.id, entity);
-  }
-
-  delete(entity: Entity): boolean {
-    return this.members.delete(entity.id);
-  }
-
-  entities(): Entity[] {
-    return [...this.members.values()].sort((a, b) => a.id - b.id);
-  }
-}

package/src/Bitset.ts

@@ -1,47 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-
-export class Bitset {
-  private readonly values = new Set<number>();
-
-  static from(values: Iterable<number>): Bitset {
-    const bitset = new Bitset();
-    for (const value of values) bitset.add(value);
-    return bitset;
-  }
-
-  add(value: number): this {
-    if (!Number.isSafeInteger(value) || value < 0) throw new ValidationError("BITSET_VALUE", "Bitset values must be non-negative safe integers.");
-    this.values.add(value);
-    return this;
-  }
-
-  delete(value: number): boolean {
-    return this.values.delete(value);
-  }
-
-  has(value: number): boolean {
-    return this.values.has(value);
-  }
-
-  containsAll(other: Bitset): boolean {
-    for (const value of other.values) {
-      if (!this.values.has(value)) return false;
-    }
-    return true;
-  }
-
-  intersects(other: Bitset): boolean {
-    for (const value of other.values) {
-      if (this.values.has(value)) return true;
-    }
-    return false;
-  }
-
-  toArray(): number[] {
-    return [...this.values].sort((a, b) => a - b);
-  }
-
-  clone(): Bitset {
-    return Bitset.from(this.values);
-  }
-}

package/src/CommandBuffer.ts

@@ -1,97 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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;
-}