@forgeax/engine-shader 0.1.23 → 0.1.24

package/src/default_standard_surface.wgsl

@@ -0,0 +1,88 @@
+#define_import_path forgeax_material::default_standard_surface
+
+#import forgeax_material::surface_v1::{SurfaceInput, SurfaceData}
+
+// The default Surface owns only base facts. Standard's generated Material
+// interface remains the source of the scalar and texture values; the
+// Standard template owns physical-layer selection and lighting.
+fn surfaceUv(input : SurfaceInput, transform : vec4<f32>, metadata : vec4<f32>) -> vec2<f32> {
+  let source = select(input.uv0, input.uv1, metadata.x >= 1.0);
+  let scaled = source * transform.zw;
+  let c = cos(metadata.y);
+  let s = sin(metadata.y);
+  return vec2<f32>(scaled.x * c - scaled.y * s, scaled.x * s + scaled.y * c) + transform.xy;
+}
+
+fn surfaceChannel(value : vec4<f32>, channel : u32) -> f32 {
+  switch (channel) {
+    case 0u: { return value.r; }
+    case 1u: { return value.g; }
+    case 2u: { return value.b; }
+    default: { return value.a; }
+  }
+}
+
+fn surfaceNormal(input : SurfaceInput, encoded : vec4<f32>, normalScale : f32) -> vec3<f32> {
+  let tangentXY = (encoded.rg * 2.0 - vec2<f32>(1.0)) * normalScale;
+  let tangentZ = sqrt(max(1.0 - dot(tangentXY, tangentXY), 0.0));
+  let geometric = normalize(input.geometricNormalWS);
+  let tangent = normalize(input.tangentWS.xyz - geometric * dot(geometric, input.tangentWS.xyz));
+  let bitangent = normalize(cross(geometric, tangent)) * input.tangentWS.w;
+  return normalize(tangent * tangentXY.x + bitangent * tangentXY.y + geometric * tangentZ);
+}
+
+fn evaluate_surface(input : SurfaceInput) -> SurfaceData {
+  let baseSample = textureSample(
+    baseColorTexture,
+    baseColorSampler,
+    surfaceUv(input, material.baseColorTextureCoordinatesTransform, material.baseColorTextureCoordinatesMetadata) * material.baseColorTextureCoordinatesMetadata.zw,
+  );
+  let metallicRoughnessSample = textureSample(
+    metallicRoughnessTexture,
+    metallicRoughnessSampler,
+    surfaceUv(input, material.metallicRoughnessTextureCoordinatesTransform, material.metallicRoughnessTextureCoordinatesMetadata) * material.metallicRoughnessTextureCoordinatesMetadata.zw,
+  );
+  let normalSample = textureSample(
+    normalTexture,
+    normalSampler,
+    surfaceUv(input, material.normalTextureCoordinatesTransform, material.normalTextureCoordinatesMetadata) * material.normalTextureCoordinatesMetadata.zw,
+  );
+  let emissiveSample = textureSample(
+    emissiveTexture,
+    emissiveSampler,
+    surfaceUv(input, material.emissiveTextureCoordinatesTransform, material.emissiveTextureCoordinatesMetadata) * material.emissiveTextureCoordinatesMetadata.zw,
+  );
+  let occlusionSample = textureSample(
+    occlusionTexture,
+    occlusionSampler,
+    surfaceUv(input, material.occlusionTextureCoordinatesTransform, material.occlusionTextureCoordinatesMetadata) * material.occlusionTextureCoordinatesMetadata.zw,
+  );
+  let vertexColor = input.vertexColor;
+  let baseColor = material.baseColor.rgb * baseSample.rgb * vertexColor.rgb;
+  let metallic = clamp(
+    material.metallic * surfaceChannel(metallicRoughnessSample, u32(material.metallicChannel)),
+    0.0,
+    1.0,
+  );
+  let roughness = clamp(
+    material.roughness * surfaceChannel(metallicRoughnessSample, u32(material.roughnessChannel)),
+    0.04,
+    1.0,
+  );
+  let emissive = material.emissive * material.emissiveIntensity * emissiveSample.rgb;
+  let occlusion = clamp(
+    1.0 + (occlusionSample.r - 1.0) * material.occlusionStrength,
+    0.0,
+    1.0,
+  );
+  return SurfaceData(
+    baseColor,
+    surfaceNormal(input, normalSample, material.normalScale),
+    metallic,
+    roughness,
+    emissive,
+    occlusion,
+    clamp(material.baseColor.a * baseSample.a * vertexColor.a, 0.0, 1.0),
+    clamp(material.alphaCutoff, 0.0, 1.0),
+  );
+}

package/src/hdrp-cluster-forward.wgsl

@@ -0,0 +1,225 @@
+// hdrp-cluster-forward.wgsl — HDRP cluster-forward punctual light evaluation.
+// feat-20260608-cluster-lighting M4 / w17.
+//
+// The cluster module owns membership and raw payload decoding only. Punctual
+// BRDF, range, cone, PCF, and fail-open behavior live in lighting-punctual.
+
+#define_import_path forgeax_hdrp::cluster_forward
+
+#import forgeax_pbr::lighting_punctual::{evalPoint, evalSpot, evalSpotShadowed}
+#import forgeax_pbr::lighting_attenuation::{projectSpotUv}
+#import forgeax_view::common::{view}
+#ifdef PROJECTOR_AVAILABLE
+#import forgeax_view::common::{projectorTexture, projectorSampler}
+#endif
+#ifdef POINT_SHADOW_AVAILABLE
+#import forgeax_pbr::lighting_punctual::{evalPointShadowed}
+#endif
+
+#ifdef CLUSTER_FORWARD_AVAILABLE
+
+const KIND_POINT: u32 = 0u;
+const KIND_SPOT: u32 = 1u;
+const PROJECTOR_ONLY_TILE: i32 = -2;
+
+// LightSlot is the byte-frozen 64B std430/std140 transport contract.
+// [0..2] position, [3] invRangeSquared
+// [4..6] colorTimesIntensity, [7] cosInner
+// [8..10] direction, [11] cosOuter
+// [12] raw kind u32, [13] shadow identity i32
+// [14] point near / spot shadow intensity f32 bits
+// [15] point far / spot PCF kernel width f32 bits
+struct LightSlot {
+  position        : vec4<f32>,
+  color           : vec4<f32>,
+  direction       : vec4<f32>,
+  kind_and_shadow : vec4<u32>,
+};
+
+const LIGHTSLOT_BYTE_SIZE: u32 = 64u;
+
+fn sampleClusterSpotProjector(lightViewProj : mat4x4<f32>, worldPos : vec3<f32>) -> vec3<f32> {
+#ifdef PROJECTOR_AVAILABLE
+  let clip = lightViewProj * vec4<f32>(worldPos, 1.0);
+  // The projector is a cookie, not an extra cone. A fragment that cannot be
+  // projected (or lies outside the tile) keeps the analytic Spot contribution
+  // intact, matching Three's SpotLightNode fail-open map gate.
+  if (abs(clip.w) < 1e-6) { return vec3<f32>(1.0); }
+  let uv = projectSpotUv(lightViewProj, worldPos);
+  if (any(uv < vec2<f32>(0.0)) || any(uv > vec2<f32>(1.0))) {
+    return vec3<f32>(1.0);
+  }
+  return textureSampleLevel(projectorTexture, projectorSampler, uv, 0.0).rgb;
+#else
+  return vec3<f32>(1.0);
+#endif
+}
+
+struct ClusterUniform {
+  grid         : vec4<u32>,
+  near_far_log : vec4<f32>,
+};
+
+#if STORAGE_BUFFER_AVAILABLE == true
+@group(2) @binding(3) var<storage, read> light_data      : array<LightSlot, 256>;
+@group(2) @binding(4) var<storage, read> cluster_grid     : array<u32>;
+@group(2) @binding(5) var<storage, read> light_index_list : array<u32>;
+#else
+@group(2) @binding(3) var<uniform> light_data_uniform : array<LightSlot, 128>;
+#endif
+@group(2) @binding(6) var<uniform> cluster_uniform : ClusterUniform;
+
+fn get_ssao_intensity() -> f32 {
+  return cluster_uniform.near_far_log.w;
+}
+
+fn view_z_to_z_slice(
+  view_z : f32,
+  grid_z : u32,
+  near   : f32,
+  far    : f32,
+  log_far_over_near : f32,
+) -> u32 {
+  if (view_z >= -near) {
+    return 0u;
+  }
+  let slice = floor(log(-view_z / near) / log_far_over_near * f32(grid_z));
+  let u_slice = u32(slice);
+  if (u_slice >= grid_z) {
+    return grid_z - 1u;
+  }
+  return u_slice;
+}
+
+fn ndc_position_to_cluster(
+  ndc     : vec3<f32>,
+  view_z  : f32,
+  grid_x  : u32,
+  grid_y  : u32,
+  grid_z  : u32,
+  near    : f32,
+  far     : f32,
+  log_far : f32,
+) -> vec3<u32> {
+  let cx = clamp(u32(floor((ndc.x * 0.5 + 0.5) * f32(grid_x))), 0u, grid_x - 1u);
+  let cy = clamp(u32(floor((ndc.y * 0.5 + 0.5) * f32(grid_y))), 0u, grid_y - 1u);
+  let cz = view_z_to_z_slice(view_z, grid_z, near, far, log_far);
+  return vec3(cx, cy, cz);
+}
+
+// Decode one kind first, then delegate the complete evaluation to the shared
+// punctual owner. Unknown kinds are explicitly zero contribution.
+fn evaluate_cluster_light(
+  light      : LightSlot,
+  world_pos  : vec3<f32>,
+  normal     : vec3<f32>,
+  view_dir   : vec3<f32>,
+  base_color : vec3<f32>,
+  metallic   : f32,
+  alpha_sq   : f32,
+  f0         : vec3<f32>,
+) -> vec3<f32> {
+  let kind = light.kind_and_shadow.x;
+  if (kind == KIND_POINT) {
+#ifdef POINT_SHADOW_AVAILABLE
+    let layer = bitcast<i32>(light.kind_and_shadow.y);
+    if (layer >= 0) {
+      return evalPointShadowed(
+        light.position.xyz, light.color.xyz, light.position.w,
+        world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+        layer,
+        bitcast<f32>(light.kind_and_shadow.z),
+        bitcast<f32>(light.kind_and_shadow.w),
+        0.005, 0.05,
+      );
+    }
+#endif
+    return evalPoint(
+      light.position.xyz, light.color.xyz, light.position.w,
+      world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+  if (kind == KIND_SPOT) {
+    let tile = bitcast<i32>(light.kind_and_shadow.y);
+    if (tile >= 0) {
+      let projector = sampleClusterSpotProjector(view.spotLightViewProj[tile], world_pos);
+      return evalSpotShadowed(
+        light.position.xyz, light.direction.xyz, light.color.xyz,
+        // LightSlot packs cosInner in color.w and cosOuter in direction.w;
+        // keep the evaluator's named cone order intact at the decode boundary.
+        light.color.w, light.direction.w, light.position.w,
+        world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+        view.spotLightViewProj[tile], tile, 0.005, 0.05,
+        clamp(
+          round(select(3.0, bitcast<f32>(light.kind_and_shadow.w),
+            bitcast<f32>(light.kind_and_shadow.w) > 0.5)),
+          1.0,
+          5.0,
+        ),
+        clamp(bitcast<f32>(light.kind_and_shadow.z), 0.0, 1.0),
+      ) * projector;
+    }
+    if (tile == PROJECTOR_ONLY_TILE) {
+      let projector = sampleClusterSpotProjector(view.spotLightViewProj[0], world_pos);
+      return evalSpot(
+        light.position.xyz, light.direction.xyz, light.color.xyz,
+        light.color.w, light.direction.w, light.position.w,
+        world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+      ) * projector;
+    }
+    return evalSpot(
+      light.position.xyz, light.direction.xyz, light.color.xyz,
+      light.color.w, light.direction.w, light.position.w,
+      world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+  return vec3<f32>(0.0);
+}
+
+fn evaluate_cluster_lights(
+  ndc        : vec3<f32>,
+  view_z     : f32,
+  world_pos  : vec3<f32>,
+  normal     : vec3<f32>,
+  view_dir   : vec3<f32>,
+  base_color : vec3<f32>,
+  metallic   : f32,
+  alpha_sq   : f32,
+  f0         : vec3<f32>,
+) -> vec3<f32> {
+  let gx = cluster_uniform.grid.x;
+  let gy = cluster_uniform.grid.y;
+  let gz = cluster_uniform.grid.z;
+  let near = cluster_uniform.near_far_log.x;
+  let far = cluster_uniform.near_far_log.y;
+  let log_far = cluster_uniform.near_far_log.z;
+  var total_radiance = vec3<f32>(0.0);
+
+#if STORAGE_BUFFER_AVAILABLE == true
+  let cluster_idx = ndc_position_to_cluster(ndc, view_z, gx, gy, gz, near, far, log_far);
+  let cluster_linear = cluster_idx.z * gy * gx + cluster_idx.y * gx + cluster_idx.x;
+  let grid_offset = cluster_linear * 2u;
+  let list_offset = cluster_grid[grid_offset];
+  let list_count = cluster_grid[grid_offset + 1u];
+  for (var i = 0u; i < list_count; i = i + 1u) {
+    let light = light_data[light_index_list[list_offset + i]];
+    total_radiance += evaluate_cluster_light(
+      light, world_pos, normal, view_dir, base_color, metallic, alpha_sq, f0,
+    );
+  }
+#else
+  let light_count = min(cluster_uniform.grid.w, 128u);
+  for (var i = 0u; i < 128u; i = i + 1u) {
+    if (i >= light_count) {
+      break;
+    }
+    total_radiance += evaluate_cluster_light(
+      light_data_uniform[i], world_pos, normal, view_dir,
+      base_color, metallic, alpha_sq, f0,
+    );
+  }
+#endif
+  return total_radiance;
+}
+
+#endif // CLUSTER_FORWARD_AVAILABLE

package/src/ibl-irradiance.wgsl

@@ -3,10 +3,12 @@
 // @forgeax/engine-shader - ibl-irradiance.wgsl
 // (feat-20260520-skylight-ibl-cubemap M3 / t44).
 //
-// Diffuse irradiance convolution. Per LearnOpenGL §6.2.2: hemisphere
-// Riemann sum (sampleDelta = 0.025) integrates the env cubemap to produce
-// the convolved irradiance cubemap consumed by sampleIblDiffuse() at
-// runtime.
+// Diffuse irradiance convolution. Per LearnOpenGL §6.2.2: a bounded
+// hemisphere Riemann sum (sampleDelta = 0.05) integrates the env cubemap to
+// produce the convolved irradiance cubemap consumed by sampleIblDiffuse() at
+// runtime. The budget is deliberately bounded for the rgba16float bake target
+// so every backend completes the fragment without overflowing its shader
+// work budget.
 //
 // @group(0) = per-face viewProj uniform.
 // @group(1) = env cubemap (texture_cube<f32>) + sampler. This is the same
@@ -36,7 +38,25 @@ struct CubemapFaceUniforms {
 @group(1) @binding(0) var envCube: texture_cube<f32>;
 @group(1) @binding(1) var envSamplerS: sampler;
 
-const IRRADIANCE_SAMPLE_DELTA: f32 = 0.025;
+const IRRADIANCE_SAMPLE_DELTA: f32 = 0.05;
+
+// The bake target is rgba16float, so a sample is admissible only when all of
+// its lanes can be represented by that format. Equality catches NaN while
+// the bound also rejects infinities before they enter the running sum.
+fn irradianceFiniteScalar(value: f32) -> bool {
+  return value == value && abs(value) <= 65504.0;
+}
+
+fn irradianceFiniteVec3(value: vec3<f32>) -> bool {
+  return irradianceFiniteScalar(value.x) &&
+         irradianceFiniteScalar(value.y) &&
+         irradianceFiniteScalar(value.z);
+}
+
+fn irradianceSanitizeScalar(value: f32) -> f32 {
+  let bounded = clamp(value, 0.0, 65504.0);
+  return select(0.0, bounded, irradianceFiniteScalar(value));
+}
 
 @vertex
 fn cubemap_vs(in0: CubemapVsIn) -> CubemapVsOut {
@@ -76,8 +96,18 @@ fn irradianceConvolve_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
       let sampleColor = textureSampleLevel(
         envCube, envSamplerS, sampleVec, 0.0,
       ).rgb;
-      irradiance += sampleColor * cos(theta) * sin(theta);
-      nrSamples += 1.0;
+      // A malformed direction or backend sample must not poison the whole
+      // irradiance face. Skip only non-finite samples and keep the
+      // normalization count in lockstep with the accumulated radiance.
+      let sampleWeight = cos(theta) * sin(theta);
+      if (
+        irradianceFiniteVec3(sampleVec) &&
+        irradianceFiniteVec3(sampleColor) &&
+        irradianceFiniteScalar(sampleWeight)
+      ) {
+        irradiance += sampleColor * sampleWeight;
+        nrSamples += 1.0;
+      }
       theta += IRRADIANCE_SAMPLE_DELTA;
     }
     phi += IRRADIANCE_SAMPLE_DELTA;
@@ -88,5 +118,10 @@ fn irradianceConvolve_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
   // consumes this payload directly; applying another Lambert divide would
   // darken diffuse IBL by PI.
   irradiance = PI * irradiance / max(nrSamples, 1.0);
-  return vec4<f32>(irradiance, 1.0);
+  return vec4<f32>(
+    irradianceSanitizeScalar(irradiance.x),
+    irradianceSanitizeScalar(irradiance.y),
+    irradianceSanitizeScalar(irradiance.z),
+    1.0,
+  );
 }

package/src/ibl-prefilter.wgsl

@@ -36,8 +36,10 @@ struct CubemapFaceUniforms {
 struct PrefilterUniforms {
   roughness: f32,
   faceSize: f32,
+  // Actual mip count of the source cube bound at group(1). The source cube is
+  // currently base-level-only; the value prevents sampling an unallocated mip.
+  sourceMipLevelCount: f32,
   // Keep the uniform block 16-byte aligned on WebGL2 downlevel backends.
-  _pad0: f32,
   _pad1: f32,
 };
 
@@ -48,6 +50,7 @@ struct PrefilterUniforms {
 @group(1) @binding(1) var envSamplerS: sampler;
 
 const PREFILTER_SAMPLE_COUNT: u32 = 1024u;
+const PREFILTER_MIP_LEVEL_COUNT: f32 = 5.0;
 
 @vertex
 fn cubemap_vs(in0: CubemapVsIn) -> CubemapVsOut {
@@ -78,16 +81,23 @@ fn prefilterEnv_fs(in0: CubemapVsOut) -> @location(0) vec4<f32> {
       let D0 = iblDGGX(max(dot(N, H), 0.0), roughness);
       let NdotH0 = max(dot(N, H), 0.0);
       let HdotV = max(dot(H, V), 0.0);
-      let pdf = D0 * NdotH0 / (4.0 * HdotV) + 0.0001;
+      // A grazing half-vector can make HdotV exactly zero. Keep the PDF
+      // finite so the mip calculation cannot feed NaN into textureSampleLevel.
+      let pdf = D0 * NdotH0 / max(4.0 * HdotV, 0.0001) + 0.0001;
 
       let resolution: f32 = 512.0;
       let saTexel = 4.0 * PI / (6.0 * resolution * resolution);
       let saSample = 1.0 / (f32(PREFILTER_SAMPLE_COUNT) * pdf + 0.0001);
 
-      let mipLevel = select(
+      let requestedMipLevel = min(select(
         0.5 * log2(saSample / saTexel),
         0.0,
         roughness == 0.0,
+      ), PREFILTER_MIP_LEVEL_COUNT - 1.0);
+      let mipLevel = clamp(
+        requestedMipLevel,
+        0.0,
+        max(prefUniforms.sourceMipLevelCount - 1.0, 0.0),
       );
 
       prefilteredColor += textureSampleLevel(

package/src/ibl-shared.wgsl

@@ -30,7 +30,10 @@ const PI: f32 = 3.14159265;
 
 // Map a direction vector to equirectangular UV.
 fn sampleSphericalMap(v: vec3<f32>) -> vec2<f32> {
-  let uv = vec2<f32>(atan2(v.z, v.x), asin(v.y));
+  // Cube-face rasterization can produce a direction whose normalized Y lane
+  // is a few ulps outside [-1, 1]. `asin` propagates that rounding error as
+  // NaN, poisoning the generated cubemap and every later IBL sample.
+  let uv = vec2<f32>(atan2(v.z, v.x), asin(clamp(v.y, -1.0, 1.0)));
   return uv * INV_ATAN + 0.5;
 }
 
@@ -87,7 +90,11 @@ fn importanceSampleGGX(Xi: vec2<f32>, N: vec3<f32>, roughness: f32) -> vec3<f32>
   let a = roughness * roughness;
 
   let phi = 2.0 * PI * Xi.x;
-  let cosTheta = sqrt(max((1.0 - Xi.y) / (1.0 + (a * a - 1.0) * Xi.y), 0.0));
+  // The production Hammersley domain is i < N, so Xi.y stays below one.
+  // Retain a finite lower bound for callers that provide an endpoint sample
+  // directly; this is defensive input handling, not the production NaN fix.
+  let denominator = max(1.0 + (a * a - 1.0) * Xi.y, 1e-5);
+  let cosTheta = sqrt(max((1.0 - Xi.y) / denominator, 0.0));
   let sinTheta = sqrt(max(1.0 - cosTheta * cosTheta, 0.0));
 
   // GGX half-vector in tangent space.

package/src/index.ts

@@ -68,9 +68,15 @@ export {
   DEFAULT_SPRITE_PARAM_SCHEMA,
   DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_BASE_PARAM_SCHEMA,
   STANDARD_PBR_ALPHA_CUTOFF_DEFAULT,
   STANDARD_PBR_ARTIFACT_RECEIPT,
   STANDARD_PBR_SKIN_ARTIFACT_RECEIPT,
+  STANDARD_PHYSICAL_LAYER_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_TEXTURE_FIELDS,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+  type StandardPhysicalTextureField,
+  standardPhysicalTextureFields,
 } from './material-schemas.js';
 export {
   registerDefaultSpriteLit,

package/src/lighting-directional.wgsl

@@ -408,7 +408,9 @@ fn evalDirectionalNoShadow(
   F0         : vec3<f32>,
 ) -> vec3<f32> {
   let l = normalize(-view.lightDir);
-  let h = normalize(viewDir + l);
+  let halfVector = viewDir + l;
+  let halfVectorLengthSquared = max(dot(halfVector, halfVector), 1e-8);
+  let h = halfVector * inverseSqrt(halfVectorLengthSquared);
   let nDotL = max(dot(normal, l), 0.0);
   let nDotV = max(dot(normal, viewDir), 1e-5);
   let nDotH = max(dot(normal, h), 0.0);

package/src/lighting-spot-modifiers.wgsl

@@ -67,7 +67,14 @@ fn spotModifierFactors(
     ies = max(textureSampleLevel(iesProfileTexture, spotModifierSampler, iesUv, metadata.z, 0.0).r, 0.0);
   }
 
-  if (metadata.w != 0xffffffffu && (metadata.y & PROJECTOR_FLAG) == 0u) {
+  // The shadow lane uses 0xffffffff as its no-shadow sentinel. That value
+  // contains PROJECTOR_FLAG bits, so test the sentinel before interpreting
+  // the lane as a projector marker; otherwise every non-shadow Cookie spot
+  // silently takes the projector exclusion path.
+  if (
+    metadata.w != 0xffffffffu &&
+    (metadata.y == 0xffffffffu || (metadata.y & PROJECTOR_FLAG) == 0u)
+  ) {
     if (depth <= 0.0) {
       cookie = vec3<f32>(0.0);
     } else {

package/src/lighting-spot-projector.wgsl

@@ -0,0 +1,31 @@
+#define_import_path forgeax_pbr::lighting_spot_projector
+
+// Clustered Standard owns the light membership/decode, while this helper
+// keeps projector projection and resource sampling in one module. Keeping the
+// projection/sample pair out of standard-cluster avoids a naga-oil scope edge
+// when the low-resource projector path is composed with the shared cluster.
+#import forgeax_pbr::lighting_attenuation::{projectSpotUv}
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+#import forgeax_view::common::{spotModifierSampler, cookieTexture}
+#else
+#import forgeax_view::common::{projectorTexture, projectorSampler}
+#endif
+
+fn sampleStandardSpotProjector(
+  lightViewProj : mat4x4<f32>,
+  world_pos    : vec3<f32>,
+  metadata     : vec4<u32>,
+) -> vec3<f32> {
+  let uv = projectSpotUv(lightViewProj, world_pos);
+  if (!(uv.x >= 0.0 && uv.x <= 1.0 && uv.y >= 0.0 && uv.y <= 1.0)) {
+    return vec3<f32>(1.0);
+  }
+#ifdef EXTENDED_LIGHTING_AVAILABLE
+  if (metadata.w == 0xffffffffu) {
+    return vec3<f32>(1.0);
+  }
+  return textureSampleLevel(cookieTexture, spotModifierSampler, uv, metadata.w, 0.0).rgb;
+#else
+  return textureSampleLevel(projectorTexture, projectorSampler, uv, 0.0).rgb;
+#endif
+}

package/src/material/artifact-types.ts

@@ -58,7 +58,7 @@ const STANDARD_PBR_TEXTURES = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
+  'specularColorTexture',
   'emissiveTexture',
   'occlusionTexture',
   'transmissionTexture',
@@ -79,7 +79,7 @@ const STANDARD_PBR_NUMERIC_FIELDS = [
   'alphaCutoff',
   'clearcoat',
   'clearcoatRoughness',
-  'specularTint',
+  'specularColor',
   'normalScale',
   'transmission',
   'ior',

package/src/material/physical/anisotropy.wgsl

@@ -0,0 +1,26 @@
+#define_import_path forgeax_pbr::anisotropy
+
+// Engine-owned anisotropy helpers.  The root contract supplies strength and
+// rotation; the map (when present) supplies tangent direction in RG and a
+// strength multiplier in B.  Keeping the frame operation here means the
+// Standard evaluator and custom Surface share one deterministic seam.
+fn evaluateAnisotropicNormal(
+  normal : vec3<f32>,
+  tangent : vec4<f32>,
+  strength : f32,
+  rotation : f32,
+  direction : vec2<f32>,
+) -> vec3<f32> {
+  let frameTangent = normalize(tangent.xyz);
+  let handedBitangent = normalize(cross(normal, frameTangent)) * select(-1.0, 1.0, tangent.w >= 0.0);
+  var mapDirection = vec2<f32>(1.0, 0.0);
+  if (dot(direction, direction) >= 1e-6) {
+    mapDirection = normalize(direction);
+  }
+  let mappedTangent = normalize(frameTangent * mapDirection.x + handedBitangent * mapDirection.y);
+  let mappedBitangent = normalize(cross(normal, mappedTangent)) * select(-1.0, 1.0, tangent.w >= 0.0);
+  let axis = normalize(mappedTangent * cos(rotation) + mappedBitangent * sin(rotation));
+  // A bounded bent normal preserves the zero-strength isotropic path while
+  // moving only the base specular highlight for non-zero anisotropy.
+  return normalize(normal + axis * clamp(strength, -0.999, 0.999) * 0.35);
+}

package/src/material/physical/clearcoat.wgsl

@@ -0,0 +1,24 @@
+#define_import_path forgeax_pbr::clearcoat
+
+// Clearcoat is the terminal physical layer. Its Fresnel term owns both the
+// attenuation of lower layers and the weight of the coat radiance.
+// The root supplies clearcoatRoughness and clearcoatNormalScale after their
+// texture projections; this module deliberately owns only layer energy.
+fn evaluateClearcoatFresnel(viewCosine : f32, clearcoatFactor : f32) -> f32 {
+  let cosine = clamp(viewCosine, 0.0, 1.0);
+  let oneMinusCosine = 1.0 - cosine;
+  let dielectricFresnel = 0.04 + 0.96 * oneMinusCosine * oneMinusCosine *
+    oneMinusCosine * oneMinusCosine * oneMinusCosine;
+  return clamp(clearcoatFactor, 0.0, 1.0) * dielectricFresnel;
+}
+
+fn evaluateClearcoatLayer(
+  baseRadiance : vec3<f32>,
+  coatRadiance : vec3<f32>,
+  viewCosine : f32,
+  clearcoatFactor : f32,
+) -> vec3<f32> {
+  let fresnel = evaluateClearcoatFresnel(viewCosine, clearcoatFactor);
+  let attenuatedBase = baseRadiance * (1.0 - fresnel);
+  return attenuatedBase + coatRadiance * fresnel;
+}

package/src/material/physical/iridescence.wgsl

@@ -0,0 +1,23 @@
+#define_import_path forgeax_pbr::iridescence
+
+// Bounded RGB thin-film Fresnel approximation.  Thickness is deliberately
+// not clamped to min/max order: the glTF contract permits inverted bounds and
+// the caller supplies the authored interval verbatim.
+fn evaluateIridescenceFresnel(
+  baseF0 : vec3<f32>,
+  strength : f32,
+  filmIor : f32,
+  thicknessNanometres : f32,
+) -> vec3<f32> {
+  let safeStrength = clamp(strength, 0.0, 1.0);
+  let safeIor = max(filmIor, 1.0);
+  let base = clamp((safeIor - 1.0) / (safeIor + 1.0), 0.0, 1.0);
+  let phase = thicknessNanometres * 0.018;
+  let spectral = vec3<f32>(
+    0.5 + 0.5 * cos(phase),
+    0.5 + 0.5 * cos(phase + 2.0943952),
+    0.5 + 0.5 * cos(phase + 4.1887903),
+  );
+  let film = clamp(vec3<f32>(base) * spectral, vec3<f32>(0.0), vec3<f32>(1.0));
+  return clamp(mix(baseF0, film, safeStrength), vec3<f32>(0.0), vec3<f32>(1.0));
+}

package/src/material/physical/sheen.wgsl

@@ -0,0 +1,17 @@
+#define_import_path forgeax_pbr::sheen
+
+// Charlie-like grazing lobe approximation with explicit energy compensation.
+// It is evaluated below clearcoat, so the caller attenuates this result when
+// the top coat Fresnel is applied.
+fn evaluateSheenLayer(
+  baseRadiance : vec3<f32>,
+  sheenColor : vec3<f32>,
+  sheenRoughness : f32,
+  viewCosine : f32,
+) -> vec3<f32> {
+  let roughness = clamp(sheenRoughness, 0.04, 1.0);
+  let grazing = pow(1.0 - clamp(viewCosine, 0.0, 1.0), 2.0);
+  let lobe = grazing * (1.0 - 0.5 * roughness);
+  let energy = clamp(max(max(sheenColor.r, sheenColor.g), sheenColor.b), 0.0, 1.0);
+  return baseRadiance * (1.0 - energy * lobe * 0.5) + sheenColor * lobe;
+}