@forgeax/engine-render 0.1.32 → 0.1.34

package/src/__tests__/instances-culling.integration.test.ts

@@ -7,8 +7,6 @@ import { Instances } from '../components/instances';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
-import type { InstanceCollectionId } from '../instances';
-import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
@@ -28,21 +26,13 @@ function spawnCamera(world: World): void {
     .unwrap();
 }
 
-function spawnInstancedCube(
-  world: World,
-  instanceCollections: InstanceCollectionStore,
-  entityX: number,
-  instanceX: number,
-) {
-  const collectionId = instanceCollections
-    .create({ transforms: translated(instanceX) })
-    .unwrap().collectionId;
+function spawnInstancedCube(world: World, entityX: number, instanceX: number) {
   return world
     .spawn(
       { component: Transform, data: { pos: [entityX, 0, 0] } },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { collectionId } },
+      { component: Instances, data: { transforms: translated(instanceX) } },
     )
     .unwrap();
 }
@@ -52,13 +42,10 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
+    const entity = spawnInstancedCube(world, 20, -20);
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
 
     expect(frame.renderables.map((renderable) => renderable.entityKey)).toContain(entity);
     expect(frame.frustumStats).toEqual({ culled: 0, total: 1 });
@@ -68,22 +55,15 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
+    const entity = spawnInstancedCube(world, 20, -20);
     world.update(0).unwrap();
-    expect(
-      extractFrames([world], 0, undefined, undefined, undefined, { instanceCollections })
-        .renderables,
-    ).toHaveLength(1);
+    expect(extractFrames([world], 0).renderables).toHaveLength(1);
 
     world.set(entity, Transform, { pos: [40, 0, 0] }).unwrap();
-    const collectionId = world.get(entity, Instances).unwrap().collectionId;
-    instanceCollections.replace(collectionId as InstanceCollectionId, translated(-40)).unwrap();
+    world.set(entity, Instances, { transforms: translated(-40) }).unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
     expect(frame.renderables).toHaveLength(1);
     expect(frame.renderables[0]?.instances?.instanceCount).toBe(1);
   });
@@ -92,23 +72,17 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const instanceCollections = new InstanceCollectionStore();
-    const collectionId = instanceCollections
-      .create({ transforms: new Float32Array() })
-      .unwrap().collectionId;
     const entity = world
       .spawn(
         { component: Transform, data: { pos: [20, 0, 0] } },
         { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: {} },
-        { component: Instances, data: { collectionId } },
+        { component: Instances, data: { transforms: new Float32Array() } },
       )
       .unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
     expect(
       frame.renderables.find((renderable) => renderable.entityKey === entity)?.instances,
     ).toMatchObject({ instanceCount: 0 });

package/src/__tests__/instances-store.unit.test.ts

@@ -1,264 +1,131 @@
+import { World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
-import { InstanceCollectionStore, instanceUploadRangesForResident } from '../instances';
-import { instanceCollectionCacheKey } from '../record/frame-snapshot';
+import { InstanceProjectionStore, validateInstanceTransforms } from '../instances';
+import { packInstanceStorageBuffer } from '../record/mesh-ssbo';
 
-function identityTransforms(count: number): Float32Array {
-  const transforms = new Float32Array(count * 16);
-  for (let index = 0; index < count; index += 1) {
-    const offset = index * 16;
-    transforms[offset] = 1;
-    transforms[offset + 5] = 1;
-    transforms[offset + 10] = 1;
-    transforms[offset + 15] = 1;
-  }
-  return transforms;
+function matrices(x: number): Float32Array {
+  return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
 }
 
-describe('InstanceCollectionStore', () => {
-  it('keeps large payloads outside ECS-sized storage and preserves one identity', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(20_000) });
-    expect(created.ok).toBe(true);
-    if (!created.ok) return;
-    expect(created.value.count).toBe(20_000);
-    expect(created.value.capacity).toBeGreaterThanOrEqual(20_000);
-    expect(store.snapshot(created.value.collectionId).unwrap().transforms).toHaveLength(
-      20_000 * 16,
-    );
-  });
+function project(
+  store: InstanceProjectionStore,
+  world: World,
+  entity: number,
+  transforms: Float32Array,
+) {
+  const snapshot = store.project(world, entity, transforms);
+  store.accept(world, entity, snapshot);
+  return snapshot;
+}
 
-  it('publishes bounded partial updates as one revision and one dirty interval', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(8) }).unwrap();
-    const before = store.snapshot(created.collectionId).unwrap();
-    const patch = identityTransforms(2);
-    patch[12] = 4;
-    expect(store.update(created.collectionId, { start: 3, transforms: patch }).ok).toBe(true);
-    const after = store.snapshot(created.collectionId).unwrap();
-    expect(after.revision).toBe(before.revision + 1);
-    expect(after.dirtyRanges).toEqual([{ start: 3, end: 5 }]);
-    expect(after.transforms[3 * 16 + 12]).toBe(4);
+describe('renderer instance projection', () => {
+  it('derives independent complete snapshots for consumers that skip different updates', () => {
+    const world = new World();
+    const first = new InstanceProjectionStore();
+    const late = new InstanceProjectionStore();
+    const before = project(first, world, 1, matrices(0));
+    project(late, world, 1, matrices(0));
+    project(first, world, 1, matrices(1));
+    project(first, world, 1, matrices(2));
+    const latest = project(late, world, 1, matrices(2));
+    expect(before.transforms[12]).toBe(0);
+    expect(latest.transforms[12]).toBe(2);
+    const stable = project(late, world, 1, matrices(2));
+    expect(stable.transforms).toBe(latest.transforms);
+    expect(stable.revision).toBe(latest.revision);
   });
 
-  it('keeps the full union when partial updates overlap out of order', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(16) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-    store.update(created.collectionId, { start: 10, transforms: identityTransforms(2) }).unwrap();
-    store.update(created.collectionId, { start: 8, transforms: identityTransforms(3) }).unwrap();
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 8, end: 12 },
-    ]);
+  it('does not alias identical entity numbers across World identities', () => {
+    const projection = new InstanceProjectionStore();
+    const a = project(projection, new World(), 1, matrices(10));
+    const b = project(projection, new World(), 1, matrices(99));
+    expect(a.collectionId).not.toBe(b.collectionId);
+    expect(a.transforms[12]).toBe(10);
+    expect(b.transforms[12]).toBe(99);
   });
 
-  it('keeps renderer dirty ranges intact when inspection peeks between updates', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(2) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-
-    store.update(created.collectionId, { start: 0, transforms: identityTransforms(1) }).unwrap();
-    const inspected = store.peek(created.collectionId).unwrap();
-    expect(inspected.dirtyRanges).toEqual([{ start: 0, end: 1 }]);
-    store.update(created.collectionId, { start: 1, transforms: identityTransforms(1) }).unwrap();
-
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 0, end: 2 },
-    ]);
+  it('rebuilds from unchanged source after dropping renderer resources', () => {
+    const world = new World();
+    const transforms = matrices(4);
+    const projection = new InstanceProjectionStore();
+    project(projection, world, 1, transforms);
+    projection.dispose();
+    expect(project(projection, world, 1, transforms).transforms).toEqual(transforms);
+    expect(new InstanceProjectionStore().project(world, 1, transforms).transforms).toEqual(
+      transforms,
+    );
   });
 
-  it('keeps collection identity in the renderer cache key', () => {
-    const first = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 1 });
-    const second = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 2 });
-    expect(first).not.toBe(second);
-    expect(instanceCollectionCacheKey(1, { cacheKey: 9, collectionId: 1 })).not.toBe(first);
-    expect(first).toBeLessThan(-0x1_0000_0000);
+  it('retains pose identity and last submitted matrices while reseeding resized topology', () => {
+    const world = new World();
+    const projection = new InstanceProjectionStore();
+    const before = project(projection, world, 1, matrices(2));
+    const moved = project(projection, world, 1, matrices(9));
+    expect(moved.generations).toEqual(before.generations);
+    const payload = packInstanceStorageBuffer(
+      moved.transforms,
+      before.transforms,
+      moved.generations,
+      before.generations,
+    );
+    expect(payload[12]).toBe(9);
+    expect(payload[16 + 12]).toBe(2);
+    const resized = project(
+      projection,
+      world,
+      1,
+      new Float32Array([...matrices(3), ...matrices(4)]),
+    );
+    expect(resized.generations[0]).not.toBe(moved.generations[0]);
+    expect(before.transforms[12]).toBe(2);
   });
 
-  it('projects resident and failure facts without exposing GPU handles', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(256) }).unwrap();
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 7,
-      lane: 'chunked-uniform',
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      uploadRanges: [{ start: 0, end: 128 }],
-      uploadedBytes: 128 * 64,
-      backend: 'webgpu',
-    });
-    expect(store._inspections()[0]).toMatchObject({
-      collectionId: created.collectionId,
-      residentGeneration: 7,
-      lane: 'chunked-uniform',
-      uploadRanges: [{ start: 0, end: 128 }],
-      uploadedBytes: 128 * 64,
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      backend: 'webgpu',
-      owner: 'renderer.instances',
-    });
-    store._reportFailure({
-      collectionId: created.collectionId,
-      code: 'limit-exceeded',
-      expected: 'the requested payload fits',
-      hint: 'use a storage-capable backend',
-      facts: {
-        requestedBytes: 256 * 64,
-        supportedBytes: 128 * 64,
-        backend: 'webgpu',
-        owner: 'renderer.instances',
-        cause: 'limit-exceeded',
-        recovery: 'use a storage-capable backend',
-      },
-    });
-    const failed = store._inspections()[0];
-    expect(failed?.lane).toBe('unavailable');
-    expect(failed?.error?.detail).toMatchObject({
-      requestedBytes: 256 * 64,
-      supportedBytes: 128 * 64,
-      owner: 'renderer.instances',
-      cause: 'limit-exceeded',
-      recovery: 'use a storage-capable backend',
-    });
+  it('releases removed identities and never aliases a replacement to retained temporal data', () => {
+    const world = new World();
+    const projection = new InstanceProjectionStore();
+    const a = project(projection, world, 1, matrices(1));
+    const b = project(projection, world, 2, matrices(2));
+    projection.retain(new Set([b.collectionId]));
+    expect(projection._inspections(0).map((value) => value.collectionId)).toEqual([b.collectionId]);
+    const replacement = project(projection, world, 1, matrices(3));
+    expect(replacement.collectionId).not.toBe(a.collectionId);
+    projection.release(world, 1);
+    projection.release(world, 1);
+    expect(projection._inspections(0)).toHaveLength(1);
   });
 
-  it('aggregates upload evidence within one frame and resets it on a stable frame', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 3,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 0, end: 2 }],
-      uploadedBytes: 2 * 80,
-      backend: 'webgpu',
-    });
-    store._reportResidency({
-      collectionId: created.collectionId,
+  it('reports only current-frame uploads and drops old device residency on recovery', () => {
+    const projection = new InstanceProjectionStore();
+    const value = project(projection, new World(), 1, matrices(2));
+    projection._reportResidency({
+      collectionId: value.collectionId,
       frameNumber: 1,
       residentGeneration: 3,
       lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 2, end: 4 }],
-      uploadedBytes: 2 * 80,
+      uploadRanges: [{ start: 0, end: 1 }],
+      uploadedBytes: 128,
+      requestedBytes: 128,
+      supportedBytes: 1024,
       backend: 'webgpu',
     });
-    expect(store._inspections()[0]).toMatchObject({
-      uploadRanges: [{ start: 0, end: 4 }],
-      uploadedBytes: 4 * 80,
-    });
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 2,
-      residentGeneration: 3,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [],
-      uploadedBytes: 0,
-      backend: 'webgpu',
-    });
-    expect(store._inspections()[0]).toMatchObject({ uploadRanges: [], uploadedBytes: 0 });
-  });
-
-  it('forces a full canonical upload for a new resident after partial mutation and recovery', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
-    store.snapshot(created.collectionId).unwrap();
-    store
-      .update(created.collectionId, {
-        start: 2,
-        transforms: identityTransforms(1),
-      })
-      .unwrap();
-    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
-      { start: 2, end: 3 },
-    ]);
-
-    store._reportResidency({
-      collectionId: created.collectionId,
-      frameNumber: 1,
-      residentGeneration: 4,
-      lane: 'direct-storage',
-      requestedBytes: 4 * 80,
-      supportedBytes: 1 << 20,
-      uploadRanges: [{ start: 2, end: 3 }],
-      uploadedBytes: 80,
-      backend: 'webgpu',
-    });
-    store._resetResidency();
-    expect(store._inspections()[0]).toMatchObject({
-      lane: 'unresident',
-      uploadedBytes: 0,
-      uploadRanges: [],
-    });
-
-    expect(
-      instanceUploadRangesForResident(true, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
-    ).toEqual([{ start: 0, end: 4 }]);
-    expect(
-      instanceUploadRangesForResident(false, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
-    ).toEqual([{ start: 2, end: 3 }]);
-  });
-
-  it('rejects malformed stride, out-of-range writes and released ids structurally', () => {
-    const store = new InstanceCollectionStore();
-    const malformed = store.create({ transforms: new Float32Array(17) });
-    expect(malformed.ok).toBe(false);
-    if (malformed.ok) return;
-    expect(malformed.error.code).toBe('instance-collection-invalid');
-    expect(malformed.error.facts).toMatchObject({
-      requestedBytes: 17 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: undefined,
-      backend: 'unknown',
-      owner: 'renderer.instances',
-      cause: 'invalid-transform-stride',
-      recovery: malformed.error.hint,
-    });
-    const created = store.create({ transforms: identityTransforms(1) }).unwrap();
-    const range = store.update(created.collectionId, {
-      start: 1,
-      transforms: identityTransforms(1),
-    });
-    expect(range.ok).toBe(false);
-    if (range.ok) return;
-    expect(range.error.code).toBe('instance-collection-invalid');
-    expect(range.error.facts).toMatchObject({
-      requestedBytes: 2 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: 16 * Float32Array.BYTES_PER_ELEMENT,
-      backend: 'unknown',
-      owner: 'renderer.instances',
-      cause: 'invalid-update-range-end',
-      recovery: range.error.hint,
-    });
-    expect(store.release(created.collectionId).ok).toBe(true);
-    const released = store.inspect(created.collectionId);
-    expect(released.ok).toBe(false);
-    if (!released.ok) expect(released.error.code).toBe('instance-collection-not-found');
+    expect(projection._inspections(1)[0]?.uploadedBytes).toBe(128);
+    expect(projection._inspections(2)[0]?.uploadedBytes).toBe(0);
+    expect(projection._inspections(2)[0]?.uploadRanges).toEqual([]);
+    projection._resetResidency();
+    expect(projection._inspections(2)[0]).toMatchObject({ lane: 'unresident', revision: 1 });
   });
 
-  it('reports the logical authoring boundary when physical capacity has spare slots', () => {
-    const store = new InstanceCollectionStore();
-    const created = store.create({ transforms: identityTransforms(3) }).unwrap();
-    expect(created.capacity).toBe(4);
-
-    const range = store.update(created.collectionId, {
-      start: 3,
-      transforms: identityTransforms(1),
+  it('rejects incomplete and non-finite matrices before they reach rendering', () => {
+    expect(validateInstanceTransforms(new Float32Array(17))).toMatchObject({
+      code: 'instance-transforms-stride-mismatch',
+      detail: { actualLength: 17, expectedStride: 16 },
     });
-    expect(range.ok).toBe(false);
-    if (range.ok) return;
-    expect(range.error.facts).toMatchObject({
-      requestedBytes: 4 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      supportedBytes: 3 * 16 * Float32Array.BYTES_PER_ELEMENT,
-      cause: 'invalid-update-range-end',
-      owner: 'renderer.instances',
+    const invalid = matrices(0);
+    invalid[12] = NaN;
+    expect(validateInstanceTransforms(invalid)).toMatchObject({
+      code: 'instance-transforms-invalid',
+      detail: { actualLength: 16, nonFiniteIndex: 12 },
     });
+    expect(validateInstanceTransforms(new Float32Array())).toBeUndefined();
   });
 });

package/src/__tests__/instances-world-ownership.integration.test.ts

@@ -0,0 +1,62 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { extractFrames } from '../render-system-extract';
+
+function matrices(count: number, x: number): Float32Array {
+  const out = new Float32Array(count * 16);
+  for (let i = 0; i < count; i++) {
+    out[i * 16] = out[i * 16 + 5] = out[i * 16 + 10] = out[i * 16 + 15] = 1;
+    out[i * 16 + 12] = x;
+  }
+  return out;
+}
+
+function scene(count: number, x: number) {
+  const world = new World();
+  registerPropagateTransforms(world);
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: matrices(count, x) } },
+    )
+    .unwrap();
+  world.update(0).unwrap();
+  return { world, entity };
+}
+
+describe('World-owned instance authoring', () => {
+  it.each([1500, 10000, 20000])('extracts %s matrices without creating a Renderer', (count) => {
+    const { world } = scene(count, 0);
+    const snapshot = extractFrames([world], 0).renderables[0]?.instances;
+    expect(snapshot?.instanceCount).toBe(count);
+    expect(snapshot?.transforms).toEqual(matrices(count, 0));
+  });
+
+  it('keeps worlds isolated and lets independent consumers observe skipped updates', () => {
+    const a = scene(2, 0);
+    const b = scene(2, 1);
+    const before = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, 0.5) }).unwrap();
+    extractFrames([a.world], 0);
+    a.world.set(a.entity, Instances, { transforms: matrices(2, -0.5) }).unwrap();
+    const late = extractFrames([a.world], 0).renderables[0]?.instances;
+    expect(late?.transforms[12]).toBe(-0.5);
+    expect(before?.transforms[12]).toBe(0);
+    expect(extractFrames([b.world], 0).renderables[0]?.instances?.transforms[12]).toBe(1);
+  });
+});