@forgeax/engine-shader 0.1.20 → 0.1.23

package/src/material/artifact-types.ts

@@ -1,14 +1,151 @@
 import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
 
+export interface MaterialShaderResourceSlot {
+  readonly name: string;
+  readonly parameter: string;
+  readonly kind: 'sampler' | 'texture';
+  readonly group: number;
+  readonly binding: number;
+}
+
+export interface MaterialShaderVertexInput {
+  readonly semantic: string;
+  readonly location: number;
+  readonly format: string;
+}
+
+export interface MaterialShaderArtifactReceipt {
+  readonly directEntry: string;
+  readonly sceneIndexEntry: string;
+  readonly materialRow: {
+    readonly byteLength: number;
+    readonly fields: readonly string[];
+  };
+  readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+  readonly uvSets: readonly { readonly parameter: string; readonly set: number }[];
+  readonly vertexInputs: readonly MaterialShaderVertexInput[];
+  readonly alphaMask: { readonly cutoff: string; readonly source: string };
+  readonly skinPaletteAddress?: {
+    readonly group: number;
+    readonly binding: number;
+    readonly stride: number;
+  };
+  readonly reflection: {
+    readonly layoutIdentity: string;
+    readonly resourceSlots: readonly MaterialShaderResourceSlot[];
+    readonly vertexInputs: readonly MaterialShaderVertexInput[];
+  };
+  readonly receiptIdentity: string;
+  readonly generation: number;
+}
+
 export interface MaterialShaderArtifact {
   readonly material: string;
   readonly pass: string;
   readonly wgsl: string;
   readonly layoutIdentity: string;
+  /** Naga-reflected UV set count used to derive clamp-to-last vertex aliases. */
+  readonly uvSetCount?: number;
   readonly bindings: readonly BindGroupLayoutDescriptor[];
   readonly deps: readonly string[];
   readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
   readonly specializationKey?: string;
+  /** Producer-owned ABI facts shared by direct and scene-index consumers. */
+  readonly receipt?: MaterialShaderArtifactReceipt;
+}
+
+const STANDARD_PBR_TEXTURES = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
+] as const;
+
+const STANDARD_PBR_NUMERIC_FIELDS = [
+  'baseColor',
+  'metallic',
+  'roughness',
+  'metallicChannel',
+  'roughnessChannel',
+  'aoChannel',
+  'extraChannel',
+  'emissive',
+  'emissiveIntensity',
+  'occlusionStrength',
+  'alphaCutoff',
+  'clearcoat',
+  'clearcoatRoughness',
+  'specularTint',
+  'normalScale',
+  'transmission',
+  'ior',
+  'thickness',
+  'attenuationColor',
+  'attenuationDistance',
+] as const;
+
+const STANDARD_PBR_VERTEX_INPUTS: readonly MaterialShaderVertexInput[] = [
+  { semantic: 'position', location: 0, format: 'float32x3' },
+  { semantic: 'normal', location: 1, format: 'float32x3' },
+  { semantic: 'uv', location: 2, format: 'float32x2' },
+  { semantic: 'tangent', location: 3, format: 'float32x4' },
+];
+
+function standardPbrResourceSlots(): MaterialShaderResourceSlot[] {
+  return STANDARD_PBR_TEXTURES.flatMap((parameter, index) => [
+    {
+      name: `${parameter}_sampler`,
+      parameter,
+      kind: 'sampler' as const,
+      group: 1,
+      binding: index * 2 + 1,
+    },
+    {
+      name: parameter,
+      parameter,
+      kind: 'texture' as const,
+      group: 1,
+      binding: index * 2 + 2,
+    },
+  ]);
+}
+
+/**
+ * Builds the one Standard PBR ABI receipt consumed by both material lanes.
+ * The skinned module uses the same material producer and only adds its palette
+ * address; it must retain the same receipt identity for material compatibility.
+ */
+export function createStandardPbrArtifactReceipt(skinned = false): MaterialShaderArtifactReceipt {
+  const resourceSlots = standardPbrResourceSlots();
+  const uvSets = STANDARD_PBR_TEXTURES.map((parameter) => ({ parameter, set: 0 }));
+  const vertexInputs = skinned
+    ? [
+        ...STANDARD_PBR_VERTEX_INPUTS,
+        { semantic: 'skinIndex', location: 4, format: 'uint16x4' },
+        { semantic: 'skinWeight', location: 5, format: 'float32x4' },
+      ]
+    : [...STANDARD_PBR_VERTEX_INPUTS];
+  return {
+    directEntry: 'vs_main',
+    sceneIndexEntry: 'vs_scene_index',
+    materialRow: { byteLength: 384, fields: [...STANDARD_PBR_NUMERIC_FIELDS] },
+    resourceSlots,
+    uvSets,
+    vertexInputs,
+    alphaMask: { cutoff: 'alphaCutoff', source: 'baseColor.a' },
+    ...(skinned ? { skinPaletteAddress: { group: 2, binding: 1, stride: 64 } } : {}),
+    reflection: {
+      layoutIdentity: 'standard-pbr/material-row-v1',
+      resourceSlots,
+      vertexInputs,
+    },
+    receiptIdentity: 'standard-pbr/material-row-v1',
+    generation: 1,
+  };
 }
 
 export function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact {

package/src/material-schemas.ts

@@ -1,4 +1,8 @@
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
+import {
+  createStandardPbrArtifactReceipt,
+  type MaterialShaderArtifactReceipt,
+} from './material/artifact-types.js';
 
 export const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
 
@@ -34,6 +38,14 @@ export const DEFAULT_STANDARD_PBR_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
   { name: 'thicknessTexture', type: 'texture2d' },
 ];
 
+/** The single producer receipt shared by direct and scene-index Standard PBR. */
+export const STANDARD_PBR_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt =
+  createStandardPbrArtifactReceipt();
+
+/** Skinned Standard PBR keeps the material receipt identity and adds palette ABI. */
+export const STANDARD_PBR_SKIN_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt =
+  createStandardPbrArtifactReceipt(true);
+
 export const DEFAULT_UNLIT_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
   { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
   { name: 'alphaCutoff', type: 'f32', default: 0 },

package/src/register-default-sprite-lit.ts

@@ -56,12 +56,9 @@ export interface SpriteLitCaps {
  * compiled by @forgeax/engine-vite-plugin-shader at build time and surfaced
  * in manifest.json. The caller reads it from the manifest entries.
  *
- * `caps.storageBuffer` switches the runtime BGL buffer types for
- * @group(0) bindings 1+2 (pointLightsBuffer / spotLightsBuffer):
- * `false` -> uniform fallback (AC-10 WebGL2 path); `true` -> read-only-storage.
- * The BGL itself is built downstream in runtime/pbr-pipeline.ts (sprite-lit
- * reuses pbr-view / pbr-mesh-array / pbr-instances unchanged; AC-07
- * BGL byte-identical).
+ * `caps.storageBuffer` is retained for the shared mesh/instance layout
+ * selection. Sprite-lit local lighting reads the same Standard Cluster group
+ * as PBR; the view group has no direct point/spot arrays.
  *
  * @param registry ShaderRegistry instance (engine boot path).
  * @param composedWgsl Post-naga_oil composed WGSL source string.

package/src/scene-temporal.wgsl

@@ -27,17 +27,23 @@ fn sceneTemporalUv(clip : vec4<f32>) -> vec2<f32> {
   return vec2<f32>(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
 }
 
-fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
-  let perspectiveDepth = max(clip.w, 0.0);
+// Signed view-space Z shared by temporal reconstruction and Standard Cluster
+// lookup. Both CPU and WGSL binners consume the negative camera-space depth:
+// perspective uses -clip.w, while orthographic depth is reconstructed from
+// the projection's near/far payload rather than Euclidean world distance.
+fn sceneViewZ(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
   let ndcDepth = clip.z / max(abs(clip.w), 1e-6);
-  let orthographicDepth = temporalProjection.x +
-    ndcDepth * (temporalProjection.y - temporalProjection.x);
-  let viewDepth = select(
-    perspectiveDepth,
-    max(orthographicDepth, 0.0),
+  let orthographicViewZ = -(temporalProjection.x +
+    ndcDepth * (temporalProjection.y - temporalProjection.x));
+  return select(
+    -clip.w,
+    orthographicViewZ,
     temporalProjection.z >= 0.5,
   );
-  return log2(1.0 + viewDepth);
+}
+
+fn sceneTemporalViewDepth(clip : vec4<f32>, temporalProjection : vec4<f32>) -> f32 {
+  return log2(1.0 + max(-sceneViewZ(clip, temporalProjection), 0.0));
 }
 
 fn packSceneTemporalV1(

package/src/shadow-pcf.wgsl

@@ -20,6 +20,49 @@
 //
 // Return: 1.0 = fully lit, 0.0 = fully shadowed.
 
+// === Directional PCSS sampling primitives ====================================
+//
+// These functions deliberately accept tile bounds from their caller. They own
+// only integer addressing, raw depth, comparison sampling, and the shared
+// receiver-bias equation; cascade selection, profile selection, blocker
+// averaging, penumbra sizing, and cascade blending remain Directional policy.
+
+fn shadow_clamp_texel_to_tile(
+  texel      : vec2<i32>,
+  tileOrigin : vec2<i32>,
+  tileSize   : vec2<i32>,
+  inset      : i32,
+) -> vec2<i32> {
+  let tileMin = tileOrigin + vec2<i32>(inset);
+  let tileMax = tileOrigin + max(vec2<i32>(inset), tileSize - vec2<i32>(1 + inset));
+  return min(tileMax, max(tileMin, texel));
+}
+
+fn shadow_load_raw_depth(
+  shadowMap : texture_depth_2d,
+  texel     : vec2<i32>,
+) -> f32 {
+  return textureLoad(shadowMap, texel, 0);
+}
+
+fn shadow_sample_compare(
+  shadowMap    : texture_depth_2d,
+  shadowSampler: sampler_comparison,
+  uv           : vec2<f32>,
+  depthRef     : f32,
+) -> f32 {
+  return textureSampleCompareLevel(shadowMap, shadowSampler, uv, depthRef);
+}
+
+fn shadow_biased_receiver_depth(
+  receiverDepth : f32,
+  normalBias    : f32,
+  depthBias     : f32,
+  nDotL         : f32,
+) -> f32 {
+  return receiverDepth - max(normalBias * (1.0 - nDotL), depthBias);
+}
+
 // 3x3 integer offset table for PCF kernel (9 taps).
 // Extracted from lighting-directional.wgsl inline loop (T-M2-4);
 // `sample_shadow_2d` walks all 9 taps; `sample_shadow_cube_hw2x2` does NOT
@@ -99,7 +142,7 @@ fn sample_shadow_2d_kernel(
 // `shadowAtlas` is @group(0) @binding(5) texture_depth_cube_array.
 // `shadowSampler` is @group(0) @binding(4) sampler_comparison (shared with
 // directional shadows — same sampler type, no dimension distinction).
-// `lightLocal` is the fragment-to-light direction vector in the cubemap's
+// `lightLocal` is the light-to-fragment direction vector in the cubemap's
 // coordinate system (Bevy convention: left-handed cubemap; caller applies
 // flip_z = vec3(1,1,-1) to convert right-hand world to left-hand cubemap).
 // `layer` is the cube_array layer index (i32; 0..3 for 4 shadow-casting

package/src/sprite-lit.wgsl

@@ -1,8 +1,12 @@
 #pragma variant_axis STORAGE_BUFFER_AVAILABLE
+#pragma variant_axis CLUSTER_FORWARD_AVAILABLE
 #define_import_path forgeax_material::sprite-lit
 
-#import forgeax_view::common::{View, Mesh, InstanceData, PointLight, SpotLight, view, meshes, instances, pointLightsBuffer, spotLightsBuffer, sampleMaterialTexture}
-#import forgeax_scene_temporal::{packSceneTemporalV1}
+#import forgeax_view::common::{View, Mesh, InstanceData, view, meshes, instances, sampleMaterialTexture, packSceneTemporal}
+#import forgeax_scene_temporal::{packSceneTemporalV1, sceneViewZ}
+#ifdef CLUSTER_FORWARD_AVAILABLE
+#import forgeax_standard::cluster::{evaluateStandardClusterLights}
+#endif
 
 // @forgeax/engine-shader - sprite-lit.wgsl
 // (tweak-20260701-sprite-lit-flat-default-drop-ndotl-for-2d).
@@ -26,7 +30,8 @@
 //   - no shadow receiver / caster
 //   - no Godot-style light_mode blends
 //   - no IBL ambient
-//   - no HDRP cluster-forward path
+//   - Standard clustered punctual lights are enabled by the
+//     CLUSTER_FORWARD_AVAILABLE variant.
 //
 // >>> AI user error self-recovery hint:
 // sprite-lit needs at least one light in scene; for unlit sprites use
@@ -34,12 +39,11 @@
 // 1 string change in MaterialAsset.passes[0].shader).
 //
 // Bindings (byte-identical to sprite.wgsl so the 4 BindGroupLayout chain is
-// reused without a per-pipeline BGL; the 4 PBR-unused entries 3..6 bind
+// reused without a per-pipeline BGL; the PBR-unused entries 3..6 bind
 // pipelineState.defaultSampler + .defaultWhiteTextureView on the host side):
 //
 //   @group(0) @binding(0) view                       uniform
-//   @group(0) @binding(1) pointLightsBuffer          storage / uniform (variant)
-//   @group(0) @binding(2) spotLightsBuffer           storage / uniform (variant)
+//   @group(2) @binding(3..6) Standard Cluster storage (selected variant)
 //   @group(1) @binding(0) material                   uniform (sprite layout
 //                                                             colorTint /
 //                                                             region /
@@ -80,16 +84,17 @@ struct VsIn {
   @location(3) tangent : vec4<f32>,
 };
 
-// VsOut carries the atlas UV plus the per-fragment world-space position.
-// The world position is emitted from the vertex stage (already computed
-// there for `out.clip`), so PointLight / SpotLight attenuation gets an
-// exact per-fragment worldPos through interpolation. This replaces the
-// earlier fragment-side reconstruction path, which collapsed under
-// multi-instance draws and could not handle the 9-slice quad layout.
+// VsOut carries the atlas UV plus the per-fragment world-space position and
+// the Standard cluster coordinates produced by the vertex stage. Fragment
+// `@builtin(position)` is framebuffer-space after rasterization, so it is not
+// a valid source for NDC cluster lookup; keep the perspective divide here and
+// interpolate the result alongside worldPos.
 struct VsOut {
   @builtin(position) clip     : vec4<f32>,
   @location(0)       uv_atlas : vec2<f32>,
   @location(1)       worldPos : vec3<f32>,
+  @location(2)       ndc      : vec3<f32>,
+  @location(3)       viewZ    : f32,
 };
 
 struct SpriteVertex {
@@ -155,6 +160,11 @@ fn vs_main(in : VsIn, @builtin(instance_index) idx : u32, @builtin(vertex_index)
   out.clip = view.worldViewProj * world;
   out.uv_atlas = vertex.uvAtlas;
   out.worldPos = world.xyz;
+  let clipPos = out.clip;
+  out.ndc = clipPos.xyz / clipPos.w;
+  // Keep the cluster depth exactly aligned with the CPU binner for both
+  // perspective and off-axis orthographic projections.
+  out.viewZ = sceneViewZ(clipPos, view.temporalProjection);
   return out;
 }
 
@@ -174,50 +184,24 @@ fn spriteLitDirectional(albedo : vec3<f32>) -> vec3<f32> {
   return albedo * view.lightColor;
 }
 
-// Flat point-light contribution. Applies the KHR-lights-punctual smooth-
-// window range attenuation only. `attenuation` is 0 outside the light's
-// range (`invRangeSquared`) and 1 at the light center; the reciprocal-square
-// term gives the physical falloff. URP cap = 4 point lights per pass.
-fn spriteLitPoint(p : PointLight, worldPos : vec3<f32>, albedo : vec3<f32>) -> vec3<f32> {
-  let toLight = p.position - worldPos;
-  let dSquared = max(dot(toLight, toLight), 1e-4);
-  let factor = 1.0 - (dSquared * p.invRangeSquared) * (dSquared * p.invRangeSquared);
-  let attenuation = max(min(factor, 1.0), 0.0) / dSquared;
-  return albedo * p.colorTimesIntensity * attenuation;
-}
-
-// Flat spot-light contribution. Same range attenuation as spriteLitPoint,
-// modulated by a smoothstep cone factor (host-side degree -> cosine
-// conversion). Spot direction only shapes the cone; it does not project
-// onto a surface normal. URP cap = 4 spot lights per pass.
-fn spriteLitSpot(s : SpotLight, worldPos : vec3<f32>, albedo : vec3<f32>) -> vec3<f32> {
-  let toLight = s.position - worldPos;
-  let dSquared = max(dot(toLight, toLight), 1e-4);
-  let l = toLight / sqrt(dSquared);
-  let factor = 1.0 - (dSquared * s.invRangeSquared) * (dSquared * s.invRangeSquared);
-  let attenuation = max(min(factor, 1.0), 0.0) / dSquared;
-  let cone = smoothstep(s.cosOuter, s.cosInner, dot(l, -s.direction));
-  return albedo * s.colorTimesIntensity * attenuation * cone;
-}
-
 // Shared shading body used by both fs_main (LDR) and fs_main_hdr (HDR).
 // The two entry points differ only in their tail-end clamp + srgb encode
 // step (LDR clamp / HDR pass-through boundary).
-fn spriteLitShadeAccum(albedo : vec3<f32>, worldPos : vec3<f32>) -> vec3<f32> {
+fn spriteLitShadeAccum(
+  albedo : vec3<f32>,
+  worldPos : vec3<f32>,
+  ndc : vec3<f32>,
+  viewZ : f32,
+) -> vec3<f32> {
   // Directional contribution (1 light, View UBO).
   var lit = spriteLitDirectional(albedo);
-  // Point-light contribution (URP cap = 4; PointLightsArray.count).
-  let pointCount = pointLightsBuffer.count;
-  for (var i : u32 = 0u; i < pointCount; i = i + 1u) {
-    let p = pointLightsBuffer.slots[i];
-    lit = lit + spriteLitPoint(p, worldPos, albedo);
-  }
-  // Spot-light contribution (URP cap = 4).
-  let spotCount = spotLightsBuffer.count;
-  for (var i : u32 = 0u; i < spotCount; i = i + 1u) {
-    let s = spotLightsBuffer.slots[i];
-    lit = lit + spriteLitSpot(s, worldPos, albedo);
-  }
+#ifdef CLUSTER_FORWARD_AVAILABLE
+  let viewDir = normalize(view.cameraPos - worldPos);
+  lit = lit + evaluateStandardClusterLights(
+    ndc, viewZ, worldPos, vec3<f32>(0.0, 0.0, 1.0),
+    viewDir, albedo, 0.0, 1.0, vec3<f32>(0.04), true,
+  );
+#endif
   return lit;
 }
 
@@ -225,7 +209,7 @@ fn spriteLitShadeAccum(albedo : vec3<f32>, worldPos : vec3<f32>) -> vec3<f32> {
 fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
   let texel = sampleMaterialTexture(baseColorTexture, baseColorSampler, in.uv_atlas, material.baseColorTextureCoordinatesMetadata.zw);
   let albedo4 = texel * material.colorTint;
-  let lit = spriteLitShadeAccum(albedo4.rgb, in.worldPos);
+  let lit = spriteLitShadeAccum(albedo4.rgb, in.worldPos, in.ndc, in.viewZ);
   // Strict clamp 0..1 before premultiplied alpha multiply keeps the LDR
   // path bounded even when a scene stacks many lights.
   let lit_rgba = clamp(vec4<f32>(lit, albedo4.a), vec4<f32>(0.0), vec4<f32>(1.0));
@@ -243,7 +227,7 @@ fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
 fn fs_main_hdr(in : VsOut) -> @location(0) vec4<f32> {
   let texel = sampleMaterialTexture(baseColorTexture, baseColorSampler, in.uv_atlas, material.baseColorTextureCoordinatesMetadata.zw);
   let albedo4 = texel * material.colorTint;
-  let lit = spriteLitShadeAccum(albedo4.rgb, in.worldPos);
+  let lit = spriteLitShadeAccum(albedo4.rgb, in.worldPos, in.ndc, in.viewZ);
   // HDR variant: do NOT clamp the lit output to [0, 1]; let the tonemap
   // pass absorb HDR values > 1. Alpha stays clamped because the premult
   // math requires alpha in [0, 1].

package/src/sprite.wgsl

@@ -152,7 +152,7 @@ fn resolveSpriteVertex(in : VsIn, idx : u32, vertex_index : u32) -> SpriteVertex
   // pivotAndSize.zw scaled the local quad AND the world matrix also scaled
   // it, producing the scale^2 visual size debt that research F-4 flagged.
   // Post-w11 there is one and only one scale source: the entity's
-  // Transform.world. The mesh's built-in vertex.pos is NOT consumed (sprite
+  // GlobalTransform.world. The mesh's built-in vertex.pos is NOT consumed (sprite
   // geometry is fully re-derived from uv + pivot) so HANDLE_QUAD's mesh.pos
   // remains a placeholder driving vertex count (4) and topology only.
   //