@forgeax/engine-runtime 0.1.27 → 0.1.29

package/src/__tests__/serialize-scene-asset.test.ts

@@ -16,7 +16,7 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type Component, defineComponent, type EntityHandle, World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { SceneInstance } from '@forgeax/engine-render';
-import type { LocalEntityId, MountOverride, SceneAsset } from '@forgeax/engine-types';
+import type { SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { rootsToSceneAsset, serializeSceneAssetToPack } from '../collect-scene-asset';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
@@ -26,10 +26,6 @@ import { registerSceneComponents } from './helpers/register-scene-components';
 // Helpers
 // ═══════════════════════════════════════════════════════════════════════════════
 
-function localId(n: number): LocalEntityId {
-  return n as LocalEntityId;
-}
-
 function mkReg(): AssetRegistry {
   return new AssetRegistry(makeMockShaderRegistry());
 }
@@ -59,10 +55,14 @@ function findMountedMember(w: World, rootA: EntityHandle): EntityHandle {
   }
   throw new Error('no mounted member found');
 }
-function firstMountOverride(scene: SceneAsset, comp: string): MountOverride | undefined {
-  for (const m of scene.mounts ?? []) {
-    for (const ov of m.overrides ?? []) {
-      if (ov.comp === comp) return ov;
+function firstInstanceOverride(
+  scene: SceneAsset,
+  comp: string,
+): { readonly value: unknown } | undefined {
+  for (const entity of Object.values(scene.entities)) {
+    for (const instanceOverride of entity.instance?.overrides ?? []) {
+      const value = instanceOverride.components[comp];
+      if (value !== undefined) return { value };
     }
   }
   return undefined;
@@ -83,12 +83,7 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
 
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
-          components: { Test_SPackSharedScalar: { assetRef: guid1 } },
-        },
-      ],
+      entities: { 'entity-0': { components: { Test_SPackSharedScalar: { assetRef: guid1 } } } },
     };
 
     const packResult = serializeSceneAssetToPack(
@@ -116,7 +111,7 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
     expect(refs).toContain(guid1);
 
     const payload = asset.payload as Record<string, unknown>;
-    const entities = payload.entities as Array<Record<string, unknown>>;
+    const entities = Object.values(payload.entities as Record<string, Record<string, unknown>>);
     expect(entities).toHaveLength(1);
 
     const ent0 = entities[0];
@@ -138,12 +133,9 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
 
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
-          components: { Test_SPackSharedArray: { sources: [guidA, guidB] } },
-        },
-      ],
+      entities: {
+        'entity-0': { components: { Test_SPackSharedArray: { sources: [guidA, guidB] } } },
+      },
     };
 
     const packResult = serializeSceneAssetToPack(
@@ -163,7 +155,7 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
     expect(refs).toContain(guidB);
 
     const payload = asset.payload as Record<string, unknown>;
-    const entities = payload.entities as Array<Record<string, unknown>>;
+    const entities = Object.values(payload.entities as Record<string, Record<string, unknown>>);
     const ent0 = entities[0];
     if (!ent0) throw new Error('entity 0 missing');
     const comps = ent0.components as Record<string, Record<string, unknown>>;
@@ -190,12 +182,7 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
 
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
-          components: { Test_STilesetPack: { tileset: tilesetGuid } },
-        },
-      ],
+      entities: { 'entity-0': { components: { Test_STilesetPack: { tileset: tilesetGuid } } } },
     };
 
     const packResult = serializeSceneAssetToPack(
@@ -226,12 +213,11 @@ describe('m3-t1: serialize refs index with schema derivation', () => {
     // collection (only strings are collected), so Phase 2 index lookup will fail.
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
+      entities: {
+        'entity-0': {
           components: { Test_SFailFastPack: { loneRef: 'non-collected-guid-wont-be-in-refs' } },
         },
-      ],
+      },
     };
 
     // Use a completely unrelated GUID for the asset to ensure Phase 1 collects nothing.
@@ -272,15 +258,14 @@ describe('m3-t2: unregistered component silently skipped', () => {
 
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
+      entities: {
+        'entity-0': {
           components: {
             Test_SRegComp: { val: 42 },
             Unreg_TestSkip: { mysteryField: 'should-survive' },
           },
         },
-      ],
+      },
     };
 
     const packResult = serializeSceneAssetToPack(
@@ -296,7 +281,7 @@ describe('m3-t2: unregistered component silently skipped', () => {
     const asset = assets[0];
     if (!asset) throw new Error('asset missing');
     const payload = asset.payload as Record<string, unknown>;
-    const entities = payload.entities as Array<Record<string, unknown>>;
+    const entities = Object.values(payload.entities as Record<string, Record<string, unknown>>);
     expect(entities).toHaveLength(1);
 
     const ent0 = entities[0];
@@ -325,15 +310,14 @@ describe('m3-t2: unregistered component silently skipped', () => {
 
     const sceneAsset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        {
-          localId: localId(0),
+      entities: {
+        'entity-0': {
           components: {
             Test_SRegComp2: { count: 99 },
             Unreg_TestSkip2: { ghostField: 12345 },
           },
         },
-      ],
+      },
     };
 
     const packResult = serializeSceneAssetToPack(
@@ -349,7 +333,7 @@ describe('m3-t2: unregistered component silently skipped', () => {
     const asset = assets[0];
     if (!asset) throw new Error('asset missing');
     const payload = asset.payload as Record<string, unknown>;
-    const entities = payload.entities as Array<Record<string, unknown>>;
+    const entities = Object.values(payload.entities as Record<string, Record<string, unknown>>);
     expect(entities).toHaveLength(1);
 
     const ent0 = entities[0];
@@ -409,13 +393,15 @@ function mintCatalogued(reg: AssetRegistry, w: World, guid: string, tag: number)
 function mountOne(reg: AssetRegistry, w: World): EntityHandle {
   const child: SceneAsset = {
     kind: 'scene',
-    entities: [{ localId: localId(0), components: { Transform: { pos: [1, 0, 0] } } }],
+    entities: { 'entity-0': { components: { Transform: { pos: [1, 0, 0] } } } },
   };
   catScene(reg, W18_CHILD, child);
   const parent: SceneAsset = {
     kind: 'scene',
-    entities: [{ localId: localId(0), components: { Transform: { pos: [0, 0, 0] } } }],
-    mounts: [{ localId: localId(1), source: W18_CHILD, memberFirst: localId(2), memberCount: 1 }],
+    entities: {
+      'entity-0': { components: { Transform: { pos: [0, 0, 0] } } },
+      child: { components: {}, instance: { source: W18_CHILD } },
+    },
   };
   catScene(reg, W18_PARENT, parent);
   const inst = reg.instantiate(rs(w, parent), w);
@@ -443,7 +429,7 @@ describe('w18 — override-value shared handle→GUID two-state NULL-sentinel (A
     const collect = rootsToSceneAsset(reg, w, [root]);
     expect(collect.ok).toBe(true);
     if (!collect.ok) return;
-    const ov = firstMountOverride(collect.value, 'AnimationPlayer');
+    const ov = firstInstanceOverride(collect.value, 'AnimationPlayer');
     expect(ov).toBeDefined();
     if (!ov) return;
     const clips = (ov.value as Record<string, unknown>).clips as unknown[];
@@ -473,7 +459,7 @@ describe('w18 — override-value shared handle→GUID two-state NULL-sentinel (A
     const collect = rootsToSceneAsset(reg, w, [root]);
     expect(collect.ok).toBe(true);
     if (!collect.ok) return;
-    const ov = firstMountOverride(collect.value, 'AnimationPlayer');
+    const ov = firstInstanceOverride(collect.value, 'AnimationPlayer');
     expect(ov).toBeDefined();
     if (!ov) return;
     const clips = (ov.value as Record<string, unknown>).clips as unknown[];
@@ -499,7 +485,7 @@ describe('w18 — override-value shared handle→GUID two-state NULL-sentinel (A
     const collect = rootsToSceneAsset(reg, w, [root]);
     expect(collect.ok).toBe(true);
     if (!collect.ok) return;
-    const ov = firstMountOverride(collect.value, 'W18_ScalarShared');
+    const ov = firstInstanceOverride(collect.value, 'W18_ScalarShared');
     expect(ov).toBeDefined();
     if (!ov) return;
     const val = ov.value as Record<string, unknown>;
@@ -522,7 +508,7 @@ describe('w18 — override-value shared handle→GUID two-state NULL-sentinel (A
     const collect = rootsToSceneAsset(reg, w, [root]);
     expect(collect.ok).toBe(true);
     if (!collect.ok) return;
-    const ov = firstMountOverride(collect.value, 'W18_ScalarShared');
+    const ov = firstInstanceOverride(collect.value, 'W18_ScalarShared');
     expect(ov).toBeDefined();
     if (!ov) return;
     const val = ov.value as Record<string, unknown>;

package/src/__tests__/shadow-caster-empty-schema.test.ts

@@ -45,7 +45,9 @@ describe('shadow_caster shared Surface schema', () => {
 
   it('(b) shadow_caster has no material sidecar', () => {
     const sourcePath = join(repoRoot, 'packages', 'shader', 'src', 'shadow_caster.wgsl');
-    expect(readFileSync(sourcePath, 'utf8')).toContain('shadow_caster.wgsl');
+    const source = readFileSync(sourcePath, 'utf8');
+    expect(source).toContain('#define_import_path forgeax::default-shadow-caster');
+    expect(source).toContain('#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}');
     expect(existsSync(`${sourcePath}.meta.json`)).toBe(false);
   });
 

package/src/__tests__/shadow-fields-observable.dawn.test.ts

@@ -14,7 +14,7 @@
 
 import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import type { Renderer } from '@forgeax/engine-render';
+import type { InstanceCollectionId, Renderer } from '@forgeax/engine-render';
 import {
   Camera,
   DirectionalLight,
@@ -39,11 +39,9 @@ const WIDTH = LIGHTWEIGHT_DAWN ? 128 : 256;
 const HEIGHT = LIGHTWEIGHT_DAWN ? 128 : 256;
 const BPR = Math.ceil((WIDTH * 4) / 256) * 256;
 
-// Each falsifier performs four fresh Dawn readbacks at the active target size
-// (256x256 by default, 128x128 in the lightweight CI lane). Windows' Dawn
-// prebuild can exceed Vitest's 90-second bound for that sequence while still
-// completing well inside the nightly platform job's 45-minute budget.
-const SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS = 300_000;
+// Four fresh readbacks, or the 2048-square map's full 300 frames, retain a
+// bounded software-GPU budget. The lightweight map comparison keeps 60 seconds.
+const SHADOW_FIELDS_FULL_PIXEL_TIMEOUT_MS = 300_000;
 
 const ENGINE_MANIFEST = await (async () => {
   const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
@@ -191,6 +189,7 @@ function spawnScene(
   normalBias: number,
   pcf: number,
   mapSize?: number,
+  instanceCollectionId?: InstanceCollectionId,
 ) {
   const cm = casterMat(world);
   const fm = floorMat(world);
@@ -234,6 +233,10 @@ function spawnScene(
       intensity: 1,
       castShadow,
       mapSize: mapSize ?? 1024,
+      // One cascade covers this field-comparison scene. Multi-cascade rebuilds
+      // are exercised by shadow-csm-runtime-vary.dawn.test.ts; repeating four
+      // 2048-square depth maps here hid the field assertions behind timeouts.
+      cascadeCount: 1,
       depthBias,
       normalBias,
       shadowDistance: 50,
@@ -253,7 +256,9 @@ function spawnScene(
     },
     { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
     { component: MeshRenderer, data: { materials: [cm] } },
-    { component: Instances, data: { transforms: buildTranslationGrid() } },
+    ...(instanceCollectionId === undefined
+      ? []
+      : [{ component: Instances, data: { collectionId: instanceCollectionId } }]),
   );
 }
 
@@ -360,7 +365,10 @@ async function renderConfig(
     const dev = sd;
 
     const w = new World();
-    spawnScene(w, castShadow, depthBias, normalBias, pcf, mapSize);
+    const instanceCollection = renderer.instances
+      .create({ transforms: buildTranslationGrid() })
+      .unwrap();
+    spawnScene(w, castShadow, depthBias, normalBias, pcf, mapSize, instanceCollection.collectionId);
     let de = 0;
     for (let i = 0; i < SHADOW_FIELDS_RENDER_FRAMES; i++) {
       const r = drawPublished(renderer, w);
@@ -485,7 +493,10 @@ async function renderConfigWithSpy(
     const dev = sd;
 
     const w = new World();
-    spawnScene(w, castShadow, depthBias, normalBias, pcf, mapSize);
+    const instanceCollection = renderer.instances
+      .create({ transforms: buildTranslationGrid() })
+      .unwrap();
+    spawnScene(w, castShadow, depthBias, normalBias, pcf, mapSize, instanceCollection.collectionId);
     let de = 0;
     for (let i = 0; i < 10; i++) {
       const r = drawPublished(renderer, w);
@@ -623,13 +634,17 @@ describe('M6 shadow fields observability', () => {
   }, 60000);
 
   // --- Gate F: mapSize 256 vs 2048 (independent shadow proof) ---
-  it('pixel A/B: mapSize 256 vs 2048', async () => {
-    if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
-    const pxA = await renderConfig(true, 0.005, 0.05, 3, 256);
-    const pxB = await renderConfig(true, 0.005, 0.05, 3, 2048);
-    const d = diff(pxA, pxB);
-    expect(d.diff).toBeGreaterThan(0);
-  }, 60000);
+  it(
+    'pixel A/B: mapSize 256 vs 2048',
+    async () => {
+      if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') return;
+      const pxA = await renderConfig(true, 0.005, 0.05, 3, 256);
+      const pxB = await renderConfig(true, 0.005, 0.05, 3, 2048);
+      const d = diff(pxA, pxB);
+      expect(d.diff).toBeGreaterThan(0);
+    },
+    LIGHTWEIGHT_DAWN ? 60_000 : SHADOW_FIELDS_FULL_PIXEL_TIMEOUT_MS,
+  );
 
   // --- Gate E: equal-control — same config twice => 0 diff ---
   it('equal-control: same config twice = 0 byte diff', async () => {
@@ -678,7 +693,7 @@ describe('M6 shadow fields observability', () => {
       expect(varied.diff).toBeGreaterThan(0);
       expect(held.diff).toBe(0);
     },
-    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+    SHADOW_FIELDS_FULL_PIXEL_TIMEOUT_MS,
   );
 
   it(
@@ -696,7 +711,7 @@ describe('M6 shadow fields observability', () => {
       expect(varied.diff).toBeGreaterThan(0);
       expect(held.diff).toBe(0);
     },
-    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+    SHADOW_FIELDS_FULL_PIXEL_TIMEOUT_MS,
   );
 
   it(
@@ -714,6 +729,6 @@ describe('M6 shadow fields observability', () => {
       expect(varied.diff).toBeGreaterThan(0);
       expect(held.diff).toBe(0);
     },
-    SHADOW_FIELDS_FALSIFIER_TIMEOUT_MS,
+    SHADOW_FIELDS_FULL_PIXEL_TIMEOUT_MS,
   );
 });

package/src/__tests__/shadow-mesh-ssbo-order.test.ts

@@ -13,32 +13,25 @@ function sourceAfter(signature: string): string {
   return shadowPass.slice(start);
 }
 
-function expectValidatedOrderedLoop(
-  signature: string,
-  indexName: string,
-  dynamicOffsetBindGroup: string,
-): void {
+function expectValidatedOrderedLoop(signature: string, indexName: string): void {
   const body = sourceAfter(signature);
   expect(body).toContain(
     `for (let ${indexName} = 0; ${indexName} < validatedOrdered.length; ${indexName}++)`,
   );
-  expect(body).toContain(`${dynamicOffsetBindGroup}, [${indexName} * MESH_PER_ENTITY_STRIDE]`);
+  expect(body).toContain('const meshSsboBase = c.shadowMeshSsboBase ?? 0');
+  expect(body).toContain(`(meshSsboBase + ${indexName}) * MESH_PER_ENTITY_STRIDE`);
 }
 
 describe('shadow mesh SSBO order', () => {
   it('uses the upload order for typed directional, point, and spot shadow offsets', () => {
-    expectValidatedOrderedLoop(
-      'function recordShadowCasterDraws(',
-      'i',
-      'shadowPass.setBindGroup(2, shadowMeshBindGroup',
-    );
+    expectValidatedOrderedLoop('function recordShadowCasterDraws(', 'i');
     expect(shadowPass).toContain('export function encodeDirectionalShadowPass(');
     expect(shadowPass).toContain('export function encodePointShadowPass(');
     expect(shadowPass).toContain('export function encodeSpotShadowPass(');
     const spotBody = sourceAfter('export function encodeSpotShadowPass(');
     expect(spotBody).toContain('recordShadowCasterDraws(');
     expect(spotBody).toContain(
-      "buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] })",
+      "buildMatchedRenderableIndices(shadowDispatchEntries(c), { LightMode: ['ShadowCaster'] })",
     );
     expect(shadowPass).not.toContain('export function recordShadowPass(');
     expect(shadowPass).not.toContain('export function recordPointShadowPass(');

package/src/__tests__/skin-extract-getarrayview-count.unit.test.ts

@@ -4,8 +4,9 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
-// Regression guard for the hot extract path: joint/instance array fields must
-// stay on the zero-copy column route instead of whole-row world.get calls.
+// Regression guard for the hot extract path: joint and sprite array fields stay
+// on column views, while large explicit instance matrices stay in the
+// renderer-owned collection store instead of being copied into ECS.
 
 const extractPaths = (() => {
   const here = dirname(fileURLToPath(import.meta.url));
@@ -14,12 +15,13 @@ const extractPaths = (() => {
 })();
 
 describe('_getArrayView count (AC-03 gate)', () => {
-  it('keeps skin and instance hot fields on column views', () => {
+  it('keeps skin/sprite hot fields on column views and instances renderer-owned', () => {
     const src = extractPaths.map((path) => readFileSync(path, 'utf8')).join('\n');
     expect(src).toMatch(/_getArrayView\(jointEntity,\s*GlobalTransform,\s*'world'\)/);
-    expect(src).toContain("_getArrayView(entity, Instances, 'transforms')");
     expect(src).toContain("_getArrayView(entity, SpriteInstances, 'transforms')");
     expect(src).toContain("_getArrayView(entity, SpriteInstances, 'regions')");
+    expect(src).toContain('instanceCollections.snapshot(collectionId)');
+    expect(src).not.toContain("_getArrayView(entity, Instances, 'transforms')");
     expect(src).not.toMatch(/^\s*const\s+\w+\s*=\s*world\.get\(jointEntity, Transform\)/m);
     expect(src).not.toMatch(/^\s*const\s+\w+\s*=\s*world\.get\(entity, Instances\)/m);
   });

package/src/__tests__/skin-m2-extract-happy.cases.unit.test.ts

@@ -63,6 +63,7 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
 import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
 import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
 import {
@@ -391,6 +392,7 @@ function registerSkinM2Mesh(world: World): Handle<'MeshAsset', 'shared'> {
     vertices: SKIN_M2_TRIANGLE_VERTICES,
     indices: new Uint16Array([0, 1, 2]),
     attributes: {
+      ...buildMeshAttributeMapForUvSets(1),
       position: SKIN_M2_TRIANGLE_POSITIONS,
       skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
       skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
@@ -492,17 +494,40 @@ function spawnSkinM2SkinnedEntity(
 
 type SkinM2StubAllocator = {
   buffer: null;
-  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number };
+  allocatePersistentSlice(input: {
+    identity: string;
+    generation: number;
+    jointCount: number;
+    bounds?: Float32Array;
+  }): SkinM2PersistentReceipt;
+  observePersistentJoints(
+    identity: string,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Float32Array[],
+  ): readonly number[];
+  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number; buffer: null };
   writeJointPalette(
     slice: { jointCount: number; byteOffset: number },
     ibms: readonly Float32Array[],
     jointWorlds: readonly Float32Array[],
   ): void;
+  beginFrame(): void;
+  endFrame(): void;
+  releasePersistentSlice(identity: string): void;
+  writePersistentJointPalette(receipt: SkinM2PersistentReceipt): void;
   resetForFrame(): void;
   _resetCount(): number;
   _writeCount(): number;
 };
 
+type SkinM2PersistentReceipt = {
+  identity: string;
+  generation: number;
+  jointCount: number;
+  byteOffset: number;
+  buffer: null;
+};
+
 function makeSkinM2StubAllocator(): SkinM2StubAllocator {
   let cursor = 0;
   let resetCount = 0;
@@ -513,11 +538,34 @@ function makeSkinM2StubAllocator(): SkinM2StubAllocator {
       const offset = cursor;
       // 256-aligned bump (mirrors real allocator dyn-offset alignment).
       cursor = (cursor + jointCount * 64 + 255) & ~255;
-      return { jointCount, byteOffset: offset };
+      return { jointCount, byteOffset: offset, buffer: null };
     },
     writeJointPalette() {
       writeCount++;
     },
+    observePersistentJoints() {
+      return [];
+    },
+    allocatePersistentSlice(input) {
+      const slice = this.allocateSlice(input.jointCount);
+      return {
+        ...slice,
+        identity: input.identity,
+        generation: input.generation,
+        fence: 1,
+        customDataStart: 0,
+        storageOrUniform: 'storage',
+        dirtyRanges: [{ startJoint: 0, jointCount: input.jointCount }],
+        uploadBytes: input.jointCount * 64,
+        ...(input.bounds === undefined ? {} : { bounds: input.bounds }),
+      };
+    },
+    writePersistentJointPalette() {
+      writeCount++;
+    },
+    beginFrame() {},
+    endFrame() {},
+    releasePersistentSlice() {},
     resetForFrame() {
       cursor = 0;
       resetCount++;

package/src/__tests__/skin-m2-extract-joint-error.cases.unit.test.ts

@@ -63,6 +63,7 @@ import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
 import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
 import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
 import { mat4, vec3 } from '@forgeax/engine-math';
 import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
 import {
@@ -391,6 +392,7 @@ function registerSkinM2Mesh(world: World): Handle<'MeshAsset', 'shared'> {
     vertices: SKIN_M2_TRIANGLE_VERTICES,
     indices: new Uint16Array([0, 1, 2]),
     attributes: {
+      ...buildMeshAttributeMapForUvSets(1),
       position: SKIN_M2_TRIANGLE_POSITIONS,
       skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
       skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
@@ -492,17 +494,40 @@ function spawnSkinM2SkinnedEntity(
 
 type SkinM2StubAllocator = {
   buffer: null;
-  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number };
+  allocatePersistentSlice(input: {
+    identity: string;
+    generation: number;
+    jointCount: number;
+    bounds?: Float32Array;
+  }): SkinM2PersistentReceipt;
+  observePersistentJoints(
+    identity: string,
+    ibms: readonly Float32Array[],
+    jointWorlds: readonly Float32Array[],
+  ): readonly number[];
+  allocateSlice(jointCount: number): { jointCount: number; byteOffset: number; buffer: null };
   writeJointPalette(
     slice: { jointCount: number; byteOffset: number },
     ibms: readonly Float32Array[],
     jointWorlds: readonly Float32Array[],
   ): void;
+  beginFrame(): void;
+  endFrame(): void;
+  releasePersistentSlice(identity: string): void;
+  writePersistentJointPalette(receipt: SkinM2PersistentReceipt): void;
   resetForFrame(): void;
   _resetCount(): number;
   _writeCount(): number;
 };
 
+type SkinM2PersistentReceipt = {
+  identity: string;
+  generation: number;
+  jointCount: number;
+  byteOffset: number;
+  buffer: null;
+};
+
 function makeSkinM2StubAllocator(): SkinM2StubAllocator {
   let cursor = 0;
   let resetCount = 0;
@@ -513,11 +538,34 @@ function makeSkinM2StubAllocator(): SkinM2StubAllocator {
       const offset = cursor;
       // 256-aligned bump (mirrors real allocator dyn-offset alignment).
       cursor = (cursor + jointCount * 64 + 255) & ~255;
-      return { jointCount, byteOffset: offset };
+      return { jointCount, byteOffset: offset, buffer: null };
     },
     writeJointPalette() {
       writeCount++;
     },
+    observePersistentJoints() {
+      return [];
+    },
+    allocatePersistentSlice(input) {
+      const slice = this.allocateSlice(input.jointCount);
+      return {
+        ...slice,
+        identity: input.identity,
+        generation: input.generation,
+        fence: 1,
+        customDataStart: 0,
+        storageOrUniform: 'storage',
+        dirtyRanges: [{ startJoint: 0, jointCount: input.jointCount }],
+        uploadBytes: input.jointCount * 64,
+        ...(input.bounds === undefined ? {} : { bounds: input.bounds }),
+      };
+    },
+    writePersistentJointPalette() {
+      writeCount++;
+    },
+    beginFrame() {},
+    endFrame() {},
+    releasePersistentSlice() {},
     resetForFrame() {
       cursor = 0;
       resetCount++;