@forgeax/engine-runtime 0.1.20 → 0.1.21

package/src/__tests__/extract-frames-merge.test.ts

@@ -171,52 +171,26 @@ function simulateMerge(
     }
     directionalCount += f.lights.directionalCount;
   }
+  const firstDirectionalLights = frames.find(
+    (frame) => frame.lights.directional !== undefined,
+  )?.lights;
   const lights: ExtractedLights = {
     directional,
     directionalCount,
     point,
     spot,
-    lightViewProj:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.lightViewProj
-        : undefined,
-    splitPlanes:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.splitPlanes
-        : undefined,
-    cascadeCount:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.cascadeCount
-        : undefined,
-    cascadeBlend:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.cascadeBlend
-        : undefined,
-    shadowMapSize:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.shadowMapSize
-        : undefined,
-    depthBias:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.depthBias
-        : undefined,
-    normalBias:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.normalBias
-        : undefined,
-    pcfKernelSize:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.pcfKernelSize
-        : undefined,
+    lightViewProj: firstDirectionalLights?.lightViewProj,
+    splitPlanes: firstDirectionalLights?.splitPlanes,
+    cascadeCount: firstDirectionalLights?.cascadeCount,
+    cascadeBlend: firstDirectionalLights?.cascadeBlend,
+    shadowMapSize: firstDirectionalLights?.shadowMapSize,
+    depthBias: firstDirectionalLights?.depthBias,
+    normalBias: firstDirectionalLights?.normalBias,
+    directionalShadowQuality: firstDirectionalLights?.directionalShadowQuality,
+    directionalShadowError: firstDirectionalLights?.directionalShadowError,
     pointShadow: frames.flatMap((f) => f.lights.pointShadow),
-    directionalCsmConfig:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.directionalCsmConfig
-        : undefined,
-    directionalCsmDirection:
-      directional !== undefined
-        ? frames.find((f) => f.lights.directional !== undefined)?.lights.directionalCsmDirection
-        : undefined,
+    directionalCsmConfig: firstDirectionalLights?.directionalCsmConfig,
+    directionalCsmDirection: firstDirectionalLights?.directionalCsmDirection,
   };
 
   // AC-05: singletons from owner world only
@@ -433,6 +407,36 @@ describe('extractFrames merge semantics (m2-t1, AC-04/05/06)', () => {
     expect(frameB.lights.directionalCount).toBe(1);
   });
 
+  it('AC-04: first directional owner error is preserved across the merge', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: DirectionalLight,
+          data: {
+            direction: [0, -1, 0],
+            shadowFilter: 4,
+            shadowAngularRadius: 999,
+            maxPenumbraTexels: 32,
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = makeWorldWithDirectionalLight();
+    const frameA = extractFrame(worldA, prepareExtractContext(worldA));
+    const frameB = extractFrame(worldB, prepareExtractContext(worldB));
+
+    expect(frameA.lights.directionalShadowError?.code).toBe('shadow-invalid-config');
+    expect(frameB.lights.directionalShadowError).toBeUndefined();
+    const merged = simulateMerge([frameA, frameB], 0);
+    expect(merged.lights.directionalShadowError?.detail).toMatchObject({
+      field: 'shadowAngularRadius',
+      actual: 999,
+    });
+  });
+
   // ── AC-05: singleton resources from owner only ─────────────────────────────
 
   it('AC-05: skylight is taken from owner world only, non-owner ignored', () => {
@@ -624,6 +628,9 @@ describe('extractFrames cross-world directional CSM (bug-20260710)', () => {
     }
     // splitPlanes reach the component shadowDistance on the last cascade.
     expect(frame.lights.splitPlanes).toBeDefined();
+    expect(frame.lights.splitPlanes).toHaveLength(16);
+    expect(frame.lights.splitPlanes?.[1]).toBeGreaterThan(0);
+    expect(frame.lights.splitPlanes?.[2]).toBeGreaterThan(0);
   });
 
   it('single world (camera + light together) still yields non-zero lightViewProj', () => {
@@ -652,5 +659,6 @@ describe('extractFrames cross-world directional CSM (bug-20260710)', () => {
     for (let i = 0; i < (frame.lights.cascadeCount ?? 0); i++) {
       expect(isNonZeroMat(lvp?.[i])).toBe(true);
     }
+    expect(frame.lights.splitPlanes).toHaveLength(16);
   });
 });

package/src/__tests__/extract-skin-mismatch.unit.test.ts

@@ -276,7 +276,7 @@ describe('render-system-extract Skin / pbr-skin mismatch (AC-07 / w19)', () => {
     expect(frame.renderables).toHaveLength(0);
   });
 
-  it('(c) Skin + pbr-skin material + skinned mesh -> no error routed', () => {
+  it('(c) Skin + pbr-skin material without a palette allocator -> renderable and dispatch skipped', () => {
     const world = new World();
     const assets = makeAssetRegistry();
     const meshHandle = registerSkinnedMesh(world);
@@ -288,9 +288,13 @@ describe('render-system-extract Skin / pbr-skin mismatch (AC-07 / w19)', () => {
 
     const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
 
-    extractFrame(world, prepareExtractContext(world, { assets }));
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
 
     expect(errorSpy).not.toHaveBeenCalled();
+    expect(frame.renderables).toHaveLength(0);
+    expect(frame.dispatch.some((entry) => entry.materialShaderId === 'forgeax::pbr-skin')).toBe(
+      false,
+    );
   });
 
   it('(d) D-5 continue semantics: bad-skin entity skipped does NOT abort sibling extract', () => {

package/src/__tests__/frame-targets-shadow-regression.unit.test.ts

@@ -25,4 +25,17 @@ describe('frame targets shadow removal', () => {
 
     expect(resolveShadowMapSize(internals as never, lights as never)).toBe(1024);
   });
+
+  it('does not resolve a Directional atlas for the disabled topology sentinel', () => {
+    const internals = {
+      device: { limits: { maxTextureDimension2D: 2048 } },
+    };
+    const lights = {
+      directional: 'disabled',
+      shadowMapSize: 2048,
+      cascadeCount: undefined,
+    };
+
+    expect(resolveShadowMapSize(internals as never, lights as never)).toBeUndefined();
+  });
 });

package/src/__tests__/geometry.unit.test.ts

@@ -2390,20 +2390,17 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       spies.drawIndexed.mockClear();
       drawPublished(renderer, world as WorldType);
 
-      // All submesh draws share the same instanceCount (D-8).
-      // Verify drawIndexed calls carry instanceCount parameter at index 1.
+      // Mesh indexed draws carry the Instances cardinality. Fullscreen graph
+      // draws are a separate topology concern and intentionally use one
+      // instance; do not mix those two contracts in one equality assertion.
       const indexedCalls = spies.drawIndexed.mock.calls as Array<
         [number, number, number, number, number]
       >;
       const drawCalls = spies.draw.mock.calls as Array<[number, number, number, number]>;
-      const allInstanceCounts = [...indexedCalls.map((c) => c[1]), ...drawCalls.map((c) => c[1])];
-      // All instanceCounts should be identical (shared across submeshes, D-8).
-      if (allInstanceCounts.length >= 2) {
-        const first = allInstanceCounts[0];
-        for (const ic of allInstanceCounts) {
-          expect(ic).toBe(first);
-        }
-      }
+      expect(indexedCalls.length).toBeGreaterThan(0);
+      expect(indexedCalls.map((call) => call[1])).toEqual(expect.arrayContaining([4]));
+      expect(indexedCalls.every((call) => call[1] === 4)).toBe(true);
+      expect(drawCalls.every((call) => call[1] === 1)).toBe(true);
       expect(errors).toEqual([]);
     });
 

package/src/__tests__/light-gpu-byte-neutral.unit.test.ts

@@ -57,13 +57,14 @@ const emptyLights: ExtractedLights = {
   directionalCount: 0,
   point: [],
   spot: [],
+  directionalShadowError: undefined,
   lightViewProj: undefined,
   splitPlanes: undefined,
   cascadeCount: undefined,
   cascadeBlend: undefined,
   depthBias: undefined,
   normalBias: undefined,
-  pcfKernelSize: undefined,
+  directionalShadowQuality: undefined,
 } as unknown as ExtractedLights;
 
 /** Capture the single writeViewUbo payload as a Float32Array. */

package/src/__tests__/light-snapshot.test-d.ts

@@ -21,6 +21,8 @@
 // covers any .test-d.ts file in any package).
 
 import { expectTypeOf, test } from 'vitest';
+import type { DirectionalShadowQuality } from '../../../render/src/components/directional-shadow-filter';
+import type { LightValidationError } from '../../../render/src/components/light-helpers';
 import type {
   DirectionalLightSnapshot,
   ExtractedLights,
@@ -81,4 +83,10 @@ test('ExtractedLights three-bucket shape', () => {
   expectTypeOf<ExtractedLights['directionalCount']>().toEqualTypeOf<number>();
   expectTypeOf<ExtractedLights['point']>().toEqualTypeOf<readonly PointLightSnapshot[]>();
   expectTypeOf<ExtractedLights['spot']>().toEqualTypeOf<readonly SpotLightSnapshot[]>();
+  expectTypeOf<ExtractedLights['directionalShadowQuality']>().toEqualTypeOf<
+    DirectionalShadowQuality | undefined
+  >();
+  expectTypeOf<ExtractedLights['directionalShadowError']>().toEqualTypeOf<
+    LightValidationError | undefined
+  >();
 });

package/src/__tests__/lights-preservation.fixup.test.ts

@@ -0,0 +1,127 @@
+import { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
+import { Camera, PointLight, SpotLight } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import {
+  computeInvRangeSquared,
+  degToCos,
+  validatePointLightShadowData,
+  validateSpotLightData,
+} from '../../../render/src/components/light-helpers';
+import {
+  packLightSlot,
+  packPointLight,
+  packSpotLight,
+} from '../../../render/src/light-buffer-layout';
+import { buildPbrViewBglEntries } from '../../../render/src/pbr-pipeline';
+import type {
+  PointLightSnapshot,
+  SpotLightSnapshot,
+} from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+
+function pointSnapshot(): PointLightSnapshot {
+  return {
+    kind: 'point',
+    position: vec3.create(1, 2, 3),
+    color: vec3.create(2, 1, 0.5),
+    intensity: 2,
+    invRangeSquared: 0.25,
+  };
+}
+
+function spotSnapshot(): SpotLightSnapshot {
+  return {
+    kind: 'spot',
+    position: vec3.create(1, 2, 3),
+    direction: vec3.create(0, -1, 0),
+    color: vec3.create(2, 1, 0.5),
+    intensity: 2,
+    invRangeSquared: 0.25,
+    cosInner: degToCos(15),
+    cosOuter: degToCos(30),
+    castShadow: false,
+    lightViewProj: undefined,
+    mapSize: 512,
+    nearPlane: 0.1,
+    farPlane: 25,
+    shadowAtlasTile: -1,
+  };
+}
+
+describe('Point/Spot and shared-light regression guard', () => {
+  it('keeps extract facts for point range and spot cone in the shared light path', () => {
+    const world = new World();
+    const pointSpawn = world.spawn(
+      { component: Transform, data: { pos: [1, 2, 3] } },
+      { component: PointLight, data: { range: 2 } },
+    );
+    const spotSpawn = world.spawn(
+      { component: Transform, data: { pos: [4, 5, 6] } },
+      {
+        component: SpotLight,
+        data: { direction: [0, -1, 0], range: 4, innerConeDeg: 15, outerConeDeg: 30 },
+      },
+    );
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    );
+    expect(pointSpawn.ok, JSON.stringify(pointSpawn)).toBe(true);
+    expect(spotSpawn.ok, JSON.stringify(spotSpawn)).toBe(true);
+
+    const lights = extractFrame(world, prepareExtractContext(world)).lights;
+    expect(lights.point).toHaveLength(1);
+    expect(lights.point[0]?.invRangeSquared).toBeCloseTo(0.25, 6);
+    expect(lights.spot).toHaveLength(1);
+    expect(lights.spot[0]?.cosInner).toBeCloseTo(degToCos(15), 6);
+    expect(lights.spot[0]?.cosOuter).toBeCloseTo(degToCos(30), 6);
+  });
+
+  it('keeps attenuation and cone helpers as finite, shared semantic owners', () => {
+    expect(computeInvRangeSquared(2)).toBeCloseTo(0.25, 8);
+    expect(computeInvRangeSquared(0)).toBe(1e8);
+    expect(computeInvRangeSquared(Number.POSITIVE_INFINITY)).toBe(0);
+    expect(degToCos(0)).toBeCloseTo(1, 8);
+    expect(degToCos(60)).toBeCloseTo(0.5, 8);
+  });
+
+  it('keeps Point/Spot packing and the shared LightSlot discriminant intact', () => {
+    const point = pointSnapshot();
+    const spot = spotSnapshot();
+    const pointPacked = packPointLight(point);
+    const spotPacked = packSpotLight(spot);
+    const pointSlot = packLightSlot(point, { shadowAtlasLayer: 2, near: 0.1, far: 20 });
+    const spotSlot = packLightSlot(spot);
+
+    expect(pointPacked.byteLength).toBe(32);
+    expect(spotPacked.byteLength).toBe(80);
+    expect(new Uint32Array(pointSlot.buffer)[12]).toBe(0);
+    expect(new Int32Array(pointSlot.buffer)[13]).toBe(2);
+    expect(new Uint32Array(spotSlot.buffer)[12]).toBe(1);
+    expect(new Int32Array(spotSlot.buffer)[13]).toBe(-1);
+  });
+
+  it('keeps shared PBR view bindings for both storage and uniform light routes', () => {
+    const storageBindings = buildPbrViewBglEntries({ storageBuffer: true });
+    const uniformBindings = buildPbrViewBglEntries({ storageBuffer: false });
+    expect(storageBindings.map((entry) => entry.binding)).toEqual(
+      uniformBindings.map((entry) => entry.binding),
+    );
+    expect(storageBindings[1]?.buffer?.type).toBe('read-only-storage');
+    expect(storageBindings[2]?.buffer?.type).toBe('read-only-storage');
+    expect(uniformBindings[1]?.buffer?.type).toBe('uniform');
+    expect(uniformBindings[2]?.buffer?.type).toBe('uniform');
+  });
+
+  it('keeps Point/Spot pcfKernelSize validation independent of Directional quality', () => {
+    expect(
+      validatePointLightShadowData({ mapSize: 512, nearPlane: 0.1, farPlane: 20, pcfKernelSize: 5 })
+        .ok,
+    ).toBe(true);
+    expect(validateSpotLightData({ direction: [0, -1, 0], pcfKernelSize: 3 }).ok).toBe(true);
+    expect(validatePointLightShadowData({ pcfKernelSize: 2 }).ok).toBe(false);
+    expect(validateSpotLightData({ direction: [0, -1, 0], pcfKernelSize: 2 }).ok).toBe(false);
+  });
+});