@aura3d/ecs 1.3.3 → 1.4.1

package/src/systems/HierarchySystem.ts

@@ -1,182 +0,0 @@
-import { ValidationError } from "@aura3d/core";
-import { entityKey, sameEntity, type Entity } from "../Entity.js";
-import { type System, type SystemContext } from "../System.js";
-import { type World } from "../World.js";
-import { HierarchyComponent } from "../components/HierarchyComponent.js";
-
-export class HierarchySystem implements System {
-  readonly name = "HierarchySystem";
-  readonly phase = "update";
-  readonly priority = -100;
-
-  update(world: World, _context: SystemContext): void {
-    for (const entity of world.query({ include: [HierarchyComponent] }).toArray()) {
-      const hierarchy = world.get(entity, HierarchyComponent);
-      if (!hierarchy) continue;
-      if (hierarchy.parent && !world.entities.isAlive(hierarchy.parent)) {
-        hierarchy._setParent(null);
-        hierarchy.depth = 0;
-      }
-    }
-    const cycles = this.detectCycles(world);
-    if (cycles.length > 0) throw new ValidationError("ECS_HIERARCHY_CYCLE", `Hierarchy cycle detected: ${cycles.map(entityKey).join(", ")}`);
-  }
-
-  setParent(world: World, child: Entity, parent: Entity | null): void {
-    world.assertAlive(child);
-    if (parent) world.assertAlive(parent);
-    if (parent && sameEntity(child, parent)) throw new ValidationError("ECS_HIERARCHY_SELF_PARENT", "Entity cannot be parented to itself.");
-    const childHierarchy = ensureHierarchy(world, child);
-    if (parent) ensureHierarchy(world, parent);
-    if (parent && this.isAncestorOf(world, child, parent)) {
-      throw new ValidationError("ECS_HIERARCHY_CYCLE", `Parenting ${entityKey(child)} to ${entityKey(parent)} would create a cycle.`);
-    }
-
-    const previousParent = childHierarchy.parent;
-    if (sameOptionalEntity(childHierarchy.parent, parent)) return;
-    if (previousParent) {
-      world.get(previousParent, HierarchyComponent)?._removeChild(child);
-      this.refreshChildSiblings(world, previousParent);
-    }
-
-    childHierarchy._setParent(parent ? { ...parent } : null);
-    childHierarchy.previousSibling = null;
-    childHierarchy.nextSibling = null;
-    if (parent) {
-      const parentHierarchy = ensureHierarchy(world, parent);
-      parentHierarchy._addChild(child);
-      this.refreshChildSiblings(world, parent);
-      childHierarchy.depth = parentHierarchy.depth + 1;
-    } else {
-      childHierarchy.depth = 0;
-    }
-    this.updateDescendantDepths(world, child);
-  }
-
-  addChild(world: World, parent: Entity, child: Entity): void {
-    this.setParent(world, child, parent);
-  }
-
-  removeFromParent(world: World, entity: Entity): void {
-    this.setParent(world, entity, null);
-  }
-
-  getParent(world: World, entity: Entity): Entity | null {
-    return world.get(entity, HierarchyComponent)?.parent ?? null;
-  }
-
-  getChildren(world: World, entity: Entity): readonly Entity[] {
-    return world.get(entity, HierarchyComponent)?.children ?? [];
-  }
-
-  getDepth(world: World, entity: Entity): number {
-    return world.get(entity, HierarchyComponent)?.depth ?? 0;
-  }
-
-  forEachDescendant(world: World, entity: Entity, callback: (descendant: Entity, depth: number) => void): void {
-    const hierarchy = world.get(entity, HierarchyComponent);
-    if (!hierarchy) return;
-    for (const child of hierarchy.children) {
-      const childHierarchy = world.get(child, HierarchyComponent);
-      callback(child, childHierarchy?.depth ?? hierarchy.depth + 1);
-      this.forEachDescendant(world, child, callback);
-    }
-  }
-
-  isAncestorOf(world: World, ancestor: Entity, descendant: Entity): boolean {
-    let cursor = world.get(descendant, HierarchyComponent)?.parent ?? null;
-    const guard = new Set<string>();
-    while (cursor) {
-      if (sameEntity(cursor, ancestor)) return true;
-      const key = entityKey(cursor);
-      if (guard.has(key)) return false;
-      guard.add(key);
-      cursor = world.get(cursor, HierarchyComponent)?.parent ?? null;
-    }
-    return false;
-  }
-
-  isDescendantOf(world: World, descendant: Entity, ancestor: Entity): boolean {
-    return this.isAncestorOf(world, ancestor, descendant);
-  }
-
-  setSiblingIndex(world: World, entity: Entity, index: number): void {
-    const hierarchy = world.get(entity, HierarchyComponent);
-    if (!hierarchy?.parent) return;
-    world.get(hierarchy.parent, HierarchyComponent)?._moveChild(entity, index);
-    this.refreshChildSiblings(world, hierarchy.parent);
-  }
-
-  detachChildren(world: World, entity: Entity): Entity[] {
-    const children = [...this.getChildren(world, entity)];
-    for (const child of children) this.setParent(world, child, null);
-    return children;
-  }
-
-  validateHierarchy(world: World): boolean {
-    return this.detectCycles(world).length === 0 && world.query({ include: [HierarchyComponent] }).toArray().every((entity) => {
-      const hierarchy = world.get(entity, HierarchyComponent);
-      if (!hierarchy?.parent) return true;
-      const parent = world.get(hierarchy.parent, HierarchyComponent);
-      return Boolean(parent?.includesChild(entity));
-    });
-  }
-
-  detectCycles(world: World): Entity[] {
-    const cycles: Entity[] = [];
-    const visiting = new Set<string>();
-    const visited = new Set<string>();
-    const visit = (entity: Entity): void => {
-      const key = entityKey(entity);
-      if (visiting.has(key)) {
-        cycles.push(entity);
-        return;
-      }
-      if (visited.has(key)) return;
-      visiting.add(key);
-      const parent = world.get(entity, HierarchyComponent)?.parent;
-      if (parent) visit(parent);
-      visiting.delete(key);
-      visited.add(key);
-    };
-    for (const entity of world.query({ include: [HierarchyComponent] }).toArray()) visit(entity);
-    return cycles;
-  }
-
-  private updateDescendantDepths(world: World, entity: Entity): void {
-    const hierarchy = world.get(entity, HierarchyComponent);
-    if (!hierarchy) return;
-    for (const child of hierarchy.children) {
-      const childHierarchy = world.get(child, HierarchyComponent);
-      if (!childHierarchy) continue;
-      childHierarchy.depth = hierarchy.depth + 1;
-      this.updateDescendantDepths(world, child);
-    }
-  }
-
-  private refreshChildSiblings(world: World, parent: Entity): void {
-    const parentHierarchy = world.get(parent, HierarchyComponent);
-    if (!parentHierarchy) return;
-    const children = parentHierarchy.children;
-    for (let index = 0; index < children.length; index += 1) {
-      const child = children[index];
-      const hierarchy = world.get(child, HierarchyComponent);
-      if (!hierarchy) continue;
-      hierarchy.previousSibling = children[index - 1] ? { ...children[index - 1] } : null;
-      hierarchy.nextSibling = children[index + 1] ? { ...children[index + 1] } : null;
-    }
-  }
-}
-
-function ensureHierarchy(world: World, entity: Entity): HierarchyComponent {
-  if (!world.registry.get(HierarchyComponent)) world.registerComponent(HierarchyComponent);
-  const existing = world.get(entity, HierarchyComponent);
-  if (existing) return existing;
-  world.add(entity, HierarchyComponent, new HierarchyComponent());
-  return world.get(entity, HierarchyComponent) as HierarchyComponent;
-}
-
-function sameOptionalEntity(left: Entity | null, right: Entity | null): boolean {
-  if (!left || !right) return left === right;
-  return sameEntity(left, right);
-}

package/src/systems/TransformSystem.ts

@@ -1,108 +0,0 @@
-import { Matrix4, Quaternion, Vector3 } from "@aura3d/math";
-import { type Entity } from "../Entity.js";
-import { type System, type SystemContext } from "../System.js";
-import { type World } from "../World.js";
-import { HierarchyComponent } from "../components/HierarchyComponent.js";
-import { TransformComponent } from "../components/TransformComponent.js";
-import { WorldTransformComponent } from "../components/WorldTransformComponent.js";
-
-/** Safety cap for defensive parent-chain walks (guards against cycles created by direct `parent` mutation). */
-const MAX_HIERARCHY_DEPTH = 4096;
-
-/**
- * Computes {@link WorldTransformComponent} for every entity that has both
- * {@link TransformComponent} and {@link HierarchyComponent}.
- *
- * Entities are processed in depth order (parents before children) so the
- * world matrix cascade is correct in a single pass.
- */
-export class TransformSystem implements System {
-  readonly name = "TransformSystem";
-  readonly phase = "update";
-  readonly priority = -80;
-
-  update(world: World, _context: SystemContext): void {
-    const entities = world
-      .query({ include: [TransformComponent, HierarchyComponent] })
-      .toArray()
-      .sort((a, b) => effectiveDepth(world, a) - effectiveDepth(world, b));
-
-    for (const entity of entities) {
-      const transform = world.get(entity, TransformComponent)!;
-      const hierarchy = world.get(entity, HierarchyComponent)!;
-
-      const local = Matrix4.compose(
-        new Vector3(...transform.position),
-        new Quaternion(...transform.rotation),
-        new Vector3(...transform.scale)
-      );
-
-      let worldMat: Matrix4;
-      if (hierarchy.parent) {
-        const parentWtc = world.get(hierarchy.parent, WorldTransformComponent);
-        worldMat = parentWtc
-          ? new Matrix4(parentWtc.worldMatrix as unknown as Matrix4["elements"]).multiply(local)
-          : local;
-      } else {
-        worldMat = local;
-      }
-
-      let wtc = world.get(entity, WorldTransformComponent);
-      if (!wtc) {
-        wtc = new WorldTransformComponent();
-        world.add(entity, WorldTransformComponent, wtc);
-      }
-      (wtc.worldMatrix as Float32Array).set(worldMat.elements);
-      (wtc.normalMatrix as Float32Array).set(computeNormalMatrix(worldMat));
-    }
-  }
-}
-
-/**
- * Returns the depth used for parents-before-children ordering.
- *
- * {@link HierarchyComponent.depth} is maintained by `HierarchySystem.setParent`.
- * If `parent` was set directly (constructor argument or field mutation) the
- * stored depth is stale at 0, so recompute it defensively by walking the
- * parent chain.
- */
-function effectiveDepth(world: World, entity: Entity): number {
-  const hierarchy = world.get(entity, HierarchyComponent);
-  if (!hierarchy) return 0;
-  if (hierarchy.depth > 0 || hierarchy.parent === null) return hierarchy.depth;
-
-  let depth = 0;
-  let current: Entity | null = hierarchy.parent;
-  while (current && depth < MAX_HIERARCHY_DEPTH) {
-    depth += 1;
-    const parentHierarchy: HierarchyComponent | undefined = world.entities.isAlive(current)
-      ? world.get(current, HierarchyComponent)
-      : undefined;
-    current = parentHierarchy?.parent ?? null;
-  }
-  return depth;
-}
-
-function computeNormalMatrix(worldMat: Matrix4): Float32Array {
-  // Normal matrix = inverse-TRANSPOSE of the world matrix, matching the
-  // renderer's reference `normalMatrixFromModel` (Renderer.ts):
-  // transpose(invert(model)), then extract the upper-left 3x3 into a 4x4
-  // with identity in the 4th row/col (column-major layout).
-  // Avoid crashing on singular matrices (zero scale) by falling back to identity.
-  try {
-    const m = worldMat.inverse().transpose().elements;
-    return new Float32Array([
-      m[0], m[1], m[2], 0,
-      m[4], m[5], m[6], 0,
-      m[8], m[9], m[10], 0,
-      0, 0, 0, 1,
-    ]);
-  } catch {
-    return new Float32Array([
-      1, 0, 0, 0,
-      0, 1, 0, 0,
-      0, 0, 1, 0,
-      0, 0, 0, 1,
-    ]);
-  }
-}

package/src/systems/index.ts

@@ -1,4 +0,0 @@
-export * from "./ActiveSystem.js";
-export * from "./HierarchySystem.js";
-export * from "./TransformSystem.js";
-export * from "./CameraSystem.js";

package/tests/ecs.test.ts

@@ -1,134 +0,0 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import {
-  CommandBuffer,
-  NameComponent,
-  SystemScheduler,
-  TagComponent,
-  TransformComponent,
-  World,
-  deserializeWorld,
-  profileWorld,
-  serializeWorld,
-  type System
-} from "../src/index.js";
-
-class VelocityComponent {
-  constructor(public value: [number, number, number]) {}
-}
-
-test("entities reject stale handles after destroy and reuse", () => {
-  const world = new World();
-  const first = world.createEntity();
-  assert.equal(world.destroyEntity(first), true);
-  const second = world.createEntity();
-
-  assert.equal(first.id, second.id);
-  assert.notEqual(first.generation, second.generation);
-  assert.throws(() => world.get(first, NameComponent), /not alive/);
-});
-
-test("component registration is deterministic per world", () => {
-  const a = new World();
-  const b = new World();
-  a.registerComponent(TransformComponent);
-  a.registerComponent(NameComponent);
-  b.registerComponent(TransformComponent);
-  b.registerComponent(NameComponent);
-
-  assert.equal(a.registry.require(TransformComponent).id, 0);
-  assert.equal(a.registry.require(NameComponent).id, 1);
-  assert.equal(b.registry.require(TransformComponent).id, 0);
-  assert.equal(b.registry.require(NameComponent).id, 1);
-});
-
-test("query include and exclude masks update after component transitions", () => {
-  const world = new World();
-  const moving = world.createEntity();
-  const named = world.createEntity();
-  world.add(moving, TransformComponent, new TransformComponent());
-  world.add(moving, VelocityComponent, new VelocityComponent([1, 0, 0]));
-  world.add(named, TransformComponent, new TransformComponent());
-  world.add(named, NameComponent, new NameComponent("stationary"));
-
-  assert.deepEqual(world.query({ include: [TransformComponent], exclude: [NameComponent] }).toArray(), [moving]);
-
-  world.remove(moving, VelocityComponent);
-  world.add(moving, NameComponent, new NameComponent("moving"));
-
-  assert.deepEqual(world.query({ include: [TransformComponent], exclude: [NameComponent] }).toArray(), []);
-});
-
-test("command buffer supports create/add/destroy during query iteration", () => {
-  const world = new World();
-  const original = world.createEntity();
-  world.add(original, TransformComponent, new TransformComponent());
-  const commands = new CommandBuffer();
-
-  world.query({ include: [TransformComponent] }).forEach((entity) => {
-    const temp = commands.createEntity();
-    commands.add(temp, TransformComponent, new TransformComponent([1, 2, 3]));
-    commands.destroyEntity(entity);
-  });
-  const created = commands.flush(world);
-
-  assert.equal(created.length, 1);
-  assert.deepEqual(world.query({ include: [TransformComponent] }).toArray(), created);
-  assert.deepEqual(world.get(created[0], TransformComponent)?.position, [1, 2, 3]);
-});
-
-test("system scheduler orders dependencies and rejects cycles", () => {
-  const order: string[] = [];
-  const make = (name: string, after: string[] = []): System => ({
-    name,
-    after,
-    update: () => order.push(name)
-  });
-  const scheduler = new SystemScheduler();
-  scheduler.add(make("input"));
-  scheduler.add(make("movement", ["input"]));
-  scheduler.add(make("commit", ["movement"]));
-
-  assert.deepEqual(scheduler.order().map((system) => system.name), ["input", "movement", "commit"]);
-
-  const cycle = new SystemScheduler();
-  cycle.add(make("a", ["b"]));
-  cycle.add(make("b", ["a"]));
-  assert.throws(() => cycle.order(), /cycle rejected/);
-});
-
-test("world update runs fixed, update, and late phases in explicit order", () => {
-  const world = new World();
-  const order: string[] = [];
-  world.systems.add({ name: "late", phase: "late", update: () => order.push("late") });
-  world.systems.add({ name: "fixed", phase: "fixed", update: () => order.push("fixed") });
-  world.systems.add({ name: "update", phase: "update", update: () => order.push("update") });
-
-  world.update({ deltaTime: 1 / 60, elapsedTime: 1, frame: 1 });
-
-  assert.deepEqual(order, ["fixed", "update", "late"]);
-});
-
-test("ECS serialization roundtrips registered component data and remaps entities", () => {
-  const world = new World();
-  world.registerComponent(TransformComponent);
-  world.registerComponent(NameComponent);
-  const entity = world.createEntity();
-  world.add(entity, TransformComponent, new TransformComponent([1, 2, 3]));
-  world.add(entity, NameComponent, new NameComponent("hero"));
-
-  const { world: restored, remap } = deserializeWorld(serializeWorld(world), [TransformComponent, NameComponent]);
-  const restoredEntity = remap.get(`${entity.id}:${entity.generation}`);
-
-  assert.ok(restoredEntity);
-  assert.deepEqual(restored.get(restoredEntity, TransformComponent), { position: [1, 2, 3], rotation: [0, 0, 0, 1], scale: [1, 1, 1] });
-  assert.deepEqual(restored.get(restoredEntity, NameComponent), { name: "hero" });
-});
-
-test("profiler reports entity and component counts", () => {
-  const world = new World();
-  const entity = world.createEntity();
-  world.add(entity, TagComponent, new TagComponent("player"));
-
-  assert.deepEqual(profileWorld(world).components.map((entry) => [entry.name, entry.count]), [["TagComponent", 1]]);
-});

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "declaration": true,
-    "outDir": "dist",
-    "emitDeclarationOnly": true
-  },
-  "include": ["src/**/*.ts"]
-}