@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/scene-mount-wrapper-roundtrip.test.ts

@@ -1,202 +1,56 @@
-// scene-mount-wrapper-roundtrip.test.ts — regression for the editor "Add to
-// Scene" ghost-node accretion bug.
-//
-// The editor's whole-GLB Add-to-Scene (spawnGlbSceneAsMount) produces a scene
-// pack shaped like:
-//     entities: [ ..., { localId: W, Name:"bed.glb", Transform, Children:[M] } ]
-//     mounts:   [ { localId: M, source: <bedGUID>, memberCount: N, parent: W } ]
-// i.e. an OWNED wrapper entity whose child is a nested mount. This is the exact
-// on-disk shape after the first add+save.
-//
-// On RELOAD, world.instantiateScene re-materialises the mount as a plain "mount
-// entity" (no Name, no SceneInstance — just Transform/ChildOf/Children) sitting
-// BETWEEN the wrapper and the child SceneInstance root. On the NEXT collect that
-// plain mount entity carries no SceneInstance, so rootsToSceneAsset emitted it
-// as an OWNED (nameless) entity + a fresh mount — one extra ghost node per
-// save→reload cycle. This test asserts collect is a FIXED POINT across two
-// reload cycles.
-
 import type { Asset } from '@forgeax/engine-assets-runtime';
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { Children, Name, Transform } from '@forgeax/engine-scene';
+import { SceneInstance } from '@forgeax/engine-render';
 import type { Handle, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { rootsToSceneAsset, serializeSceneAssetToPack } from '../collect-scene-asset';
+import { rootsToSceneAsset } from '../collect-scene-asset';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerSceneComponents } from './helpers/register-scene-components';
 
-const G_CHILD = '11111111-1111-4111-8111-111111111111';
-const G_TOP = '22222222-2222-4222-8222-222222222222';
-
-function mkReg(): AssetRegistry {
-  return new AssetRegistry(makeMockShaderRegistry());
-}
-function pg(s: string): AssetGuid {
-  const r = AssetGuid.parse(s);
-  if (!r.ok) throw new Error(`bad GUID: ${s}`);
-  return r.value;
-}
-function cat(reg: AssetRegistry, g: string, p: SceneAsset): void {
-  reg.catalog(pg(g), p as Asset);
-}
-function rs(w: World, a: SceneAsset): Handle<'SceneAsset', 'shared'> {
-  registerSceneComponents(w, [Name]);
-  return w.allocSharedRef('SceneAsset', a);
-}
-function accessParse(reg: AssetRegistry) {
-  const internal = reg as unknown as {
-    parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): unknown;
-  };
-  return (payload: Record<string, unknown>, refs?: readonly string[]): SceneAsset =>
-    internal.parseAssetPayload('scene', payload, refs as string[] | undefined) as SceneAsset;
+const CHILD = '11111111-1111-4111-8111-111111111111';
+function guid(value: string): AssetGuid {
+  const result = AssetGuid.parse(value);
+  if (!result.ok) throw new Error(`bad GUID: ${value}`);
+  return result.value;
 }
-function unpack(pack: Record<string, unknown>): {
-  payload: Record<string, unknown>;
-  refs: readonly string[] | undefined;
-} {
-  const a = (pack.assets as Record<string, unknown>[])[0] as Record<string, unknown>;
-  return { payload: a.payload as Record<string, unknown>, refs: a.refs as string[] | undefined };
+function makeHandle(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  registerSceneComponents(world);
+  return world.allocSharedRef('SceneAsset', asset);
 }
 
-describe('editor Add-to-Scene wrapper+mount round-trip (ghost accretion regression)', () => {
-  it('collect is a fixed point across reload cycles (no nameless ghost accretes)', () => {
-    const reg = mkReg();
-    const w = new World();
-
-    // Child scene = the "bed": one owned mesh entity.
+describe('keyed instance wrapper collect', () => {
+  it('collect preserves the wrapper key, source and explicit parent declaration', () => {
+    const registry = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
     const child: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: 0 as never,
-          components: { Name: { value: 'bed-mesh' }, Transform: { pos: [0, 0, 0] } },
-        },
-      ],
+      entities: { leaf: { components: { Transform: {} } } },
     };
-    cat(reg, G_CHILD, child);
-
-    // Plain top scene with ONE owned entity (like spin-cube's Ground). The
-    // editor adds the mount live below via a wrapper (no mounts[] on disk yet).
-    const top: SceneAsset = {
+    expect(registry.catalog(guid(CHILD), child as Asset).ok).toBe(true);
+    const parent: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: 0 as never,
-          components: { Name: { value: 'Ground' }, Transform: { pos: [0, 0, 0] } },
+      entities: {
+        root: { components: { Transform: {} } },
+        wrapper: {
+          components: { ChildOf: { parent: 'root' } },
+          instance: { source: CHILD },
         },
-      ],
+      },
     };
-    cat(reg, G_TOP, top);
-
-    const parse = accessParse(reg);
-
-    const runCycle = (roots: number[]): { owned: number; mounts: number; pack: SceneAsset } => {
-      const c = rootsToSceneAsset(reg, w, roots as never);
-      if (!c.ok) throw new Error(`collect failed: ${JSON.stringify(c.error)}`);
-      return {
-        owned: c.value.entities.length,
-        mounts: (c.value.mounts ?? []).length,
-        pack: c.value,
-      };
-    };
-
-    // The editor's owned top-level roots after a reload = the named entities the
-    // session tracks (store.ts _e2h owned-set: the scene asset's entities[], not
-    // mount internals). Mirror that here by taking the NAMED entities reachable
-    // from the scene (Ground + the bed.glb wrapper), excluding the nameless
-    // mount carrier — exactly what the editor collects via entRootHandles.
-    const namedTopEntities = (syntheticRoot: number): number[] => {
-      const wr = w as unknown as {
-        get(
-          e: number,
-          c: unknown,
-        ): {
-          ok: boolean;
-          value?: { entities?: ArrayLike<number>; value?: string; parent?: number };
-        };
-      };
-      // BFS from the synthetic root over Children; keep NAMED entities whose
-      // parent is not itself a named-tracked entity (i.e. top-level owned roots).
-      const named: number[] = [];
-      const queue = [syntheticRoot];
-      const seen = new Set<number>([syntheticRoot]);
-      while (queue.length) {
-        const cur = queue.shift() as number;
-        const ch = wr.get(cur, Children);
-        if (ch.ok && ch.value?.entities) {
-          for (const k of Array.from(ch.value.entities)) {
-            if (seen.has(k)) continue;
-            seen.add(k);
-            queue.push(k);
-            if (wr.get(k, Name).ok) named.push(k);
-          }
-        }
-      }
-      return named;
-    };
-
-    // Instantiate the top scene.
-    const i0 = reg.instantiate(rs(w, top), w);
-    expect(i0.ok).toBe(true);
-    if (!i0.ok) return;
-
-    // ── Editor "Add to Scene": spawn a NAMED wrapper parented under the top
-    //    scene, then mount the child scene UNDER the wrapper (instantiate with
-    //    parent=wrapper). Mirrors spawnGlbSceneAsMount +
-    //    instantiateSceneRefUnderWorld. ──
-    const wrapperRes = w.spawn(
-      { component: Name, data: { value: 'bed.glb' } },
-      { component: Transform, data: { pos: [0, 0, 0] } },
-    );
-    expect(wrapperRes.ok).toBe(true);
-    if (!wrapperRes.ok) return;
-    const mountRes = reg.instantiate(rs(w, child), w, wrapperRes.value);
-    expect(mountRes.ok).toBe(true);
-    if (!mountRes.ok) return;
-
-    // Cycle 1: collect from the owned roots (Ground + wrapper).
-    // Ground is a child of the synthetic root; the wrapper is a free root we
-    // just spawned. Collect from both (the editor's entRootHandles set).
-    const groundRoots = namedTopEntities(i0.value as unknown as number);
-    const c1 = runCycle([...groundRoots, wrapperRes.value as unknown as number]);
-
-    // Cycle 2: serialize → parse → reload → collect.
-    const s1 = serializeSceneAssetToPack(c1.pack, w.components.entries(), G_TOP);
-    expect(s1.ok).toBe(true);
-    if (!s1.ok) return;
-    const u1 = unpack(s1.value);
-    const p1 = parse(u1.payload, u1.refs);
-    cat(reg, G_TOP, p1);
-    const i1 = reg.instantiate(rs(w, p1), w);
-    expect(i1.ok).toBe(true);
-    if (!i1.ok) return;
-    const c2 = runCycle(namedTopEntities(i1.value as unknown as number));
-
-    // Cycle 3: reload + collect once more (the ghost-accretion point).
-    const s2 = serializeSceneAssetToPack(c2.pack, w.components.entries(), G_TOP);
-    expect(s2.ok).toBe(true);
-    if (!s2.ok) return;
-    const u2 = unpack(s2.value);
-    const p2 = parse(u2.payload, u2.refs);
-    cat(reg, G_TOP, p2);
-    const i2 = reg.instantiate(rs(w, p2), w);
-    expect(i2.ok).toBe(true);
-    if (!i2.ok) return;
-    const c3 = runCycle(namedTopEntities(i2.value as unknown as number));
-
-    // ACCEPTANCE: owned + mount counts are a FIXED POINT across reloads (before
-    // the fix this grew unboundedly: owned 2 → 3 → 5, one nameless ghost per
-    // cycle). Ground + bed.glb wrapper = 2 owned; the bed = 1 mount.
-    expect({ owned: c1.owned, mounts: c1.mounts }).toEqual({ owned: 2, mounts: 1 });
-    expect({ owned: c2.owned, mounts: c2.mounts }).toEqual({ owned: 2, mounts: 1 });
-    expect({ owned: c3.owned, mounts: c3.mounts }).toEqual({ owned: 2, mounts: 1 });
-
-    // No owned entity is nameless (the ghost signature).
-    for (const e of c3.pack.entities) {
-      const comps = e.components as Record<string, Record<string, unknown>>;
-      expect(comps.Name, `owned entity localId ${e.localId} must have a Name`).toBeDefined();
-    }
+    const result = registry.instantiate(makeHandle(world, parent), world);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(
+      [...world.iterDescendants(result.value)].filter(
+        (entity) => world.get(entity, SceneInstance).ok,
+      ),
+    ).toHaveLength(1);
+    const collected = rootsToSceneAsset(registry, world, [result.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    expect(collected.value.entities.wrapper?.instance?.source).toBe(CHILD);
+    expect(collected.value.entities.wrapper?.components.ChildOf).toEqual({ parent: 'root' });
   });
 });

package/src/__tests__/scene-sugar-instantiate.test.ts

@@ -21,24 +21,23 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { defineComponent, type EntityHandle, World } from '@forgeax/engine-ecs';
 import { SceneInstance } from '@forgeax/engine-render';
 import { ChildOf } from '@forgeax/engine-scene';
-import type { Handle, LocalEntityId, SceneAsset, SceneEntity } from '@forgeax/engine-types';
+import type { Handle, SceneAsset, SceneEntity } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerRuntimeComponents } from './helpers/register-runtime-components';
 
-function localId(n: number): LocalEntityId {
-  return n as LocalEntityId;
-}
-
 function buildScene(): SceneAsset {
   const Transform = defineComponent('Transform', { pos: 'array<f32, 3>' });
   void Transform;
   const nodes: SceneEntity[] = [
-    { localId: localId(0), components: { Transform: { pos: [1, 0, 0] } } },
-    { localId: localId(1), components: { Transform: { pos: [2, 0, 0] } } },
+    { key: 'entity-0', components: { Transform: { pos: [1, 0, 0] } } },
+    { key: 'entity-1', components: { Transform: { pos: [2, 0, 0] } } },
   ];
-  return { kind: 'scene', entities: nodes };
+  return {
+    kind: 'scene',
+    entities: Object.fromEntries(nodes.map(({ key, components }) => [key, { components }])),
+  };
 }
 
 function registerSceneAsset(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
@@ -142,11 +141,17 @@ describe('w30 - engine.assets.instantiate sugar wrapper equivalence (AC-03)', ()
 //       array is a snapshot at call time, not a live view (SceneInstance contract).
 
 function buildPostScene(): SceneAsset {
-  const nodes: SceneEntity[] = [
-    { localId: localId(0), components: { Transform: { pos: [0, 0, 0] } } },
-    { localId: localId(1), components: { Transform: { pos: [1, 0, 0] }, ChildOf: { parent: 0 } } },
+  const nodes: Array<SceneEntity & { readonly key: string }> = [
+    { key: 'entity-0', components: { Transform: { pos: [0, 0, 0] } } },
+    {
+      key: 'entity-1',
+      components: { Transform: { pos: [1, 0, 0] }, ChildOf: { parent: 'entity-0' } },
+    },
   ];
-  return { kind: 'scene', entities: nodes };
+  return {
+    kind: 'scene',
+    entities: Object.fromEntries(nodes.map(({ key, components }) => [key, { components }])),
+  };
 }
 
 // A lightweight component for post-instantiate injection testing.
@@ -227,8 +232,8 @@ describe('M5 post-instantiate component injection (w13 / AC-09 + AC-10)', () =>
     // Two root nodes, each gets a different component via query-after.
     defineComponent('Transform', { pos: 'array<f32, 3>' });
     const multiRoot: SceneEntity[] = [
-      { localId: localId(0), components: { Transform: { pos: [0, 0, 0] } } },
-      { localId: localId(1), components: { Transform: { pos: [10, 0, 0] } } },
+      { key: 'entity-0', components: { Transform: { pos: [0, 0, 0] } } },
+      { key: 'entity-1', components: { Transform: { pos: [10, 0, 0] } } },
     ];
     const reg = new AssetRegistry(makeMockShaderRegistry());
     const world = new World();
@@ -267,7 +272,7 @@ describe('M5 post-instantiate component injection (w13 / AC-09 + AC-10)', () =>
     const world = new World();
     registerRuntimeComponents(world, [Enemy, Waypoint]);
     const singleRoot: SceneEntity[] = [
-      { localId: localId(0), components: { Transform: { pos: [0, 0, 0] } } },
+      { key: 'entity-0', components: { Transform: { pos: [0, 0, 0] } } },
     ];
     const asset: SceneAsset = { kind: 'scene', entities: singleRoot };
     const handle = registerSceneAsset(world, asset);