@forgeax/engine-render 0.1.33 → 0.1.35

package/src/__tests__/temporal-history-lifecycle.unit.test.ts

@@ -31,6 +31,11 @@ describe('TAA history lifecycle', () => {
         'r8unorm',
       ]);
       expect(state).toHaveProperty('stability');
+      expect(state).toHaveProperty('cloudRadiance');
+      expect(state).toHaveProperty('cloudTransmittance');
+      expect(state).toHaveProperty('cloudDepth');
+      expect(state.cloudHistoryEnabled).toBe(false);
+      expect(state.cloudRadiance).toBeUndefined();
       const view = createTemporalView({ antialias: 'taa', width: 8, height: 8 });
       const inspection = inspectTemporal(view, undefined, { active: state });
       expect(inspection.historyBytes).toBe(34 * 8 * 8);
@@ -39,6 +44,33 @@ describe('TAA history lifecycle', () => {
       retireTemporalGpuState(state);
     }
   });
+  it('allocates the cloud MRT only for a cloud-enabled candidate', async () => {
+    const device = (await new RhiNullAdapter().requestDevice()).unwrap();
+    const textures = vi.spyOn(device, 'createTexture');
+    const state = getTemporalGpuState(
+      {} as RenderFrameState,
+      device,
+      DeviceScope.create(23, 'cloud-history-test'),
+      8,
+      8,
+      true,
+    );
+    try {
+      expect(state.cloudHistoryEnabled).toBe(true);
+      expect(state.cloudRadiance).toBeDefined();
+      expect(textures).toHaveBeenCalledTimes(12);
+      expect(textures.mock.calls.slice(6).map(([desc]) => desc.label)).toEqual([
+        'cloud-history-radiance-a',
+        'cloud-history-radiance-b',
+        'cloud-history-transmittance-a',
+        'cloud-history-transmittance-b',
+        'cloud-history-depth-a',
+        'cloud-history-depth-b',
+      ]);
+    } finally {
+      retireTemporalGpuState(state);
+    }
+  });
   it('filters subpixel color reconstruction without filtering temporal metadata', async () => {
     const device = (await new RhiNullAdapter().requestDevice()).unwrap();
     const samplers = vi.spyOn(device, 'createSampler');

package/src/__tests__/temporal-performance.integration.test.ts

@@ -210,7 +210,7 @@ describe('temporal motion blur performance evidence', () => {
     const evidence = createCorrectnessEvidence(
       {
         backend: 'webgpu',
-        framesObserved: 300,
+        framesObserved: 60,
         temporal: { status: 'stable', historyValid: true, historyAttempt: 'committed', epoch: 300 },
         temporalTarget: {
           identity: 'standard-scene-temporal',
@@ -441,7 +441,7 @@ describe('temporal motion blur performance evidence', () => {
     const assembled = assemblePerformanceAdmissionEvidence(
       {
         backend: 'webgpu',
-        framesObserved: 300,
+        framesObserved: 60,
         errors: [],
         drawErrors: [],
         resolution: { width: 1920, height: 1080 },
@@ -543,7 +543,7 @@ describe('temporal motion blur performance evidence', () => {
       assemblePerformanceAdmissionEvidence(
         {
           backend: 'webgpu',
-          framesObserved: 300,
+          framesObserved: 60,
           errors: [],
           drawErrors: [],
           resolution: { width: 1920, height: 1080 },

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

@@ -6,23 +6,17 @@ import { Instances } from '../components/instances';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
-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]);
 
-function spawnInstance(
-  world: World,
-  instanceCollections: InstanceCollectionStore,
-  state: keyof typeof VisibilityStateValue,
-) {
-  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
+function spawnInstance(world: World, state: keyof typeof VisibilityStateValue) {
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { collectionId } },
+      { component: Instances, data: { transforms: new Float32Array(IDENTITY) } },
       { component: Visibility, data: { state: VisibilityStateValue[state] } },
     )
     .unwrap();
@@ -31,12 +25,9 @@ function spawnInstance(
 describe('visibility instance producer gate', () => {
   it('gates an explicit Instances owner before producing a renderable', () => {
     const world = new World();
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = spawnInstance(world, instanceCollections, 'hidden');
+    const entity = spawnInstance(world, 'hidden');
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
 
     expect(frame.renderables.some((item) => item.entityKey === entity)).toBe(false);
     expect(frame.dispatch.some((item) => item.entityIndex === 0)).toBe(false);
@@ -44,13 +35,10 @@ describe('visibility instance producer gate', () => {
 
   it('keeps visible members of a mixed batch independent from hidden members', () => {
     const world = new World();
-    const instanceCollections = new InstanceCollectionStore();
-    spawnInstance(world, instanceCollections, 'hidden');
-    const visible = spawnInstance(world, instanceCollections, 'visible');
+    spawnInstance(world, 'hidden');
+    const visible = spawnInstance(world, 'visible');
 
-    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
-      instanceCollections,
-    });
+    const frame = extractFrames([world], 0);
 
     expect(frame.renderables.map((item) => item.entityKey)).toEqual([visible]);
     expect(frame.dispatch.length).toBe(2);

package/src/__tests__/visibility-producer-matrix.integration.test.ts

@@ -11,7 +11,6 @@ import { SpriteInstances } from '../components/sprite-instances';
 import { TileLayer } from '../components/tile-layer';
 import { Tilemap } from '../components/tilemap';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
-import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 import { classifySceneDataCoverage } from '../temporal/coverage';
 import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
@@ -20,7 +19,7 @@ const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
 
 type ProducerCase = {
   readonly name: string;
-  readonly setup: (world: World, instanceCollections: InstanceCollectionStore) => EntityHandle;
+  readonly setup: (world: World) => EntityHandle;
 };
 
 function staticMesh(world: World): EntityHandle {
@@ -61,33 +60,25 @@ function spriteMesh(world: World): EntityHandle {
     .unwrap();
 }
 
-function autoFoldInstances(
-  world: World,
-  instanceCollections: InstanceCollectionStore,
-): EntityHandle {
-  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
+function autoFoldInstances(world: World): EntityHandle {
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { collectionId } },
+      { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
 }
 
-function explicitInstances(
-  world: World,
-  instanceCollections: InstanceCollectionStore,
-): EntityHandle {
-  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
+function explicitInstances(world: World): EntityHandle {
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { collectionId } },
+      { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
@@ -141,20 +132,18 @@ describe('visibility built-in producer matrix', () => {
 
   it.each(PRODUCERS)('$name is hidden, visible, then restorable', ({ setup }) => {
     const world = new World();
-    const instanceCollections = new InstanceCollectionStore();
-    const entity = setup(world, instanceCollections);
+    const entity = setup(world);
 
-    const options = { instanceCollections };
-    const hidden = extractFrames([world], 0, undefined, undefined, undefined, options);
+    const hidden = extractFrames([world], 0);
     expect(hidden.renderables).toHaveLength(0);
     expect(hidden.dispatch).toHaveLength(0);
 
     world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
-    const visible = extractFrames([world], 0, undefined, undefined, undefined, options);
+    const visible = extractFrames([world], 0);
     expect(visible.visibilitySnapshots[0]?.get(entity)?.effective).toBe('visible');
 
     world.set(entity, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
-    const restored = extractFrames([world], 0, undefined, undefined, undefined, options);
+    const restored = extractFrames([world], 0);
     expect(restored.renderables).toHaveLength(0);
     expect(restored.dispatch).toHaveLength(0);
   });

package/src/__tests__/volume-optics-oracle.unit.test.ts

@@ -35,9 +35,11 @@ describe('volumetric optics CPU oracle', () => {
   it('does not apply density twice to single-scatter radiance', () => {
     expect(integrateShader).not.toContain('phase * sample.g * sample.r * (1.0 - transmittance)');
     expect(integrateShader).toContain(
-      'let local_scatter = radiance * volume_params.albedo.xyz * phase *',
+      'source += radiance * volume_params.albedo.xyz * phase * VOLUME_LIGHT_PHASE_SCALE * sigma;',
+    );
+    expect(integrateShader).toContain(
+      'let local_scatter = source * (1.0 - local_transmittance) / max(extinction, EPSILON) +',
     );
-    expect(integrateShader).toContain('VOLUME_LIGHT_PHASE_SCALE * (1.0 - local_transmittance) +');
   });
 
   it('converts the shared integrated-light basis once before normalized HG', () => {

package/src/__tests__/volumetric-fog-budget-recovery.integration.test.ts

@@ -406,7 +406,9 @@ describe('volumetric fog budget and recovery contract', () => {
     );
   });
 
-  it('uses the canonical World clock to bound real volume history reuse', async () => {
+  it.each([
+    1, 2,
+  ])('uses the canonical World clock for %i owners and bounds real history reuse', async (ownerCount) => {
     const queue = new RecordingNullQueue();
     const adapter = new RecoverableNullAdapter(() => queue);
     const backend = {
@@ -441,22 +443,23 @@ describe('volumetric fog budget and recovery contract', () => {
         data: { direction: [-0.4, -0.8, -0.3], castShadow: true },
       })
       .unwrap();
-    world
-      .spawn({
-        component: VolumetricFog,
-        data: {
-          light: sun,
-          density,
-          boundsMin: [-1, -1, -1],
-          boundsMax: [1, 1, 1],
-          extinction: [0.2, 0.2, 0.2],
-          albedo: [0.8, 0.8, 0.8],
-          emission: [0, 0, 0],
-          anisotropy: 0,
-          maxDistance: 50,
-        },
-      })
-      .unwrap();
+    for (let owner = 0; owner < ownerCount; owner++)
+      world
+        .spawn({
+          component: VolumetricFog,
+          data: {
+            light: sun,
+            density,
+            boundsMin: [-1, -1, -1],
+            boundsMax: [1, 1, 1],
+            extinction: [0.2, 0.2, 0.2],
+            albedo: [0.8, 0.8, 0.8],
+            emission: [0, 0, 0],
+            anisotropy: 0,
+            maxDistance: 50,
+          },
+        })
+        .unwrap();
 
     const lease = renderer.attach(world);
     expect(lease.ok).toBe(true);
@@ -477,10 +480,17 @@ describe('volumetric fog budget and recovery contract', () => {
       if (!frame.ok) return { history: -1, worldTime: -1, delta: -1 };
       expect((await frame.value.completed).ok).toBe(true);
       const paramsWrite = queue.writes
-        .filter((write) => write.offset === 0 && write.bytes.byteLength === 144)
+        .filter(
+          (write) => write.offset === 0 && write.bytes.byteLength === VOLUMETRIC_FOG_PARAMS_BYTES,
+        )
         .at(-1);
       expect(paramsWrite).toBeDefined();
       if (paramsWrite === undefined) return { history: -1, worldTime: -1, delta: -1 };
+      const params = new Float32Array(paramsWrite.bytes.buffer, paramsWrite.bytes.byteOffset);
+      expect(params[3]).toBe(ownerCount);
+      for (let owner = 0; owner < ownerCount; owner++) {
+        expect(params[(owner + 1) * 36 + 32]).toBeCloseTo(world.getResource(Time).elapsed, 5);
+      }
       const historyWrite = queue.writes
         .filter(
           (write) =>
@@ -559,7 +569,7 @@ describe('volumetric fog budget and recovery contract', () => {
     expect(resolved?.extent).toEqual({ width: 960, height: 540, depthOrArrayLayers: 1 });
   });
 
-  it('keeps one real Renderer volume generation through 20 resizes, 3 recoveries, and 300 frames', async () => {
+  it('keeps one real Renderer volume generation through 20 resizes, 3 recoveries, and 60 frames', async () => {
     const adapter = new RecoverableNullAdapter();
     const backend = {
       ...nullRhi,
@@ -766,7 +776,7 @@ describe('volumetric fog budget and recovery contract', () => {
       readonly totalBytes: number;
       readonly physicalResourceCount: number;
     }> = [];
-    for (let frame = 0; frame < 300; frame += 1) {
+    for (let frame = 0; frame < 60; frame += 1) {
       const inspection = await draw();
       const facts = inspection?.volumetricFog?.resourceFacts;
       expect(facts).toBeDefined();

package/src/__tests__/volumetric-fog-errors.unit.test.ts

@@ -1,6 +1,7 @@
 import type { EntityHandle } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
 import { type VolumetricFogAuthoring, validateVolumetricFog } from '../volume/component';
+import { extractVolumetricFog } from '../volume/extract';
 
 const base: VolumetricFogAuthoring = {
   light: 1 as EntityHandle,
@@ -32,12 +33,12 @@ describe('VolumetricFog structured error contract', () => {
     }
   });
 
-  it('keeps owner conflict as a closed error instead of creating a second volume', () => {
-    const result = validateVolumetricFog({ ...base, ownerCount: 2 });
+  it('keeps volume budget overflow as a closed error', () => {
+    const result = extractVolumetricFog(Array.from({ length: 9 }, () => base));
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.error.code).toBe('volume-owner-conflict');
-      expect(result.error.detail).toMatchObject({ ownerCount: 2 });
+      expect(result.error.detail).toMatchObject({ ownerCount: 9 });
     }
   });
 

package/src/__tests__/volumetric-fog-multiple.unit.test.ts

@@ -0,0 +1,55 @@
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import type { VolumetricFogAuthoring } from '../volume/component';
+import { extractVolumetricFog } from '../volume/extract';
+
+const fog: VolumetricFogAuthoring = {
+  light: 0 as EntityHandle,
+  density: {
+    guid: 'smoke-a',
+    generation: 1,
+    format: 'r8unorm',
+    colorSpace: 'linear',
+    shape: { viewDimension: '3d', extent: { width: 16, height: 16, depth: 16 } },
+  },
+  bounds: { min: [-1, -1, -1], max: [1, 1, 1] },
+  extinction: [1, 1, 1],
+  albedo: [0.8, 0.8, 0.8],
+  emission: [0, 0, 0],
+  anisotropy: 0,
+  maxDistance: 20,
+};
+
+describe('independent local volumetric fog owners', () => {
+  it('accepts overlapping owners and retains their distinct optical properties', () => {
+    const second = { ...fog, emission: [1, 0, 0] as const };
+    const result = extractVolumetricFog([fog, second]);
+    expect(result.ok).toBe(true);
+    if (result.ok && result.value.status === 'available') {
+      expect(result.value.fogs).toHaveLength(2);
+      expect(result.value.fogs[1]?.emission).toEqual([1, 0, 0]);
+    }
+  });
+  it('validates every owner, not only the first', () => {
+    const result = extractVolumetricFog([fog, { ...fog, anisotropy: 2 }]);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('volume-invalid-parameters');
+  });
+  it('removes one owner independently and turns off only after the last', () => {
+    const result = extractVolumetricFog([fog]);
+    expect(result.ok && result.value.status === 'available' && result.value.fogs.length).toBe(1);
+    expect(extractVolumetricFog([])).toEqual({ ok: true, value: { status: 'off' } });
+  });
+  it('rejects overflow explicitly instead of dropping visible owners', () => {
+    const result = extractVolumetricFog(Array.from({ length: 9 }, () => fog));
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('volume-owner-conflict');
+  });
+  it('rejects unknown sampling modes in untyped input', () => {
+    const result = extractVolumetricFog([
+      { ...fog, sampling: 'unknown' } as unknown as VolumetricFogAuthoring,
+    ]);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('volume-invalid-parameters');
+  });
+});

package/src/__tests__/volumetric-fog-spot-frame-optics.integration.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 
-const frame = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+const frame = readFileSync(new URL('../record/volume-params.ts', import.meta.url), 'utf8');
 
 describe('volumetric Spot frame optics', () => {
   it('passes extracted colorTimesIntensity through once', () => {