@forgeax/engine-scene 0.1.28 → 0.1.29

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

@@ -0,0 +1,269 @@
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { err, type Handle, ok, type SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Children, compileKeyedSceneAsset, type KeyedSceneCompileContext } from '../index';
+
+const Marker = defineComponent('KeyedSceneMarker', { value: 'i32' });
+const DirectionalLight = defineComponent('DirectionalLight', { shadowFilter: 'f32' });
+
+function register(world: World): void {
+  for (const component of [ChildOf, Children, Marker, DirectionalLight])
+    world.components.register(component).unwrap();
+}
+
+function compile(
+  world: World,
+  handle: Handle<'SceneAsset', 'shared'>,
+  asset: SceneAsset,
+  assets: ReadonlyMap<number, SceneAsset>,
+  handles: ReadonlyMap<string, Handle<'SceneAsset', 'shared'>>,
+): ReturnType<typeof compileKeyedSceneAsset> {
+  const context: KeyedSceneCompileContext = {
+    resolveSource: (source, _parent) => {
+      const child = handles.get(source);
+      return child === undefined ? err({ code: 'missing-source' }) : ok(child);
+    },
+    resolveAsset: (child) => {
+      const value = assets.get(Number(child));
+      return value === undefined ? err({ code: 'missing-asset' }) : ok(value);
+    },
+    stack: new Set([Number(handle)]),
+  };
+  return compileKeyedSceneAsset(world, handle, asset, context);
+}
+
+describe('keyed SceneAsset compiler', () => {
+  it('sorts keys, resolves same-scene and nested addresses, and derives private slots', () => {
+    const world = new World();
+    register(world);
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        'door/slash': { components: { KeyedSceneMarker: { value: 2 } } },
+        leaf: { components: { KeyedSceneMarker: { value: 3 } } },
+      },
+    };
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        z: {
+          components: {
+            KeyedSceneMarker: { value: 1 },
+            ChildOf: { parent: 'root' },
+          },
+        },
+        instance: {
+          components: { ChildOf: { parent: 'root' } },
+          instance: {
+            source: 'child-guid',
+            overrides: [{ target: ['door/slash'], components: { KeyedSceneMarker: { value: 9 } } }],
+          },
+        },
+        root: {
+          components: {
+            KeyedSceneMarker: { value: 0 },
+          },
+        },
+      },
+    };
+    const childHandle = world.allocSharedRef('SceneAsset', child);
+    const parentHandle = world.allocSharedRef('SceneAsset', parent);
+    const result = compile(
+      world,
+      parentHandle,
+      parent,
+      new Map([
+        [Number(childHandle), child],
+        [Number(parentHandle), parent],
+      ]),
+      new Map([['child-guid', childHandle]]),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect([...result.value.keyByLocalId.values()]).toEqual(['root', 'z', 'instance']);
+    expect(result.value.resolveAddress('root')).toBe(0);
+    expect(result.value.resolveAddress(['instance', 'door/slash'])).toBe(3);
+    expect(result.value.asset.mounts?.[0]?.memberCount).toBe(2);
+    expect(result.value.asset.mounts?.[0]?.overrides?.[0]?.localId).toBe(3);
+  });
+
+  it('rejects hierarchy cycles before producing a runtime projection', () => {
+    const world = new World();
+    register(world);
+    const handle = world.allocSharedRef('SceneAsset', { kind: 'scene', entities: {} });
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        a: { components: { ChildOf: { parent: 'b' } } },
+        b: { components: { ChildOf: { parent: 'a' } } },
+      },
+    };
+    const result = compile(world, handle, asset, new Map([[Number(handle), asset]]), new Map());
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toMatchObject({ detail: { reason: 'hierarchy cycle' } });
+  });
+
+  it('rejects hierarchy cycles that cross an instance carrier', () => {
+    const world = new World();
+    register(world);
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: { leaf: { components: {} } },
+    };
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        root: { components: { ChildOf: { parent: 'instance' } } },
+        instance: {
+          components: { ChildOf: { parent: 'root' } },
+          instance: { source: 'child-guid' },
+        },
+      },
+    };
+    const childHandle = world.allocSharedRef('SceneAsset', child);
+    const parentHandle = world.allocSharedRef('SceneAsset', parent);
+    const result = compile(
+      world,
+      parentHandle,
+      parent,
+      new Map([
+        [Number(childHandle), child],
+        [Number(parentHandle), parent],
+      ]),
+      new Map([['child-guid', childHandle]]),
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: { detail: { reason: 'hierarchy cycle' } },
+    });
+  });
+
+  it('rejects a carrier parented to a root in its own child scene', () => {
+    const world = new World();
+    register(world);
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        root: { components: {} },
+        door: { components: { ChildOf: { parent: 'root' } } },
+      },
+    };
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: {
+        outer: {
+          components: { ChildOf: { parent: ['outer', 'door'] } },
+          instance: { source: 'child-guid' },
+        },
+      },
+    };
+    const childHandle = world.allocSharedRef('SceneAsset', child);
+    const parentHandle = world.allocSharedRef('SceneAsset', parent);
+    const result = compile(
+      world,
+      parentHandle,
+      parent,
+      new Map([
+        [Number(childHandle), child],
+        [Number(parentHandle), parent],
+      ]),
+      new Map([['child-guid', childHandle]]),
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: { detail: { reason: 'hierarchy cycle' } },
+    });
+  });
+
+  it('keeps every segment of a deeply nested address', () => {
+    const world = new World();
+    register(world);
+    const leaf: SceneAsset = { kind: 'scene', entities: { door: { components: {} } } };
+    const inside: SceneAsset = {
+      kind: 'scene',
+      entities: { inside: { components: {}, instance: { source: 'leaf-guid' } } },
+    };
+    const outer: SceneAsset = {
+      kind: 'scene',
+      entities: { outer: { components: {}, instance: { source: 'inside-guid' } } },
+    };
+    const leafHandle = world.allocSharedRef('SceneAsset', leaf);
+    const insideHandle = world.allocSharedRef('SceneAsset', inside);
+    const outerHandle = world.allocSharedRef('SceneAsset', outer);
+    const result = compile(
+      world,
+      outerHandle,
+      outer,
+      new Map([
+        [Number(leafHandle), leaf],
+        [Number(insideHandle), inside],
+        [Number(outerHandle), outer],
+      ]),
+      new Map([
+        ['leaf-guid', leafHandle],
+        ['inside-guid', insideHandle],
+      ]),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.resolveAddress(['outer', 'inside', 'door'])).toBe(2);
+  });
+
+  it('rejects unknown component fields before runtime projection', () => {
+    const world = new World();
+    register(world);
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: { root: { components: { KeyedSceneMarker: { typo: 1 } } } },
+    };
+    const handle = world.allocSharedRef('SceneAsset', asset);
+    const result = compile(world, handle, asset, new Map([[Number(handle), asset]]), new Map());
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        detail: {
+          reason: 'unknown component field',
+          component: 'KeyedSceneMarker',
+          field: 'typo',
+          entity: 'root',
+        },
+      },
+    });
+  });
+
+  it('migrates numeric 0.1.27 entity addresses and pcfKernelSize at compile time', () => {
+    const world = new World();
+    register(world);
+    const asset = {
+      kind: 'scene',
+      entities: {
+        '0': { components: { KeyedSceneMarker: { value: 0 } } },
+        '1': {
+          components: {
+            ChildOf: { parent: 0 },
+            DirectionalLight: { pcfKernelSize: 3 },
+          },
+        },
+      },
+    } as unknown as SceneAsset;
+    const handle = world.allocSharedRef('SceneAsset', asset);
+    const result = compile(world, handle, asset, new Map([[Number(handle), asset]]), new Map());
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        asset: {
+          entities: [
+            { components: { KeyedSceneMarker: { value: 0 } } },
+            {
+              components: {
+                ChildOf: { parent: 0 },
+                DirectionalLight: { shadowFilter: 2 },
+              },
+            },
+          ],
+        },
+      },
+    });
+  });
+});

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

@@ -5,61 +5,80 @@ import {
   resolveSceneEntity,
   type SceneEntityRef,
   sceneEntity,
-  validateSceneBindings,
+  sceneEntityAddressKey,
+  validateSceneEntityKeys,
 } from '../instances/binding.js';
 import { externalizeSceneAsset } from '../instances/externalization.js';
 
-describe('SceneEntityRef instance binding', () => {
-  it('resolves by scene sourceKey and bindingKey, not display name', () => {
+describe('SceneEntityRef instance address', () => {
+  const bindings = (address: SceneEntityRef['address'], value: number) =>
+    new Map([[sceneEntityAddressKey(address), value]]);
+
+  it('resolves by scene source and authored entity address', () => {
     const ref: SceneEntityRef = sceneEntity('level/main', 'player');
     const first = resolveSceneEntity(ref, {
       sceneSourceKey: 'level/main',
-      bindings: new Map([['player', 11]]),
+      bindings: bindings('player', 11),
     });
     const second = resolveSceneEntity(ref, {
       sceneSourceKey: 'level/main',
-      bindings: new Map([['player', 22]]),
+      bindings: bindings('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', () => {
+  it('rejects a missing or cross-instance address with a closed error', () => {
     const result = resolveSceneEntity(sceneEntity('level/main', 'camera'), {
       sceneSourceKey: 'level/main',
-      bindings: new Map([['player', 11]]),
+      bindings: bindings('player', 11),
     });
 
     expect(result).toMatchObject({
       ok: false,
       error: {
         code: 'scene-binding-missing',
-        expected: expect.stringContaining('bindingKey'),
+        expected: expect.stringContaining('entity key'),
         hint: expect.stringContaining('declare'),
-        detail: { sceneSourceKey: 'level/main', bindingKey: 'camera' },
+        detail: { sceneSourceKey: 'level/main', address: 'camera' },
       },
     });
   });
 
   it('rejects a reference from another concrete SceneInstance', () => {
-    const ref = sceneEntity('level/other', 'player');
-    const result = resolveSceneEntity(ref, {
+    const result = resolveSceneEntity(sceneEntity('level/other', 'player'), {
       sceneSourceKey: 'level/main',
-      bindings: new Map([['player', 11]]),
+      bindings: bindings('player', 11),
     });
 
     expect(result).toMatchObject({
       ok: false,
       error: {
         code: 'scene-binding-wrong-instance',
-        detail: { sceneSourceKey: 'level/other', bindingKey: 'player' },
+        detail: { sceneSourceKey: 'level/other', address: 'player' },
       },
     });
   });
 
-  it('rejects duplicate declarations before an instance can publish bindings', () => {
-    const result = validateSceneBindings('level/main', ['player', 'player']);
+  it('requires an explicit anonymous source key for direct POD scenes', () => {
+    const anonymous = resolveSceneEntity(sceneEntity('', 'player'), {
+      sceneSourceKey: '',
+      bindings: bindings('player', 11),
+    });
+    const fabricated = resolveSceneEntity(sceneEntity('unrelated/source', 'player'), {
+      sceneSourceKey: '',
+      bindings: bindings('player', 11),
+    });
+    expect(anonymous).toEqual({ ok: true, value: 11 });
+    expect(fabricated).toMatchObject({
+      ok: false,
+      error: { code: 'scene-binding-wrong-instance' },
+    });
+  });
+
+  it('rejects duplicate authored entity keys before publication', () => {
+    const result = validateSceneEntityKeys('level/main', ['player', 'player']);
 
     expect(result).toMatchObject({
       ok: false,
@@ -67,31 +86,57 @@ describe('SceneEntityRef instance binding', () => {
         code: 'scene-binding-duplicate',
         expected: expect.stringContaining('unique'),
         hint: expect.stringContaining('rename'),
-        detail: { sceneSourceKey: 'level/main', bindingKey: 'player' },
+        detail: { sceneSourceKey: 'level/main', address: 'player' },
       },
     });
   });
 
-  it('keeps binding identity stable when the display name or source path changes', () => {
-    const ref = sceneEntity('level/main', 'player');
-    const result = resolveSceneEntity(ref, {
+  it('supports nested addresses without using display names or paths', () => {
+    const ref = sceneEntity('level/main', ['house', 'door']);
+    expect(ref).toEqual({ sceneSourceKey: 'level/main', address: ['house', 'door'] });
+    expect(ref).not.toHaveProperty('name');
+    expect(ref).not.toHaveProperty('path');
+  });
+
+  it('treats a one-segment address array as the same direct key', () => {
+    const direct = resolveSceneEntity(sceneEntity('level/main', 'player'), {
+      sceneSourceKey: 'level/main',
+      bindings: bindings('player', 11),
+    });
+    const array = resolveSceneEntity(sceneEntity('level/main', ['player']), {
       sceneSourceKey: 'level/main',
-      bindings: new Map([['player', 11]]),
+      bindings: bindings(['player'], 11),
     });
+    expect(direct).toEqual({ ok: true, value: 11 });
+    expect(array).toEqual(direct);
+  });
 
-    expect(result).toEqual({ ok: true, value: 11 });
-    expect(ref).not.toHaveProperty('name');
-    expect(ref).not.toHaveProperty('path');
+  it('keeps literal and nested addresses distinct', () => {
+    const literal = '["house","door"]';
+    const nested = ['house', 'door'] as const;
+    const map = new Map([
+      [sceneEntityAddressKey(literal), 11],
+      [sceneEntityAddressKey(nested), 22],
+    ]);
+    const literalResult = resolveSceneEntity(sceneEntity('level/main', literal), {
+      sceneSourceKey: 'level/main',
+      bindings: map,
+    });
+    const nestedResult = resolveSceneEntity(sceneEntity('level/main', nested), {
+      sceneSourceKey: 'level/main',
+      bindings: map,
+    });
+    expect(literalResult).toEqual({ ok: true, value: 11 });
+    expect(nestedResult).toEqual({ ok: true, value: 22 });
   });
 
-  it('preserves scene source and binding metadata through decode and externalization', async () => {
+  it('preserves keyed scene data 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: {} }],
+        entities: { player: { components: {} } },
       },
       refs: [],
       artifacts: {},
@@ -103,22 +148,86 @@ describe('SceneEntityRef instance binding', () => {
     });
     expect(decoded).toMatchObject({
       ok: true,
-      value: {
-        sourceKey: 'world/main',
-        entities: [{ bindingKey: 'player' }],
-      },
+      value: { entities: { player: { components: {} } } },
     });
     if (!decoded.ok) return;
 
     const externalized = externalizeSceneAsset(decoded.value, () => ({}));
+    expect(externalized).toMatchObject({
+      ok: true,
+      value: { payload: { entities: { player: { components: {} } } } },
+    });
+  });
+
+  it('keeps legacy binding keys when decoding an array SceneAsset', async () => {
+    const envelope = {
+      guid: '00000000-0000-0000-0000-000000000022',
+      kind: 'scene',
+      payload: {
+        kind: 'scene' as const,
+        entities: [
+          { localId: 0, bindingKey: 'root', components: {} },
+          { localId: 1, bindingKey: 'player', components: { ChildOf: { parent: 0 } } },
+        ],
+      },
+      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: {
+        entities: {
+          root: { components: {} },
+          player: { components: { ChildOf: { parent: 'root' } } },
+        },
+      },
+    });
+  });
+
+  it('migrates the 0.1.27 numeric template fields at the externalization boundary', () => {
+    const legacy = {
+      kind: 'scene',
+      entities: [
+        { localId: 0, components: { Name: { value: 'Root' } } },
+        {
+          localId: 1,
+          components: {
+            ChildOf: { parent: 0 },
+            DirectionalLight: { pcfKernelSize: 3 },
+          },
+        },
+      ],
+    } as unknown as import('@forgeax/engine-types').SceneAsset;
+    const externalized = externalizeSceneAsset(legacy, (componentName) => {
+      if (componentName === 'ChildOf') return { parent: 'entity' };
+      if (componentName === 'DirectionalLight') {
+        return { pcfKernelSize: 'f32', shadowFilter: 'f32' };
+      }
+      return {};
+    });
     expect(externalized).toMatchObject({
       ok: true,
       value: {
         payload: {
-          sourceKey: 'world/main',
-          entities: [{ bindingKey: 'player' }],
+          entities: {
+            '1': {
+              components: {
+                ChildOf: { parent: '0' },
+                DirectionalLight: { shadowFilter: 2 },
+              },
+            },
+          },
         },
       },
     });
+    if (!externalized.ok) return;
+    expect(externalized.value.payload.entities).not.toHaveProperty(
+      '1.components.DirectionalLight.pcfKernelSize',
+    );
   });
 });

package/src/__tests__/structural.test.ts

@@ -15,7 +15,10 @@ describe('SceneInstance structure characterization', () => {
       hasWorldStateWeakMap: source.includes('const sceneWorldStates = new WeakMap'),
     };
 
-    expect(snapshot.lines).toBeLessThan(1564);
+    // The keyed authoring compiler lives in keyed.ts; this is the post-migration
+    // runtime projection baseline, with a small guard against re-growing the
+    // former numeric/mount implementation.
+    expect(snapshot.lines).toBeLessThan(1700);
     expect(snapshot.exportedFunctions).toBe(27);
     expect(snapshot.hasStatePayload).toBe(false);
     expect(snapshot.hasWorldStateWeakMap).toBe(false);