@forgeax/engine-shader 0.1.28 → 0.1.29

package/src/material/artifact-types.ts

@@ -1,4 +1,11 @@
-import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
+import {
+  type BindGroupLayoutDescriptor,
+  derive,
+  type MaterialParticleInput,
+  type ParamSchemaEntry,
+  STANDARD_MATERIAL_PARAM_SCHEMA,
+  STANDARD_PHYSICAL_TEXTURE_FIELDS,
+} from '@forgeax/engine-types';
 
 export interface MaterialShaderResourceSlot {
   readonly name: string;
@@ -49,44 +56,59 @@ export interface MaterialShaderArtifact {
   readonly bindings: readonly BindGroupLayoutDescriptor[];
   readonly deps: readonly string[];
   readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
+  /** Reflection-owned dynamic values supplied by a VFX renderer. */
+  readonly particleInputs?: readonly MaterialParticleInput[];
   readonly specializationKey?: string;
   /** Producer-owned ABI facts shared by direct and scene-index consumers. */
   readonly receipt?: MaterialShaderArtifactReceipt;
 }
 
-const STANDARD_PBR_TEXTURES = [
-  'baseColorTexture',
-  'metallicRoughnessTexture',
-  'normalTexture',
-  'specularColorTexture',
-  'emissiveTexture',
-  'occlusionTexture',
-  'transmissionTexture',
-  'thicknessTexture',
-] as const;
+/**
+ * Canonical Standard material schema consumed by the scene-index row.
+ * Physical texture handles stay in the fixed injected range (26..45); their
+ * numeric factors remain in this row, after the seven stable user texture
+ * coordinate pairs. Keeping this projection beside the receipt lets the
+ * shader producer and the render-side table consume one schema identity.
+ */
+export const STANDARD_PIPELINE_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
+  STANDARD_MATERIAL_PARAM_SCHEMA.filter(
+    (entry) =>
+      !(
+        entry.type.startsWith('texture') &&
+        STANDARD_PHYSICAL_TEXTURE_FIELDS.includes(
+          entry.name as (typeof STANDARD_PHYSICAL_TEXTURE_FIELDS)[number],
+        )
+      ),
+  );
+
+const STANDARD_PIPELINE_DERIVED = derive(STANDARD_PIPELINE_PARAM_SCHEMA);
 
-const STANDARD_PBR_NUMERIC_FIELDS = [
-  'baseColor',
-  'metallic',
-  'roughness',
-  'metallicChannel',
-  'roughnessChannel',
-  'aoChannel',
-  'extraChannel',
-  'emissive',
-  'emissiveIntensity',
-  'occlusionStrength',
-  'alphaCutoff',
-  'clearcoat',
-  'clearcoatRoughness',
-  'specularColor',
-  'normalScale',
-  'transmission',
-  'ior',
-  'thickness',
-  'attenuationColor',
-  'attenuationDistance',
-] as const;
+function isNumericParam(entry: ParamSchemaEntry): boolean {
+  return (
+    entry.type === 'f32' ||
+    entry.type === 'i32' ||
+    entry.type === 'u32' ||
+    entry.type === 'vec2' ||
+    entry.type === 'vec3' ||
+    entry.type === 'vec4' ||
+    entry.type === 'color'
+  );
+}
+
+function standardPbrMaterialRowFields(): readonly string[] {
+  const coordinates = new Map(
+    STANDARD_PIPELINE_DERIVED.coordinateRecords.map((record) => [record.parameter, record]),
+  );
+  return STANDARD_PIPELINE_PARAM_SCHEMA.flatMap((entry) => {
+    if (isNumericParam(entry)) return [entry.name];
+    if (entry.type.startsWith('texture')) {
+      const record = coordinates.get(entry.name);
+      if (record === undefined) throw new Error(`missing coordinate record for ${entry.name}`);
+      return [record.transformMember, record.metadataMember];
+    }
+    return [];
+  });
+}
 
 const STANDARD_PBR_VERTEX_INPUTS: readonly MaterialShaderVertexInput[] = [
   { semantic: 'position', location: 0, format: 'float32x3' },
@@ -96,22 +118,18 @@ const STANDARD_PBR_VERTEX_INPUTS: readonly MaterialShaderVertexInput[] = [
 ];
 
 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,
-    },
-  ]);
+  return STANDARD_PIPELINE_DERIVED.resourceBindings.flatMap((resource) => {
+    if (resource.kind !== 'sampler' && resource.kind !== 'texture') return [];
+    return [
+      {
+        name: resource.name,
+        parameter: resource.parameter ?? resource.name,
+        kind: resource.kind,
+        group: 1,
+        binding: resource.binding,
+      },
+    ];
+  });
 }
 
 /**
@@ -119,38 +137,65 @@ function standardPbrResourceSlots(): MaterialShaderResourceSlot[] {
  * 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 {
+export function createStandardPbrArtifactReceipt(
+  skinned = false,
+  vertexColorAvailable = 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];
+  const uvSets = STANDARD_PIPELINE_DERIVED.coordinateRecords.map((record) => ({
+    parameter: record.parameter,
+    set: 0,
+  }));
+  const vertexInputs = [
+    ...STANDARD_PBR_VERTEX_INPUTS,
+    ...(skinned
+      ? [
+          { semantic: 'skinIndex', location: 4, format: 'uint16x4' },
+          { semantic: 'skinWeight', location: 5, format: 'float32x4' },
+        ]
+      : []),
+    ...(vertexColorAvailable ? [{ semantic: 'color', location: 13, format: 'float32x4' }] : []),
+  ];
+  const layoutIdentity = `standard-pbr/material-row-v2${vertexColorAvailable ? '/vertex-color' : ''}`;
   return {
     directEntry: 'vs_main',
     sceneIndexEntry: 'vs_scene_index',
-    materialRow: { byteLength: 384, fields: [...STANDARD_PBR_NUMERIC_FIELDS] },
+    materialRow: {
+      byteLength: STANDARD_PIPELINE_DERIVED.totalBytes,
+      fields: [...standardPbrMaterialRowFields()],
+    },
     resourceSlots,
     uvSets,
     vertexInputs,
     alphaMask: { cutoff: 'alphaCutoff', source: 'baseColor.a' },
     ...(skinned ? { skinPaletteAddress: { group: 2, binding: 1, stride: 64 } } : {}),
     reflection: {
-      layoutIdentity: 'standard-pbr/material-row-v1',
+      layoutIdentity,
       resourceSlots,
       vertexInputs,
     },
-    receiptIdentity: 'standard-pbr/material-row-v1',
-    generation: 1,
+    receiptIdentity: layoutIdentity,
+    generation: 2,
   };
 }
 
 export function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact {
   if (value === null || typeof value !== 'object') return false;
   const artifact = value as Partial<MaterialShaderArtifact>;
+  const particleInputs = artifact.particleInputs;
+  const particleInputsValid =
+    particleInputs === undefined ||
+    (Array.isArray(particleInputs) &&
+      particleInputs.every(
+        (input) =>
+          input !== null &&
+          typeof input === 'object' &&
+          typeof input.name === 'string' &&
+          typeof input.type === 'string' &&
+          typeof input.visibility === 'string' &&
+          Number.isInteger(input.lane) &&
+          input.lane >= 0,
+      ));
   return (
     typeof artifact.material === 'string' &&
     typeof artifact.pass === 'string' &&
@@ -158,6 +203,7 @@ export function isMaterialShaderArtifact(value: unknown): value is MaterialShade
     typeof artifact.layoutIdentity === 'string' &&
     Array.isArray(artifact.bindings) &&
     Array.isArray(artifact.deps) &&
-    Array.isArray(artifact.vertexInputs)
+    Array.isArray(artifact.vertexInputs) &&
+    particleInputsValid
   );
 }

package/src/material-schemas.ts

@@ -4,6 +4,7 @@ import {
   STANDARD_PHYSICAL_PARAMETER_NAMES,
 } from '@forgeax/engine-types';
 import {
+  STANDARD_PIPELINE_PARAM_SCHEMA as CANONICAL_STANDARD_PIPELINE_PARAM_SCHEMA,
   createStandardPbrArtifactReceipt,
   type MaterialShaderArtifactReceipt,
 } from './material/artifact-types.js';
@@ -13,6 +14,24 @@ export const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
 /** Shared material contract for the standard PBR and skinned PBR shaders. */
 export const DEFAULT_STANDARD_PBR_PARAM_SCHEMA = STANDARD_MATERIAL_PARAM_SCHEMA;
 
+/** Numeric WGSL override ID, stable across Naga symbol mangling. */
+export const STANDARD_TEXTURE_MASK_OVERRIDE = '64000';
+
+const standardTextureBits: ReadonlyMap<string, number> = new Map(
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) => entry.type === 'texture2d').map(
+    (entry, index) => [entry.name, 2 ** index],
+  ),
+);
+
+/** Presence follows the authored contract, never asynchronous GPU residency. */
+export function standardTextureMask(schema: readonly ParamSchemaEntry[]): number {
+  let mask = 0;
+  for (const entry of schema) {
+    if (entry.type === 'texture2d') mask |= standardTextureBits.get(entry.name) ?? 0;
+  }
+  return mask;
+}
+
 export type { StandardPhysicalTextureField } from '@forgeax/engine-types';
 /**
  * Backward-compatible export name for callers that need the physical
@@ -64,14 +83,71 @@ export const STANDARD_BASE_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
  * physical texture pairs are never included here and are appended only for a
  * root contract that declares them.
  */
-export const STANDARD_PIPELINE_PARAM_SCHEMA: readonly ParamSchemaEntry[] =
-  DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(
-    // The canonical Standard UBO keeps every numeric root coordinate,
-    // including the physical-layer tail. Physical map pairs are engine-owned
-    // resources and are injected after the stable user region.
-    (entry) =>
-      !(STANDARD_PHYSICAL_PARAMETER_NAMES.has(entry.name) && entry.type.startsWith('texture')),
-  );
+// Keep the runtime schema export on the receipt producer's canonical
+// projection.  The shader artifact, GPU Scene row, and material bind-group
+// builder must not each filter the Standard root independently.
+export const STANDARD_PIPELINE_PARAM_SCHEMA = CANONICAL_STANDARD_PIPELINE_PARAM_SCHEMA;
+
+/**
+ * Fixed material contract consumed by the VFX mesh adapters.
+ *
+ * `standard-surface.wgsl` is an authored surface rather than the generated
+ * Standard root, so its Material block must be projected explicitly when a
+ * particle shader is published. Keep the projection derived from the
+ * canonical Standard vocabulary wherever possible; only the surface-owned
+ * `specularTint` scalar and texture alias are local to this contract. The
+ * order is the WGSL ABI: numeric fields first (384 B), followed by eight
+ * sampler/texture pairs (bindings 1..16), then the shared IBL injection at
+ * bindings 17..23.
+ */
+const PARTICLE_SURFACE_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 PARTICLE_SURFACE_TEXTURE_FIELDS = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
+] as const;
+
+function particleSurfaceSchemaEntry(name: string): ParamSchemaEntry {
+  const entry = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.find((candidate) => candidate.name === name);
+  if (entry !== undefined) return entry;
+  if (name === 'specularTint') {
+    return { name, type: 'vec3', colorSpace: 'srgb', default: [1, 1, 1] };
+  }
+  if (name === 'specularTintTexture') return { name, type: 'texture2d' };
+  throw new Error(`Particle Standard Surface schema field is missing: ${name}`);
+}
+
+export const PARTICLE_MESH_SURFACE_PARAM_SCHEMA: readonly ParamSchemaEntry[] = Object.freeze([
+  ...PARTICLE_SURFACE_NUMERIC_FIELDS.map(particleSurfaceSchemaEntry),
+  ...PARTICLE_SURFACE_TEXTURE_FIELDS.map(particleSurfaceSchemaEntry),
+]);
 
 /** The single producer receipt shared by direct and scene-index Standard PBR. */
 export const STANDARD_PBR_ARTIFACT_RECEIPT: MaterialShaderArtifactReceipt =

package/src/output-encoding.wgsl

@@ -0,0 +1,10 @@
+#define_import_path forgeax_view::output_encoding
+
+// The single explicit output encoding owner for raw surface writes.
+#import forgeax_view::common::{linearToSrgbOetf}
+
+// Convert linear-LDR RGB once and preserve the source alpha channel exactly.
+fn encodeOutput(linearColor : vec3<f32>, alpha : f32) -> vec4<f32> {
+  let encoded = linearToSrgbOetf(linearColor);
+  return vec4<f32>(encoded, alpha);
+}

package/src/pbr-temporal.wgsl

@@ -43,10 +43,13 @@ fn resolvePbrTemporalReactive(
 fn projectPbrSceneTemporal(
   baseColorAlpha : f32,
   alphaCutoff : f32,
+#ifdef BASE_COLOR_TEXTURE_AVAILABLE
+  baseColorTextureEnabled : bool,
   baseColorTexture : texture_2d<f32>,
   baseColorSampler : sampler,
   transform : vec4<f32>,
   metadata : vec4<f32>,
+#endif
   currentClip : vec4<f32>,
   previousClip : vec4<f32>,
   temporalProjection : vec4<f32>,
@@ -60,6 +63,9 @@ fn projectPbrSceneTemporal(
   uv6 : vec2<f32>,
   uv7 : vec2<f32>,
 ) -> vec4<f32> {
+  var baseSample = vec4<f32>(1.0);
+#ifdef BASE_COLOR_TEXTURE_AVAILABLE
+  if (baseColorTextureEnabled) {
   let baseUv = transformedPbrTemporalUv(
     transform,
     metadata,
@@ -72,12 +78,14 @@ fn projectPbrSceneTemporal(
     uv6,
     uv7,
   );
-  let baseSample = sampleMaterialTexture(
+  baseSample = sampleMaterialTexture(
     baseColorTexture,
     baseColorSampler,
     baseUv,
     metadata.zw,
   );
+  }
+#endif
   if (alphaCutoff > 0.0 && baseColorAlpha * baseSample.a <= alphaCutoff) {
     discard;
   }

package/src/scene-temporal.wgsl

@@ -2,6 +2,8 @@
 
 // The sole shader interpretation of forgeax::scene-data::temporal-v1.
 // The packed target is rgba16float at render resolution and is sampled only.
+// Coverage uses the main (possibly jittered) raster/depth lattice. Motion UV
+// values themselves exclude jitter; an unjittered consumer offsets its read.
 
 const SCENE_DATA_TEMPORAL_V1_CLEAR : vec4<f32> = vec4<f32>(0.0, 0.0, -1.0, 1.0);
 

package/src/shadow-pcf.wgsl

@@ -142,9 +142,9 @@ 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 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).
+// `lightLocal` is the raw light-to-fragment direction vector in the cubemap's
+// coordinate system. evalPointShadowed and buildPointShadowMatrices share the
+// CubeCamera face directions and clip-space-X reflection convention.
 // `layer` is the cube_array layer index (i32; 0..3 for 4 shadow-casting
 // point lights; sentinel -1 must be gated upstream — this function assumes
 // a valid layer).
@@ -170,11 +170,9 @@ fn sample_shadow_cube_hw2x2(
   depthBias     : f32,
   nDotL         : f32,
 ) -> f32 {
-  // Slope-scaled bias: same formula as 2D path, shared SSOT. feat-20260621 M3 /
-  // m3-t5: param names aligned to D-1 (normalBias = slope coefficient,
-  // depthBias = floor). Pure rename -- each positional arg keeps its prior role.
-  let bias = max(normalBias * (1.0 - nDotL), depthBias / 1000.0);
-  let adjustedDepth = depthRef - bias;
+  // The public depthBias is a normalized depth floor, as for the directional
+  // receiver. Do not shrink it by 1000: that leaves front-lit faces uncovered.
+  let adjustedDepth = shadow_biased_receiver_depth(depthRef, normalBias, depthBias, nDotL);
 
   // Single textureSampleCompareLevel call: the comparison sampler resolves a
   // 2x2 PCF neighborhood at the silicon level; clamp-to-edge address mode

package/src/shadow-surface.wgsl

@@ -0,0 +1,16 @@
+#define_import_path forgeax_shadow::surface
+#import forgeax_view::common::{View, ShadowCasterCascade, view, shadowCasterCascade}
+
+// All geometry producers use the shadow owner's selected light view. Point
+// faces supply their face view through View; spots use the caster uniform.
+fn projectShadowPosition(worldPosition: vec4<f32>) -> vec4<f32> {
+  if (shadowCasterCascade.isSpot == 1u) {
+    return shadowCasterCascade.spotLightViewProj * worldPosition;
+  }
+  switch shadowCasterCascade.index {
+    case 0u: { return view.lightViewProj_A * worldPosition; }
+    case 1u: { return view.lightViewProj_B * worldPosition; }
+    case 2u: { return view.lightViewProj_C * worldPosition; }
+    default: { return view.lightViewProj_D * worldPosition; }
+  }
+}