@forgeax/engine-render 0.1.20 → 0.1.21

package/src/components/light-helpers.ts

@@ -17,12 +17,17 @@
 import { err, ok, type Result } from '@forgeax/engine-types';
 import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
 import { ShadowInvalidConfigError } from '../errors/render';
+import { DirectionalShadowFilterValue } from './directional-shadow-filter';
 
 export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;
 export type LightValidationResult = Result<void, LightValidationError>;
 
 const RANGE_ZERO_FALLBACK_INV_R2 = 1e8;
 const DEG_TO_RAD = Math.PI / 180;
+const PCSS_RADIUS_MIN = 0.0001;
+const PCSS_RADIUS_MAX = 0.05;
+const PCSS_PENUMBRA_MIN = 1;
+const PCSS_PENUMBRA_MAX = 64;
 
 /**
  * Convert SpotLight cone half-angle (degrees) to its cosine.
@@ -97,7 +102,9 @@ export function validateDirectionalLightData(
   if (data.castShadow === false) return ok(undefined);
 
   const mapSize = (data.mapSize as number | undefined) ?? 2048;
-  if (mapSize < 1) return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  if (mapSize < 1) {
+    return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  }
   const cascadeCount = (data.cascadeCount as number | undefined) ?? 4;
   if (cascadeCount < 1 || cascadeCount > 4 || !Number.isInteger(cascadeCount)) {
     return err(new ShadowInvalidConfigError('cascadeCount', cascadeCount, 1, 4));
@@ -110,14 +117,65 @@ export function validateDirectionalLightData(
   if (cascadeBlend < 0 || cascadeBlend > 0.5) {
     return err(new ShadowInvalidConfigError('cascadeBlend', cascadeBlend, 0, 0.5));
   }
-  const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
-  if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
-  }
   const shadowDistance = (data.shadowDistance as number | undefined) ?? 200;
   if (shadowDistance <= 0) {
     return err(new ShadowInvalidConfigError('shadowDistance', shadowDistance, 0, '>'));
   }
+  const shadowFilter =
+    (data.shadowFilter as number | undefined) ?? DirectionalShadowFilterValue.pcf3;
+  const allowedFilters = Object.values(DirectionalShadowFilterValue);
+  if (!Number.isFinite(shadowFilter) || !allowedFilters.includes(shadowFilter as never)) {
+    return err(
+      new ShadowInvalidConfigError(
+        'shadowFilter',
+        shadowFilter,
+        { kind: 'allowed-values', values: allowedFilters },
+        undefined,
+        'one of [pcf1, pcf3, pcf5, pcssMedium, pcssHigh]',
+      ),
+    );
+  }
+  if (
+    shadowFilter === DirectionalShadowFilterValue.pcssMedium ||
+    shadowFilter === DirectionalShadowFilterValue.pcssHigh
+  ) {
+    const shadowAngularRadius = (data.shadowAngularRadius as number | undefined) ?? 0.00465;
+    if (!Number.isFinite(shadowAngularRadius)) {
+      return err(
+        new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
+          kind: 'range',
+          min: PCSS_RADIUS_MIN,
+          max: PCSS_RADIUS_MAX,
+        }),
+      );
+    }
+    if (shadowAngularRadius < PCSS_RADIUS_MIN || shadowAngularRadius > PCSS_RADIUS_MAX) {
+      return err(
+        new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
+          kind: 'range',
+          min: PCSS_RADIUS_MIN,
+          max: PCSS_RADIUS_MAX,
+        }),
+      );
+    }
+    const maxPenumbraTexels = (data.maxPenumbraTexels as number | undefined) ?? 32;
+    if (
+      !Number.isFinite(maxPenumbraTexels) ||
+      !Number.isInteger(maxPenumbraTexels) ||
+      maxPenumbraTexels < PCSS_PENUMBRA_MIN ||
+      maxPenumbraTexels > PCSS_PENUMBRA_MAX
+    ) {
+      return err(
+        new ShadowInvalidConfigError(
+          'maxPenumbraTexels',
+          maxPenumbraTexels,
+          { kind: 'range', min: PCSS_PENUMBRA_MIN, max: PCSS_PENUMBRA_MAX },
+          undefined,
+          'a finite integer in [1, 64]',
+        ),
+      );
+    }
+  }
   return ok(undefined);
 }
 
@@ -153,7 +211,15 @@ export function validateSpotLightData(
   }
   const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+    return err(
+      new ShadowInvalidConfigError(
+        'pcfKernelSize',
+        pcfKernelSize,
+        { kind: 'lower-bound', operator: '>=', value: 1 },
+        undefined,
+        'an odd integer >= 1',
+      ),
+    );
   }
   const shadowIntensity = (data.shadowIntensity as number | undefined) ?? 1;
   if (!Number.isFinite(shadowIntensity) || shadowIntensity < 0 || shadowIntensity > 1) {
@@ -186,7 +252,15 @@ export function validatePointLightShadowData(
   }
   const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
-    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+    return err(
+      new ShadowInvalidConfigError(
+        'pcfKernelSize',
+        pcfKernelSize,
+        { kind: 'lower-bound', operator: '>=', value: 1 },
+        undefined,
+        'an odd integer >= 1',
+      ),
+    );
   }
   return ok(undefined);
 }

package/src/components/reflection-probe.ts

@@ -0,0 +1,49 @@
+// @forgeax/engine-render - local reflection probe vocabulary.
+//
+// A ReflectionProbe is an ECS authoring fact. The renderer owns its six-face
+// capture, PMREM output, box selection, and Skylight fallback; this component
+// never carries a GPU handle or an authored material reference.
+
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { RenderIntentInvalidError } from '../errors/render';
+
+export const REFLECTION_PROBE_UPDATE_ONCE = 0;
+export const REFLECTION_PROBE_UPDATE_ON_CHANGE = 1;
+export const REFLECTION_PROBE_UPDATE_CONTINUOUS = 2;
+
+export type ReflectionProbeUpdateIntent = 'once' | 'on-change' | 'continuous';
+
+export function reflectionProbeUpdateIntentFromF32(value: number): ReflectionProbeUpdateIntent {
+  switch (value) {
+    case REFLECTION_PROBE_UPDATE_ONCE:
+      return 'once';
+    case REFLECTION_PROBE_UPDATE_ON_CHANGE:
+      return 'on-change';
+    case REFLECTION_PROBE_UPDATE_CONTINUOUS:
+      return 'continuous';
+    default:
+      throw new RenderIntentInvalidError('ReflectionProbe', value);
+  }
+}
+
+export function reflectionProbeUpdateIntentToF32(intent: ReflectionProbeUpdateIntent): number {
+  switch (intent) {
+    case 'once':
+      return REFLECTION_PROBE_UPDATE_ONCE;
+    case 'on-change':
+      return REFLECTION_PROBE_UPDATE_ON_CHANGE;
+    case 'continuous':
+      return REFLECTION_PROBE_UPDATE_CONTINUOUS;
+  }
+}
+
+export const ReflectionProbe = defineComponent('ReflectionProbe', {
+  halfExtents: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  priority: { type: 'f32', default: 0 },
+  intensity: { type: 'f32', default: 1 },
+  resolution: { type: 'u32', default: 256 },
+  updateIntent: { type: 'f32', default: REFLECTION_PROBE_UPDATE_ONCE },
+  invalidationVersion: { type: 'u32', default: 0 },
+});
+
+export type ReflectionProbeData = ShapeOf<SchemaOf<typeof ReflectionProbe>>;

package/src/environment/frame.ts

@@ -7,7 +7,7 @@ import type {
   FogCandidate,
   FogFrame,
 } from '../extract/environment';
-import { validateAtmosphereParameters } from '../extract/environment';
+import { validateAtmosphereParameters, validateFogParameters } from '../extract/environment';
 import { environmentFactSignatures } from './signature';
 
 export type { EnvironmentCandidate, EnvironmentFrame, EnvironmentSource, FogCandidate, FogFrame };
@@ -103,19 +103,6 @@ function freezeFog(candidate: FogCandidate): FogFrame {
   });
 }
 
-function validFog(candidate: FogCandidate): boolean {
-  return (
-    candidate.color.every(Number.isFinite) &&
-    Number.isFinite(candidate.density) &&
-    candidate.density >= 0 &&
-    Number.isFinite(candidate.heightFalloff) &&
-    candidate.heightFalloff >= 0 &&
-    Number.isFinite(candidate.maxOpacity) &&
-    candidate.maxOpacity >= 0 &&
-    candidate.maxOpacity <= 1
-  );
-}
-
 /** Select one immutable frame fact set for both Standard lighting lanes. */
 export function selectEnvironment(
   input: EnvironmentSelectionInput,
@@ -131,16 +118,11 @@ export function selectEnvironment(
   }
   if (input.fogs.length > 1) return err(new FogCardinalityError(input.fogs.length));
   const selectedFog = input.fogs[0];
-  if (selectedFog !== undefined && !validFog(selectedFog)) {
-    const field =
-      !Number.isFinite(selectedFog.density) || selectedFog.density < 0
-        ? 'density'
-        : !Number.isFinite(selectedFog.heightFalloff) || selectedFog.heightFalloff < 0
-          ? 'heightFalloff'
-          : 'maxOpacity';
-    return err(
-      new EnvironmentSelectionParameterError(field, selectedFog[field], 'finite and in range'),
-    );
+  if (selectedFog !== undefined) {
+    const issue = validateFogParameters(selectedFog);
+    if (issue !== undefined) {
+      return err(new EnvironmentSelectionParameterError(issue.field, issue.value, issue.expected));
+    }
   }
   const selected = input.environments[0];
   if (selected?.kind === 'atmosphere') {

package/src/environment/lifecycle.ts

@@ -62,6 +62,18 @@ export class EnvironmentLifecycle {
     });
   }
 
+  /** Retain a structured authoring failure while the active/LKG frame stays live. */
+  recordSelectionFailure(error: {
+    readonly code: string;
+    readonly detail: Readonly<Record<string, unknown>>;
+  }): void {
+    this.lastCandidateFailure = Object.freeze({
+      stage: 'prepare',
+      code: error.code,
+      detail: Object.freeze({ ...error.detail }),
+    });
+  }
+
   recordStageFailure(
     stage: EnvironmentInspectionFailure['stage'],
     generation: EnvironmentGeneration,