@aura3d/ecs 1.4.0 → 1.4.2

package/src/SystemScheduler.ts

@@ -1,81 +0,0 @@
-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 {
-    // `before`/`after` are soft ordering constraints: if the referenced
-    // system is not registered (or runs in a different phase), the edge is
-    // simply skipped instead of failing the whole schedule.
-    if (!byName.has(from) || !byName.has(to)) return;
-    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

@@ -1,76 +0,0 @@
-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}`);
-  }
-}

package/src/components/ActiveComponent.ts

@@ -1,56 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-import { type ComponentSchema } from "../Component.js";
-
-export interface SerializedActiveComponent {
-  readonly activeSelf: boolean;
-}
-
-export class ActiveComponent {
-  activeSelf: boolean;
-  activeInHierarchy: boolean;
-
-  constructor(active = true) {
-    if (typeof active !== "boolean") throw new ValidationError("ACTIVE_COMPONENT", "ActiveComponent expects a boolean active state.");
-    this.activeSelf = active;
-    this.activeInHierarchy = active;
-  }
-
-  get isActive(): boolean {
-    return this.activeSelf;
-  }
-
-  get isActiveInHierarchy(): boolean {
-    return this.activeInHierarchy;
-  }
-
-  setActive(active: boolean): void {
-    if (typeof active !== "boolean") throw new ValidationError("ACTIVE_COMPONENT", "Active state must be boolean.");
-    this.activeSelf = active;
-  }
-
-  toggle(): void {
-    this.activeSelf = !this.activeSelf;
-  }
-
-  toJSON(): SerializedActiveComponent {
-    return { activeSelf: this.activeSelf };
-  }
-
-  static readonly schema: ComponentSchema = {
-    version: 1,
-    serialize(component: object): SerializedActiveComponent {
-      const active = component as ActiveComponent;
-      return { activeSelf: active.activeSelf };
-    },
-    deserialize(data: unknown): ActiveComponent {
-      if (!isRecord(data) || typeof data.activeSelf !== "boolean") {
-        throw new ValidationError("ACTIVE_COMPONENT_DESERIALIZE", "ActiveComponent data requires activeSelf boolean.");
-      }
-      return new ActiveComponent(data.activeSelf);
-    }
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}

package/src/components/CameraComponent.ts

@@ -1,32 +0,0 @@
-export type CameraKind = "perspective" | "orthographic";
-
-/**
- * Camera parameters + computed matrices for an ECS entity.
- *
- * {@link CameraSystem} computes `projectionMatrix`, `viewMatrix`, and
- * `viewProjectionMatrix` each frame from the entity's
- * {@link WorldTransformComponent}.
- */
-export class CameraComponent {
-  kind: CameraKind = "perspective";
-
-  // Perspective
-  fovYRadians = Math.PI / 3;
-  aspect = 1;
-  near = 0.1;
-  far = 1000;
-
-  // Orthographic
-  left = -1;
-  right = 1;
-  bottom = -1;
-  top = 1;
-  zoom = 1;
-
-  // Computed each frame by CameraSystem
-  projectionMatrix = new Float32Array(16);
-  viewMatrix = new Float32Array(16);
-  viewProjectionMatrix = new Float32Array(16);
-
-  viewport = { x: 0, y: 0, width: 1, height: 1 };
-}

package/src/components/HierarchyComponent.ts

@@ -1,134 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-import { type ComponentSchema } from "../Component.js";
-import { entityKey, sameEntity, type Entity } from "../Entity.js";
-
-export interface SerializedHierarchyComponent {
-  readonly parent: Entity | null;
-  readonly children: readonly Entity[];
-  readonly previousSibling: Entity | null;
-  readonly nextSibling: Entity | null;
-  readonly depth: number;
-}
-
-export class HierarchyComponent {
-  /**
-   * Parent entity, or `null` for root entities.
-   *
-   * Must be set via `HierarchySystem.setParent` (or `addChild`), which
-   * maintains {@link depth}, sibling links, and the parent's child list.
-   * Setting this field directly (including via the constructor argument)
-   * leaves `depth` stale at 0 — `TransformSystem` recomputes depth
-   * defensively for its parents-before-children ordering, but child/sibling
-   * bookkeeping will remain out of sync until `setParent` is used.
-   */
-  parent: Entity | null;
-  previousSibling: Entity | null = null;
-  nextSibling: Entity | null = null;
-  depth = 0;
-  private readonly childEntities: Entity[] = [];
-
-  constructor(parent: Entity | null = null) {
-    this.parent = parent;
-  }
-
-  get children(): readonly Entity[] {
-    return this.childEntities;
-  }
-
-  get childCount(): number {
-    return this.childEntities.length;
-  }
-
-  get firstChild(): Entity | null {
-    return this.childEntities[0] ?? null;
-  }
-
-  get lastChild(): Entity | null {
-    return this.childEntities[this.childEntities.length - 1] ?? null;
-  }
-
-  hasParent(): boolean {
-    return this.parent !== null;
-  }
-
-  hasChildren(): boolean {
-    return this.childEntities.length > 0;
-  }
-
-  includesChild(entity: Entity): boolean {
-    return this.childEntities.some((child) => sameEntity(child, entity));
-  }
-
-  forEachChild(callback: (child: Entity) => void): void {
-    for (const child of this.childEntities) callback(child);
-  }
-
-  getSiblingIndex(entity?: Entity): number {
-    if (!entity) return this.parent ? 0 : -1;
-    return this.childEntities.findIndex((child) => sameEntity(child, entity));
-  }
-
-  _setParent(parent: Entity | null): void {
-    this.parent = parent;
-  }
-
-  _addChild(child: Entity): void {
-    if (!this.includesChild(child)) this.childEntities.push(child);
-  }
-
-  _removeChild(child: Entity): boolean {
-    const index = this.childEntities.findIndex((entry) => sameEntity(entry, child));
-    if (index < 0) return false;
-    this.childEntities.splice(index, 1);
-    return true;
-  }
-
-  _clearChildren(): void {
-    this.childEntities.length = 0;
-  }
-
-  _moveChild(child: Entity, index: number): void {
-    const current = this.childEntities.findIndex((entry) => sameEntity(entry, child));
-    if (current < 0) throw new ValidationError("ECS_HIERARCHY_CHILD", `Entity is not a child: ${entityKey(child)}`);
-    const [entry] = this.childEntities.splice(current, 1);
-    this.childEntities.splice(Math.max(0, Math.min(index, this.childEntities.length)), 0, entry);
-  }
-
-  toJSON(): SerializedHierarchyComponent {
-    return {
-      parent: this.parent ? { ...this.parent } : null,
-      children: this.childEntities.map((child) => ({ ...child })),
-      previousSibling: this.previousSibling ? { ...this.previousSibling } : null,
-      nextSibling: this.nextSibling ? { ...this.nextSibling } : null,
-      depth: this.depth
-    };
-  }
-
-  static readonly schema: ComponentSchema = {
-    version: 1,
-    serialize(component: object): SerializedHierarchyComponent {
-      return (component as HierarchyComponent).toJSON();
-    },
-    deserialize(data: unknown): HierarchyComponent {
-      if (!isRecord(data) || !Array.isArray(data.children)) {
-        throw new ValidationError("HIERARCHY_COMPONENT_DESERIALIZE", "HierarchyComponent data requires children array.");
-      }
-      const hierarchy = new HierarchyComponent(isEntity(data.parent) ? data.parent : null);
-      for (const child of data.children) {
-        if (isEntity(child)) hierarchy._addChild(child);
-      }
-      hierarchy.previousSibling = isEntity(data.previousSibling) ? data.previousSibling : null;
-      hierarchy.nextSibling = isEntity(data.nextSibling) ? data.nextSibling : null;
-      hierarchy.depth = typeof data.depth === "number" && Number.isFinite(data.depth) ? Math.max(0, Math.floor(data.depth)) : 0;
-      return hierarchy;
-    }
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function isEntity(value: unknown): value is Entity {
-  return isRecord(value) && Number.isSafeInteger(value.id) && Number.isSafeInteger(value.generation);
-}

package/src/components/LightComponent.ts

@@ -1,18 +0,0 @@
-export type LightKind = "directional" | "point" | "spot" | "ambient";
-
-/**
- * Light parameters for an ECS entity.
- *
- * The ECS render bridge collects lights each frame and passes them to the
- * renderer as part of the {@link RenderSource} lighting state.
- */
-export class LightComponent {
-  kind: LightKind = "directional";
-  color: [number, number, number] = [1, 1, 1];
-  intensity = 1;
-  range = 10;
-  angle = Math.PI / 4; // spot only
-  penumbra = 0; // spot only
-  castsShadow = false;
-  layerMask = 1;
-}

package/src/components/MeshComponent.ts

@@ -1,23 +0,0 @@
-import type { SkinningPaletteBinding } from "@aura3d/rendering";
-
-/**
- * Renderable geometry + material binding for an ECS entity.
- *
- * References resources by name/handle; the ECS render bridge resolves them
- * through the {@link ECSRenderLibraries} map at collection time.
- */
-export class MeshComponent {
-  geometry: string;
-  material: string;
-  castShadow = true;
-  receiveShadow = true;
-  skinning?: SkinningPaletteBinding;
-  morphWeights?: readonly number[];
-  instanceTransforms?: Float32Array;
-  instanceColors?: Float32Array;
-
-  constructor(geometry: string, material: string) {
-    this.geometry = geometry;
-    this.material = material;
-  }
-}

package/src/components/NameComponent.ts

@@ -1,7 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-
-export class NameComponent {
-  constructor(public name: string) {
-    if (!name) throw new ValidationError("NAME_COMPONENT", "NameComponent requires a non-empty name.");
-  }
-}

package/src/components/TagComponent.ts

@@ -1,7 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-
-export class TagComponent {
-  constructor(public tag: string) {
-    if (!tag) throw new ValidationError("TAG_COMPONENT", "TagComponent requires a non-empty tag.");
-  }
-}

package/src/components/TransformComponent.ts

@@ -1,34 +0,0 @@
-import { Quaternion, Vector3 } from "@aura3d/math";
-
-export class TransformComponent {
-  position: [number, number, number];
-  rotation: [number, number, number, number];
-  scale: [number, number, number];
-
-  constructor(
-    position: Vector3 | readonly [number, number, number] = Vector3.zero.clone(),
-    rotation: Quaternion | readonly [number, number, number, number] = Quaternion.identity.clone(),
-    scale: Vector3 | readonly [number, number, number] = Vector3.one.clone()
-  ) {
-    this.position = position instanceof Vector3 ? position.toArray() : [...position];
-    const normalizedRotation = rotation instanceof Quaternion ? rotation.normalize() : new Quaternion(rotation[0], rotation[1], rotation[2], rotation[3]).normalize();
-    this.rotation = [normalizedRotation.x, normalizedRotation.y, normalizedRotation.z, normalizedRotation.w];
-    this.scale = scale instanceof Vector3 ? scale.toArray() : [...scale];
-  }
-
-  toJSON(): { position: [number, number, number]; rotation: [number, number, number, number]; scale: [number, number, number] } {
-    return {
-      position: [...this.position],
-      rotation: [...this.rotation],
-      scale: [...this.scale]
-    };
-  }
-
-  toMath(): { position: Vector3; rotation: Quaternion; scale: Vector3 } {
-    return {
-      position: new Vector3(this.position[0], this.position[1], this.position[2]),
-      rotation: new Quaternion(this.rotation[0], this.rotation[1], this.rotation[2], this.rotation[3]),
-      scale: new Vector3(this.scale[0], this.scale[1], this.scale[2])
-    };
-  }
-}

package/src/components/WorldTransformComponent.ts

@@ -1,22 +0,0 @@
-/**
- * Computed world-space transform for an ECS entity.
- *
- * Written by {@link TransformSystem} each frame from the entity's
- * {@link TransformComponent} and {@link HierarchyComponent} parent chain.
- * The renderer bridge reads this directly — it never touches local transforms.
- */
-export class WorldTransformComponent {
-  worldMatrix = new Float32Array([
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1
-  ]);
-
-  normalMatrix = new Float32Array([
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1
-  ]);
-}

package/src/index.ts

@@ -1,25 +0,0 @@
-export * from "./Entity.js";
-export * from "./EntityManager.js";
-export * from "./Component.js";
-export * from "./ComponentRegistry.js";
-export * from "./SparseSet.js";
-export * from "./Bitset.js";
-export * from "./ComponentStore.js";
-export * from "./Archetype.js";
-export * from "./Query.js";
-export * from "./CommandBuffer.js";
-export * from "./System.js";
-export * from "./SystemScheduler.js";
-export * from "./World.js";
-export * from "./ECSSerializer.js";
-export * from "./ECSProfiler.js";
-export * from "./components/TransformComponent.js";
-export * from "./components/WorldTransformComponent.js";
-export * from "./components/CameraComponent.js";
-export * from "./components/LightComponent.js";
-export * from "./components/MeshComponent.js";
-export * from "./components/NameComponent.js";
-export * from "./components/TagComponent.js";
-export * from "./components/ActiveComponent.js";
-export * from "./components/HierarchyComponent.js";
-export * from "./systems/index.js";

package/src/systems/ActiveSystem.ts

@@ -1,64 +0,0 @@
-import { type Entity } from "../Entity.js";
-import { type System, type SystemContext } from "../System.js";
-import { type World } from "../World.js";
-import { ActiveComponent } from "../components/ActiveComponent.js";
-import { HierarchyComponent } from "../components/HierarchyComponent.js";
-
-export class ActiveSystem implements System {
-  readonly name = "ActiveSystem";
-  readonly phase = "update";
-  readonly priority = -90;
-  onActiveChanged?: (entity: Entity, activeInHierarchy: boolean) => void;
-
-  update(world: World, _context: SystemContext): void {
-    const memo = new Map<string, boolean>();
-    const entities = world.query({ include: [ActiveComponent] }).toArray().sort((left, right) => {
-      return (world.get(left, HierarchyComponent)?.depth ?? 0) - (world.get(right, HierarchyComponent)?.depth ?? 0);
-    });
-    for (const entity of entities) {
-      const component = world.get(entity, ActiveComponent);
-      if (!component) continue;
-      const previous = component.activeInHierarchy;
-      component.activeInHierarchy = computeActiveInHierarchy(world, entity, memo);
-      if (previous !== component.activeInHierarchy) this.onActiveChanged?.(entity, component.activeInHierarchy);
-    }
-  }
-
-  setActive(world: World, entity: Entity, active: boolean): void {
-    let component = world.get(entity, ActiveComponent);
-    if (!component) {
-      component = new ActiveComponent(active);
-      world.add(entity, ActiveComponent, component);
-    } else {
-      component.setActive(active);
-    }
-    this.update(world, { deltaTime: 0, elapsedTime: 0, frame: 0 });
-  }
-
-  isActive(world: World, entity: Entity): boolean {
-    return world.get(entity, ActiveComponent)?.activeSelf ?? true;
-  }
-
-  isActiveInHierarchy(world: World, entity: Entity): boolean {
-    return world.get(entity, ActiveComponent)?.activeInHierarchy ?? true;
-  }
-
-  getActiveEntities(world: World): Entity[] {
-    return world.query({ include: [ActiveComponent] }).toArray().filter((entity) => this.isActiveInHierarchy(world, entity));
-  }
-
-  getInactiveEntities(world: World): Entity[] {
-    return world.query({ include: [ActiveComponent] }).toArray().filter((entity) => !this.isActiveInHierarchy(world, entity));
-  }
-}
-
-function computeActiveInHierarchy(world: World, entity: Entity, memo: Map<string, boolean>): boolean {
-  const key = `${entity.id}:${entity.generation}`;
-  const cached = memo.get(key);
-  if (cached !== undefined) return cached;
-  const activeSelf = world.get(entity, ActiveComponent)?.activeSelf ?? true;
-  const parent = world.get(entity, HierarchyComponent)?.parent ?? null;
-  const active = activeSelf && (parent ? computeActiveInHierarchy(world, parent, memo) : true);
-  memo.set(key, active);
-  return active;
-}

package/src/systems/CameraSystem.ts

@@ -1,50 +0,0 @@
-import { Matrix4 } from "@aura3d/math";
-import { type System, type SystemContext } from "../System.js";
-import { type World } from "../World.js";
-import { CameraComponent } from "../components/CameraComponent.js";
-import { WorldTransformComponent } from "../components/WorldTransformComponent.js";
-
-/**
- * Computes camera projection and view matrices for entities that have
- * both {@link CameraComponent} and {@link WorldTransformComponent}.
- *
- * Runs after {@link TransformSystem} so the camera entity's world matrix
- * is already computed.
- */
-export class CameraSystem implements System {
-  readonly name = "CameraSystem";
-  readonly phase = "update";
-  readonly priority = -70;
-  // Soft ordering constraint: the scheduler skips this edge when
-  // TransformSystem is not registered, so CameraSystem can run standalone.
-  readonly after = ["TransformSystem"];
-
-  update(world: World, _context: SystemContext): void {
-    for (const entity of world
-      .query({ include: [CameraComponent, WorldTransformComponent] })
-      .toArray()) {
-      const cam = world.get(entity, CameraComponent)!;
-      const wt = world.get(entity, WorldTransformComponent)!;
-
-      const projection =
-        cam.kind === "perspective"
-          ? Matrix4.perspective(cam.fovYRadians, cam.aspect, cam.near, cam.far)
-          : Matrix4.orthographic(
-              cam.left / cam.zoom,
-              cam.right / cam.zoom,
-              cam.bottom / cam.zoom,
-              cam.top / cam.zoom,
-              cam.near,
-              cam.far
-            );
-
-      // viewMatrix = inverse(worldMatrix)
-      const worldMat = new Matrix4(wt.worldMatrix as unknown as Matrix4["elements"]);
-      const view = worldMat.inverse();
-
-      (cam.projectionMatrix as Float32Array).set(projection.elements);
-      (cam.viewMatrix as Float32Array).set(view.elements);
-      (cam.viewProjectionMatrix as Float32Array).set(projection.multiply(view).elements);
-    }
-  }
-}