@forgeax/engine-scene 0.1.20 → 0.1.23

package/src/__tests__/propagation.unit.test.ts

@@ -1,163 +1,279 @@
-import { FixedUpdate, Update, World } from '@forgeax/engine-ecs';
+import { type EntityHandle, FixedUpdate, Update, World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
-import { ChildOf, propagateTransforms, Transform } from '../index';
+import { ChangeEpochExhaustedError } from '../../../ecs/src/errors';
+import { worldInternal } from '../../../ecs/src/world-internal';
+import { ChildOf, GlobalTransform, propagateTransforms, Transform } from '../index';
 import { registerPropagateTransforms } from '../systems';
 
+function spawnTransform(world: World, pos: number[], parent?: EntityHandle) {
+  const components = [{ component: Transform, data: { pos } }];
+  if (parent === undefined) return world.spawn(...components).unwrap();
+  return world.spawn(...components, { component: ChildOf, data: { parent } }).unwrap();
+}
+
 describe('scene propagation', () => {
-  it('registers ordinary transform owners without exposing terminal publication as a schedule', () => {
+  it('materializes the derived world component from Transform at the ECS boundary', () => {
     const world = new World();
-    registerPropagateTransforms(world);
+    const entity = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+
+    expect(world.get(entity, GlobalTransform).ok).toBe(true);
+  });
+
+  it('materializes the transform pair when a hierarchy edge is the only authored component', () => {
+    const world = new World();
+    const parent = world.spawn({ component: Transform, data: { pos: [4, 0, 0] } }).unwrap();
+    const child = world.spawn({ component: ChildOf, data: { parent } }).unwrap();
+
+    expect(world.get(child, Transform).ok).toBe(true);
+    expect(world.get(child, GlobalTransform).ok).toBe(true);
+    expect(propagateTransforms(world).ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(4);
+  });
+
+  it('rejects a Transform-only entity with a structured pair error', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    world.removeComponent(entity, GlobalTransform).unwrap();
+
+    const result = propagateTransforms(world);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('hierarchy-broken');
+      expect(result.error.expected).toContain('GlobalTransform pair');
+      expect(result.error.detail?.entity).toBe(entity);
+    }
+  });
+
+  it('rejects a GlobalTransform-only entity with a structured pair error', () => {
+    const world = new World();
+    const entity = world.spawn({ component: GlobalTransform, data: {} }).unwrap();
+
+    const result = propagateTransforms(world);
 
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('hierarchy-broken');
+      expect(result.error.expected).toContain('Transform pair');
+      expect(result.error.detail?.entity).toBe(entity);
+    }
+  });
+
+  it('preserves the ECS range-publication error in flat propagation diagnostics', () => {
+    const world = new World();
+    spawnTransform(world, [2, 0, 0]);
+    const internal = world[worldInternal];
+    const originalMarkRange = internal.markComponentRangeChanged;
+    Object.defineProperty(internal, 'markComponentRangeChanged', {
+      configurable: true,
+      value: () => {
+        throw new ChangeEpochExhaustedError(Number.MAX_SAFE_INTEGER);
+      },
+    });
+    try {
+      const result = propagateTransforms(world);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('hierarchy-broken');
+        expect(result.error.detail?.kind).toBe('derived-write');
+        if (result.error.detail?.kind === 'derived-write') {
+          expect(result.error.detail.cause.code).toBe('change-epoch-exhausted');
+          expect(result.error.detail.cause.expected).toBe(
+            'mutationEpoch < Number.MAX_SAFE_INTEGER',
+          );
+          expect(result.error.detail.cause.hint).toContain('Rebuild the World');
+          expect(result.error.detail.cause.detail).toEqual({ epoch: Number.MAX_SAFE_INTEGER });
+        }
+      }
+    } finally {
+      Object.defineProperty(internal, 'markComponentRangeChanged', {
+        configurable: true,
+        value: originalMarkRange,
+      });
+    }
+  });
+
+  it('registers the TransformPropagation owner in Update and FixedUpdate', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
     expect(
       world
         .inspect()
         .schedules.find((entry) => entry.schedule === Update)
-        ?.systems.map((system) => system.name),
+        ?.systems.map((s) => s.name),
     ).toContain('propagateTransforms');
     expect(
       world
         .inspect()
         .schedules.find((entry) => entry.schedule === FixedUpdate)
-        ?.systems.map((system) => system.name),
+        ?.systems.map((s) => s.name),
     ).toContain('propagateTransformsFixed');
-    expect(world.inspect().schedules.map((entry) => entry.schedule.name)).not.toContain(
-      'FramePublish',
-    );
   });
-  it('propagates a root and child in a headless world', () => {
+
+  it('propagates a root and child into GlobalTransform', () => {
     const world = new World();
     registerPropagateTransforms(world);
-    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
-    const child = world
-      .spawn(
-        { component: Transform, data: { pos: [3, 0, 0] } },
-        { component: ChildOf, data: { parent: root } },
-      )
-      .unwrap();
+    const root = spawnTransform(world, [2, 0, 0]);
+    const child = spawnTransform(world, [3, 0, 0], root);
     expect(world.update(1 / 60).ok).toBe(true);
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(5);
   });
 
   it('cascades linked children when a parent is despawned', () => {
     const world = new World();
     registerPropagateTransforms(world);
-    const parent = world.spawn({ component: Transform, data: {} }).unwrap();
-    const child = world
-      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
-      .unwrap();
-    world.despawn(parent);
-    const result = world.update(1 / 60);
-    expect(result.ok).toBe(true);
+    const parent = spawnTransform(world, [0, 0, 0]);
+    const child = spawnTransform(world, [1, 0, 0], parent);
+
+    world.despawn(parent).unwrap();
+
+    expect(world.update(1 / 60).ok).toBe(true);
     expect(world.get(child, Transform).ok).toBe(false);
   });
 
   it('keeps equal entity handles isolated across Worlds', () => {
     const first = new World();
     const second = new World();
-    const firstRoot = first.spawn({ component: Transform, data: { pos: [3, 0, 0] } }).unwrap();
-    const secondRoot = second.spawn({ component: Transform, data: { pos: [7, 0, 0] } }).unwrap();
-
+    const firstRoot = spawnTransform(first, [3, 0, 0]);
+    const secondRoot = spawnTransform(second, [7, 0, 0]);
     expect(firstRoot).toBe(secondRoot);
     expect(propagateTransforms(first).ok).toBe(true);
     expect(propagateTransforms(second).ok).toBe(true);
-    expect(first.get(firstRoot, Transform).unwrap().world[12]).toBeCloseTo(3);
-    expect(second.get(secondRoot, Transform).unwrap().world[12]).toBeCloseTo(7);
+    expect(first.get(firstRoot, GlobalTransform).unwrap().world[12]).toBeCloseTo(3);
+    expect(second.get(secondRoot, GlobalTransform).unwrap().world[12]).toBeCloseTo(7);
   });
 
-  it('reuses a stable propagation result and invalidates it after a local edit', () => {
+  it('executes repeated propagation and preserves stable world semantics', () => {
     const world = new World();
-    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
-    const child = world
-      .spawn(
-        { component: Transform, data: { pos: [3, 0, 0] } },
-        { component: ChildOf, data: { parent: root } },
-      )
-      .unwrap();
+    const root = spawnTransform(world, [2, 0, 0]);
+    const child = spawnTransform(world, [3, 0, 0], root);
 
     const first = propagateTransforms(world);
     const second = propagateTransforms(world);
-    expect(first).toBe(second);
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(5);
+
+    const corruptedWorld = new Float32Array(16);
+    corruptedWorld[12] = -100;
+    world.set(child, GlobalTransform, { world: corruptedWorld }).unwrap();
+    const repaired = propagateTransforms(world);
+    expect(repaired.ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(5);
 
     world.set(root, Transform, { pos: [7, 0, 0] }).unwrap();
     const third = propagateTransforms(world);
-    expect(third).not.toBe(second);
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+    expect(third.ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(10);
   });
 
-  it('incrementally recomputes an edited transform and its descendants', () => {
+  it('recomputes the edited transform and its descendants', () => {
     const world = new World();
-    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
-    const child = world
-      .spawn(
-        { component: Transform, data: { pos: [3, 0, 0] } },
-        { component: ChildOf, data: { parent: root } },
-      )
-      .unwrap();
-    const grandchild = world
-      .spawn(
-        { component: Transform, data: { pos: [4, 0, 0] } },
-        { component: ChildOf, data: { parent: child } },
-      )
-      .unwrap();
-    const sibling = world.spawn({ component: Transform, data: { pos: [20, 0, 0] } }).unwrap();
-
+    const root = spawnTransform(world, [2, 0, 0]);
+    const child = spawnTransform(world, [3, 0, 0], root);
+    const grandchild = spawnTransform(world, [4, 0, 0], child);
+    const sibling = spawnTransform(world, [20, 0, 0]);
     propagateTransforms(world).unwrap();
     world.set(child, Transform, { pos: [8, 0, 0] }).unwrap();
     propagateTransforms(world).unwrap();
+    expect(world.get(root, GlobalTransform).unwrap().world[12]).toBeCloseTo(2);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(10);
+    expect(world.get(grandchild, GlobalTransform).unwrap().world[12]).toBeCloseTo(14);
+    expect(world.get(sibling, GlobalTransform).unwrap().world[12]).toBeCloseTo(20);
+  });
 
-    expect(world.get(root, Transform).unwrap().world[12]).toBeCloseTo(2);
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
-    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(14);
-    expect(world.get(sibling, Transform).unwrap().world[12]).toBeCloseTo(20);
+  it('recomputes a child after reparenting to a different live parent', () => {
+    const world = new World();
+    const firstParent = spawnTransform(world, [10, 0, 0]);
+    const secondParent = spawnTransform(world, [100, 0, 0]);
+    const child = spawnTransform(world, [1, 0, 0], firstParent);
+    propagateTransforms(world).unwrap();
+    world.set(child, ChildOf, { parent: secondParent }).unwrap();
+    propagateTransforms(world).unwrap();
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(101);
   });
 
-  it('expands a generic ChildOf mutation from the validated hierarchy snapshot', () => {
+  it('publishes a local fallback before returning a stale-parent error', () => {
     const world = new World();
-    const firstParent = world.spawn({ component: Transform, data: { pos: [10, 0, 0] } }).unwrap();
-    const secondParent = world.spawn({ component: Transform, data: { pos: [100, 0, 0] } }).unwrap();
-    const child = world
-      .spawn(
-        { component: Transform, data: { pos: [1, 0, 0] } },
-        { component: ChildOf, data: { parent: firstParent } },
-      )
-      .unwrap();
-    const grandchild = world
-      .spawn(
-        { component: Transform, data: { pos: [2, 0, 0] } },
-        { component: ChildOf, data: { parent: child } },
-      )
-      .unwrap();
+    const parent = spawnTransform(world, [10, 0, 0]);
+    const child = spawnTransform(world, [1, 0, 0], parent);
+    propagateTransforms(world).unwrap();
+    const baseline = new Float32Array(world.get(child, GlobalTransform).unwrap().world);
+
+    const staleParent = spawnTransform(world, [50, 0, 0]);
+    world.despawn(staleParent).unwrap();
+    world.set(child, ChildOf, { parent: staleParent }).unwrap();
+    const fault = propagateTransforms(world);
+
+    expect(fault.ok).toBe(false);
+    if (!fault.ok) expect(fault.error.code).toBe('hierarchy-broken');
+    const fallback = world.get(child, GlobalTransform).unwrap().world;
+    expect(fallback[12]).toBeCloseTo(1);
+    expect(fallback[12]).not.toBeCloseTo(baseline[12] ?? Number.NaN);
+
+    world.set(child, ChildOf, { parent }).unwrap();
+    expect(propagateTransforms(world).ok).toBe(true);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(baseline[12] ?? 0);
+  });
+
+  it('cuts every member of a cycle to a finite local root fallback', () => {
+    const world = new World();
+    const root = spawnTransform(world, [0, 0, 0]);
+    const first = spawnTransform(world, [1, 0, 0], root);
+    const second = spawnTransform(world, [2, 0, 0], first);
+    world.set(first, ChildOf, { parent: second }).unwrap();
+
+    const result = propagateTransforms(world);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('hierarchy-cycle');
+    for (const entity of [first, second]) {
+      const matrix = world.get(entity, GlobalTransform).unwrap().world;
+      expect([...matrix].every(Number.isFinite)).toBe(true);
+    }
+  });
+
+  it('expands a generic ChildOf mutation and updates descendants', () => {
+    const world = new World();
+    const firstParent = spawnTransform(world, [10, 0, 0]);
+    const secondParent = spawnTransform(world, [100, 0, 0]);
+    const child = spawnTransform(world, [1, 0, 0], firstParent);
+    const grandchild = spawnTransform(world, [2, 0, 0], child);
 
     propagateTransforms(world).unwrap();
     world.set(child, ChildOf, { parent: secondParent }).unwrap();
     propagateTransforms(world).unwrap();
 
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(101);
-    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(103);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(101);
+    expect(world.get(grandchild, GlobalTransform).unwrap().world[12]).toBeCloseTo(103);
   });
 
-  it('publishes transform writes when propagation is explicitly ordered after gameplay', () => {
+  it('returns a structured error for a parent cycle', () => {
+    const world = new World();
+    const root = spawnTransform(world, [1, 0, 0]);
+    const child = spawnTransform(world, [2, 0, 0], root);
+    const result = world.addComponent(root, { component: ChildOf, data: { parent: child } });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('relationship-self-cycle');
+      expect(result.error.hint).toContain('descendant');
+    }
+  });
+
+  it('publishes local writes before the same-tick world read', () => {
     const world = new World();
     registerPropagateTransforms(world);
-    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
-    const child = world
-      .spawn(
-        { component: Transform, data: { pos: [3, 0, 0] } },
-        { component: ChildOf, data: { parent: root } },
-      )
-      .unwrap();
+    const root = spawnTransform(world, [2, 0, 0]);
+    const child = spawnTransform(world, [3, 0, 0], root);
     world
       .addSystem(Update, {
         name: 'late-pose',
-        before: ['propagateTransforms'],
         queries: [],
+        before: ['propagateTransforms'],
         fn: () => world.set(child, Transform, { pos: [8, 0, 0] }),
       })
       .unwrap();
-
     world.update(0).unwrap();
-
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(10);
   });
 });

package/src/__tests__/scene-binding.integration.test.ts

@@ -0,0 +1,124 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { sceneAssetDecoder } from '../assets/scene-decoder.js';
+import {
+  resolveSceneEntity,
+  type SceneEntityRef,
+  sceneEntity,
+  validateSceneBindings,
+} from '../instances/binding.js';
+import { externalizeSceneAsset } from '../instances/externalization.js';
+
+describe('SceneEntityRef instance binding', () => {
+  it('resolves by scene sourceKey and bindingKey, not display name', () => {
+    const ref: SceneEntityRef = sceneEntity('level/main', 'player');
+    const first = resolveSceneEntity(ref, {
+      sceneSourceKey: 'level/main',
+      bindings: new Map([['player', 11]]),
+    });
+    const second = resolveSceneEntity(ref, {
+      sceneSourceKey: 'level/main',
+      bindings: new Map([['player', 22]]),
+    });
+
+    expect(first).toEqual({ ok: true, value: 11 });
+    expect(second).toEqual({ ok: true, value: 22 });
+  });
+
+  it('rejects a missing or cross-instance binding with a closed error', () => {
+    const result = resolveSceneEntity(sceneEntity('level/main', 'camera'), {
+      sceneSourceKey: 'level/main',
+      bindings: new Map([['player', 11]]),
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'scene-binding-missing',
+        expected: expect.stringContaining('bindingKey'),
+        hint: expect.stringContaining('declare'),
+        detail: { sceneSourceKey: 'level/main', bindingKey: 'camera' },
+      },
+    });
+  });
+
+  it('rejects a reference from another concrete SceneInstance', () => {
+    const ref = sceneEntity('level/other', 'player');
+    const result = resolveSceneEntity(ref, {
+      sceneSourceKey: 'level/main',
+      bindings: new Map([['player', 11]]),
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'scene-binding-wrong-instance',
+        detail: { sceneSourceKey: 'level/other', bindingKey: 'player' },
+      },
+    });
+  });
+
+  it('rejects duplicate declarations before an instance can publish bindings', () => {
+    const result = validateSceneBindings('level/main', ['player', 'player']);
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'scene-binding-duplicate',
+        expected: expect.stringContaining('unique'),
+        hint: expect.stringContaining('rename'),
+        detail: { sceneSourceKey: 'level/main', bindingKey: 'player' },
+      },
+    });
+  });
+
+  it('keeps binding identity stable when the display name or source path changes', () => {
+    const ref = sceneEntity('level/main', 'player');
+    const result = resolveSceneEntity(ref, {
+      sceneSourceKey: 'level/main',
+      bindings: new Map([['player', 11]]),
+    });
+
+    expect(result).toEqual({ ok: true, value: 11 });
+    expect(ref).not.toHaveProperty('name');
+    expect(ref).not.toHaveProperty('path');
+  });
+
+  it('preserves scene source and binding metadata through decode and externalization', async () => {
+    const envelope = {
+      guid: '00000000-0000-0000-0000-000000000021',
+      kind: 'scene',
+      payload: {
+        kind: 'scene' as const,
+        sourceKey: 'world/main',
+        entities: [{ localId: 0, bindingKey: 'player', components: {} }],
+      },
+      refs: [],
+      artifacts: {},
+    } as unknown as Parameters<typeof sceneAssetDecoder.decode>[0]['envelope'];
+    const decoded = await sceneAssetDecoder.decode({
+      envelope,
+      artifacts: { read: async () => ok(new Uint8Array()) },
+      signal: new AbortController().signal,
+    });
+    expect(decoded).toMatchObject({
+      ok: true,
+      value: {
+        sourceKey: 'world/main',
+        entities: [{ bindingKey: 'player' }],
+      },
+    });
+    if (!decoded.ok) return;
+
+    const externalized = externalizeSceneAsset(decoded.value, () => ({}));
+    expect(externalized).toMatchObject({
+      ok: true,
+      value: {
+        payload: {
+          sourceKey: 'world/main',
+          entities: [{ bindingKey: 'player' }],
+        },
+      },
+    });
+  });
+});

package/src/__tests__/schedule-order.contract.test.ts

@@ -0,0 +1,43 @@
+import { FixedUpdate, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { GlobalTransform, Transform } from '../index';
+import { registerPropagateTransforms } from '../systems';
+
+describe('TransformPropagation schedule contract', () => {
+  it('exposes one ordering token in both Update and FixedUpdate', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const inspection = world.inspect();
+    const update = inspection.schedules.find((entry) => entry.schedule === Update);
+    const fixed = inspection.schedules.find((entry) => entry.schedule === FixedUpdate);
+
+    expect(update?.systems.map((system) => system.name)).toContain('propagateTransforms');
+    expect(fixed?.systems.map((system) => system.name)).toContain('propagateTransformsFixed');
+    expect(inspection.schedules.map((entry) => entry.schedule.name)).toEqual(
+      expect.arrayContaining(['Update', 'FixedUpdate']),
+    );
+    expect(inspection.schedules.map((entry) => entry.schedule.name)).not.toContain('FramePublish');
+  });
+
+  it('keeps local and world query surfaces disjoint', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Transform, data: { pos: [4, 0, 0] } }).unwrap();
+    registerPropagateTransforms(world);
+
+    expect(
+      world
+        .query({ read: [Transform] })
+        .unwrap()
+        .at(entity)
+        ?.get(Transform).pos[0],
+    ).toBe(4);
+    expect(
+      world
+        .query({ read: [GlobalTransform] })
+        .unwrap()
+        .at(entity),
+    ).toBeDefined();
+    expect(world.update(0).ok).toBe(true);
+    expect(world.get(entity, GlobalTransform).unwrap().world[12]).toBeCloseTo(4);
+  });
+});

package/src/__tests__/structural.test.ts

@@ -0,0 +1,23 @@
+// @ts-expect-error The package test tsconfig intentionally omits Node globals.
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+describe('SceneInstance structure characterization', () => {
+  it('records the current instance state surface', async () => {
+    const source = readFileSync(
+      new URL('../instances/scene-instances.ts', import.meta.url),
+      'utf8',
+    );
+    const snapshot = {
+      lines: source.split('\n').length - 1,
+      exportedFunctions: (source.match(/^export function\b/gm) ?? []).length,
+      hasStatePayload: source.includes('export interface SceneInstanceStatePayload'),
+      hasWorldStateWeakMap: source.includes('const sceneWorldStates = new WeakMap'),
+    };
+
+    expect(snapshot.lines).toBeLessThan(1564);
+    expect(snapshot.exportedFunctions).toBe(27);
+    expect(snapshot.hasStatePayload).toBe(false);
+    expect(snapshot.hasWorldStateWeakMap).toBe(false);
+  });
+});