@forgeax/engine-render 0.1.25 → 0.1.26

package/src/record/shadow-pass.ts

@@ -1,3 +1,4 @@
+import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
   type BindGroupEntry,
@@ -24,6 +25,11 @@ import {
   resolveGeometryInstanceBuffer,
   resolveGeometryInstancesBindGroup,
 } from './main-pass-geometry';
+import {
+  buildPerSubmeshMaterialBg,
+  type PerSubmeshMaterialBgDeps,
+  prepareMaterialSkylight,
+} from './main-pass-material';
 import {
   getOrCreateFromChain,
   MESH_PER_ENTITY_STRIDE,
@@ -31,7 +37,7 @@ import {
   MESH_UBO_FULL_ARRAY_BYTES,
 } from './mesh-ssbo';
 import type { _InternalRenderPipelineContext } from './render-context';
-import { STANDARD_PBR_UBO_SIZE } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
 import { POINTS_LINES_VIEW_BYTES, pointShadowViewOffset, VIEW_UNIFORM_BYTES } from './view-ubo';
 
 export const SHADOW_CASTER_SLOT_STRIDE = 256;
@@ -247,11 +253,10 @@ function ensureTypedShadowViewBg(
 }
 
 interface ShadowDispatch {
-  readonly materialHandle: number;
+  readonly vertexEntry: string | undefined;
+  readonly fragmentEntry: string | undefined;
   readonly materialShaderId: string;
   readonly renderState: MaterialRenderState | undefined;
-  readonly materialSlot: number | undefined;
-  readonly paramSnapshot: DispatchEntry['paramSnapshot'];
 }
 
 type ShadowDispatchMap = ReadonlyMap<number, ReadonlyMap<number, ShadowDispatch>>;
@@ -265,20 +270,14 @@ export function shadowShaderMap(c: _InternalRenderPipelineContext): ShadowDispat
         byMaterial = new Map<number, ShadowDispatch>();
         shaders.set(entry.renderableIndex, byMaterial);
       }
-      const candidateSlots =
-        c.materialSlotIndices[entry.renderableIndex] ?? c.materialSlotIndices.flat();
-      const materialSlot = candidateSlots.find(
-        (slot) => c.materialSlots[slot]?.materialHandle === entry.materialHandle,
-      );
       byMaterial.set(entry.materialHandle, {
-        materialHandle: entry.materialHandle,
+        vertexEntry: entry.vertexEntry,
+        fragmentEntry: entry.fragmentEntry,
         materialShaderId:
           entry.materialShaderId === 'forgeax::default-standard-pbr'
             ? SHADOW_CASTER_SHADER_ID
             : entry.materialShaderId,
         renderState: entry.renderState,
-        materialSlot,
-        paramSnapshot: entry.paramSnapshot,
       });
     }
   }
@@ -379,13 +378,15 @@ export function encodeDirectionalShadowPass(
     `view-shadow-directional-${cascadeIndex}`,
   );
   const materialBg = ensureSpotShadowMaterialBg(c);
-  if (pipeline === null || viewBg === null || materialBg === null) return;
-  c.frameState.directionalShadowCacheRecorded = true;
+  if (pipeline === null || viewBg === null || materialBg === null) {
+    c.frameState.directionalShadowCacheRecorded = false;
+    return;
+  }
   pass.setViewport(viewport.x, viewport.y, viewport.w, viewport.h, 0, 1);
   pass.setPipeline(pipeline);
   pass.setBindGroup(0, viewBg, [0, 0]);
   pass.setBindGroup(1, materialBg, [0]);
-  recordShadowCasterDraws(
+  const complete = recordShadowCasterDraws(
     c,
     pass,
     pipeline,
@@ -393,6 +394,8 @@ export function encodeDirectionalShadowPass(
     buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] }),
     shadowShaderMap(c),
   );
+  c.frameState.directionalShadowCacheRecorded =
+    cascadeIndex === 0 ? complete : c.frameState.directionalShadowCacheRecorded && complete;
 }
 
 export function encodePointShadowPass(
@@ -577,7 +580,7 @@ function recordShadowCasterDraws(
   shadowMeshBindGroup: BindGroup,
   matchedIndices: Set<number> | null,
   shadowDispatchByRenderableIdx: ShadowDispatchMap,
-): void {
+): boolean {
   const { runtime, pipelineState, validatedOrdered } = c;
   // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer
   // (the wrapper) -- the de-dup compare uses wrapper identity (one wrapper
@@ -591,6 +594,8 @@ function recordShadowCasterDraws(
   // bound by the setPipeline call above; the loop switches to a custom
   // ShadowCaster PSO when a material supplies one.
   let shadowLastPipeline: RenderPipeline = shadowPipeline;
+  let materialDeps: PerSubmeshMaterialBgDeps | undefined;
+  let complete = true;
 
   for (let i = 0; i < validatedOrdered.length; i++) {
     const entry = validatedOrdered[i];
@@ -601,7 +606,10 @@ function recordShadowCasterDraws(
 
     if (entry.source.skin !== undefined) {
       const skinPipeline = skinnedShadowPipeline(c, entry);
-      if (skinPipeline === null) continue;
+      if (skinPipeline === null) {
+        complete = false;
+        continue;
+      }
       if (skinPipeline !== shadowLastPipeline) {
         shadowPass.setPipeline(skinPipeline);
         shadowLastPipeline = skinPipeline;
@@ -686,21 +694,17 @@ function recordShadowCasterDraws(
         ?.get(submeshMaterial.materialHandle ?? 0);
       const entryShadowShaderId = shadowDispatch?.materialShaderId;
       const entryShadowRenderState = shadowDispatch?.renderState;
-      // A skinned caster's pipeline was selected above together with its
-      // two-binding mesh/palette group. Keep that pairing for every submesh;
-      // resetting to the static shadow pipeline here would bind the skin
-      // group against `pbr-pl` and Dawn rejects the draw at submit time.
-      let entryShadowPipeline =
+      // Canonical skin casters retain their palette layout. Authored casters
+      // select their own program below with the same geometry layout.
+      let entryShadowPipeline: RenderPipeline | null =
         entry.source.skin !== undefined ? shadowLastPipeline : shadowPipeline;
       if (
-        entry.source.skin === undefined &&
         entryShadowShaderId !== undefined &&
         (entryShadowShaderId !== 'forgeax::default-shadow-caster' ||
-          entryShadowRenderState !== undefined)
+          (entryShadowRenderState !== undefined && entry.source.skin === undefined))
       ) {
-        // On a cache miss (async build in flight / build failure), fall back
-        // to the default PSO so the caster still writes depth rather than
-        // dropping its draw.
+        // Pending or failed authored programs must not draw using a different
+        // caster. Retry preparation on the next frame with the same program.
         entryShadowPipeline =
           runtime.getMaterialShaderPipeline?.(
             entryShadowShaderId,
@@ -710,12 +714,65 @@ function recordShadowCasterDraws(
             undefined, // indexFormat
             undefined, // variantSet — shadow caster has no variant axes
             'shadow-caster', // passKind
-          ) ?? shadowPipeline;
+            undefined, // meshAttributes
+            1,
+            undefined, // colorFormatOverride
+            undefined, // shaderUvSetCount
+            undefined, // depthFormatOverride
+            undefined, // vertexLayout
+            entry.mesh.layoutProjection,
+            undefined, // shaderModuleMode
+            entry.source.skin === undefined ? 'pbr' : 'pbr-skin',
+            undefined, // additionalColorFormats
+            shadowDispatch?.vertexEntry,
+            shadowDispatch?.fragmentEntry,
+          ) ?? null;
+      }
+      if (entryShadowPipeline === null) {
+        complete = false;
+        continue;
       }
       if (entryShadowPipeline !== shadowLastPipeline && entryShadowPipeline !== null) {
         shadowPass.setPipeline(entryShadowPipeline);
         shadowLastPipeline = entryShadowPipeline;
       }
+      if (entryShadowShaderId !== undefined && entryShadowShaderId !== SHADOW_CASTER_SHADER_ID) {
+        materialDeps ??= {
+          runtime,
+          pipelineState,
+          world: c.world,
+          store: c.store,
+          materialSlice: STANDARD_PBR_UBO_SIZE,
+          videoHighPerfAvailable: probeVideoHighPerfUpload(runtime.device),
+          skylightResources: prepareMaterialSkylight(c).skylightResources,
+          resolveRenderTargetTextureSource: runtime.resolveRenderTargetTextureSource,
+          materialBgShared: c.frameState.materialBgShared,
+          materialBgAssemblyCache: c.materialBgAssemblyCache,
+          frameState: c.frameState,
+          bindGroupCounts: c.bindGroupCounts,
+        };
+        const materialSlot =
+          c.materialSlotIndices[i]?.[sm.materialSlot] ?? c.materialSlotIndices[i]?.[0];
+        if (materialSlot === undefined) {
+          throw new RhiError({
+            code: 'rhi-descriptor-invalid',
+            expected: 'a prepared material slot for each shadow submesh',
+            hint: 'repair material slot preparation before recording shadows',
+          });
+        }
+        const materialGroup = buildPerSubmeshMaterialBg(
+          materialDeps,
+          submeshMaterial,
+          entry.source.entityKey,
+          entry.world ?? c.world,
+          entryShadowShaderId,
+        );
+        shadowPass.setBindGroup(1, materialGroup, [materialSlot * MATERIAL_PER_ENTITY_STRIDE]);
+      } else {
+        const materialGroup = ensureSpotShadowMaterialBg(c);
+        if (materialGroup === null) continue;
+        shadowPass.setBindGroup(1, materialGroup, [0]);
+      }
       for (const instanceDraw of shadowInstanceDraws) {
         shadowPass.setBindGroup(3, instanceDraw.instanceBindGroup);
         if (entry.mesh.indexed) {
@@ -726,6 +783,7 @@ function recordShadowCasterDraws(
       }
     }
   }
+  return complete;
 }
 
 /**

package/src/recovery/render-system-candidate.ts

@@ -639,7 +639,11 @@ export function createRenderSystemRecovery(
           seed.frame.lights.pointShadow.length > 0 ||
           seed.frame.lights.spot.some((spot) => spot.castShadow === true) ||
           (seed.frame.lights.lightViewProj?.length ?? 0) > 0,
-        splitLdrSprite: computeSplitLdrSprite(candidateValidated, camera.tonemap !== 'none'),
+        splitLdrSprite: computeSplitLdrSprite(
+          candidateValidated,
+          camera.tonemap !== 'none',
+          seed.frame.dispatch,
+        ),
         reflectionFallbackAvailable: candidateFrameState.reflectionFallbackDemand === true,
       });
       const candidatePostProcessIds = new Set<string>([

package/src/render-system-extract-tail.ts

@@ -15,6 +15,7 @@ import {
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { box3, frustum, type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 import { RhiError } from '@forgeax/engine-rhi';
 import { GlobalTransform, MorphWeights, Transform } from '@forgeax/engine-scene';
 import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
@@ -148,6 +149,7 @@ import {
   materialColorParameterSchema,
   materialNormalScale,
   materialParametersToParamSchema,
+  materialProgramKeysForMaterial,
   materialTextureFields,
   materialTextureRef,
   pipelineRenderState,
@@ -174,6 +176,7 @@ export function extractFrames(
   pipelineState?: ExtractPipelineSurface | null,
   materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld,
   options: {
+    readonly materialContext?: MaterialCookProgramContext;
     readonly cull?: 'normal' | 'none';
     readonly renderables?: 'full' | 'none';
     readonly renderableEntitiesByWorld?: readonly (ReadonlySet<number> | undefined)[];
@@ -251,6 +254,9 @@ export function extractFrames(
                   return cache;
                 })(),
             }),
+        ...(options.materialContext === undefined
+          ? {}
+          : { materialContext: options.materialContext }),
         cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
         renderables: options.renderables ?? 'full',
         ...(options.renderableEntitiesByWorld?.[wi] === undefined
@@ -1559,6 +1565,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
+  const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
   // (`row.get(X) !== undefined` edge sniff) replaces the prior
@@ -1927,7 +1934,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             layerVal,
             materialSnap.paramSnapshot,
             0,
-            materialSnap.materialShaderId,
+            materialSnap.materialProgramKeys,
           );
         }
       } else if (handleRaw === 0 || assets === undefined || assets === null) {
@@ -1956,7 +1963,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               layerVal,
               materialSnap.paramSnapshot,
               0,
-              materialSnap.materialShaderId,
+              materialSnap.materialProgramKeys,
             );
           }
         } else {
@@ -2020,7 +2027,26 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             }
             const resolved = resolvedResult.value;
             const allPasses = resolved.passes;
-            const firstPassShader = runtimeMaterialShaderIdForMaterial(asset, allPasses, assets);
+            const materialContext =
+              context.materialContext === undefined
+                ? undefined
+                : {
+                    ...context.materialContext,
+                    geometry: hasSkin ? ('skinned' as const) : context.materialContext.geometry,
+                  };
+            const materialProgramKeys = materialProgramKeysForMaterial(
+              asset,
+              assets,
+              materialContext,
+            );
+            const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              undefined,
+            );
+            const firstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              materialProgramKeys,
+            );
             const pv = materialValuesToLinearRuntime(
               resolved.values,
               materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assets),
@@ -2049,7 +2075,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
 
             const materialParamSchema = materialParametersToParamSchema(
               resolved.parameters ?? [],
-              firstPassShader,
+              authoredFirstPassShader,
             );
             // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w17 (D-5):
             // bidirectional Skin <-> pbr-skin material fail-fast at extract.
@@ -2338,6 +2364,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               }),
               normalScale: normalScalePv,
               materialShaderId: firstPassShader,
+              materialProgramKeys,
               materialHandle: handleRaw,
               renderState: pipelineRenderState(allPasses[0]?.renderState),
               paramSnapshot: paramSnap,
@@ -2399,7 +2426,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 layerVal,
                 paramSnap,
                 0,
-                firstPassShader,
+                materialProgramKeys,
               );
             }
           }
@@ -2610,15 +2637,22 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         if (assets !== undefined && assets !== null) {
           for (let mi = 1; mi < materialHandles.length; mi++) {
             const subHandle = materialHandles[mi] ?? 0;
-            const cachedSubmaterial = materialSnapshotCache.get(subHandle);
+            const subCache = hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache;
+            const cachedSubmaterial = subCache.get(subHandle);
             materialsArr.push(
               cachedSubmaterial?.snapshot ??
                 resolveMaterialSnapshot(
                   subHandle,
                   world,
                   assets,
-                  materialSnapshotCache,
-                  persistentMaterialSnapshotCache,
+                  subCache,
+                  hasSkin ? undefined : persistentMaterialSnapshotCache,
+                  context.materialContext === undefined
+                    ? undefined
+                    : {
+                        ...context.materialContext,
+                        geometry: hasSkin ? 'skinned' : context.materialContext.geometry,
+                      },
                 ),
             );
           }
@@ -2628,8 +2662,14 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             const subHandle = materialHandles[mi] ?? 0;
             if (subHandle === handleRaw) continue;
             const subEntry =
-              materialSnapshotCache.get(subHandle) ??
-              readPersistentMaterialSnapshot(persistentMaterialSnapshotCache, subHandle, assets);
+              (hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache).get(subHandle) ??
+              (hasSkin
+                ? undefined
+                : readPersistentMaterialSnapshot(
+                    persistentMaterialSnapshotCache,
+                    subHandle,
+                    assets,
+                  ));
             appendMaterialDispatchEntries(
               pendingDispatch,
               subEntry?.passes ?? (subHandle === 0 ? [DEFAULT_FORWARD_PASS] : []),
@@ -2639,7 +2679,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               layerVal,
               materialsArr[mi]?.paramSnapshot,
               0,
-              materialsArr[mi]?.materialShaderId,
+              materialsArr[mi]?.materialProgramKeys,
             );
           }
         }

package/src/render-system-extract.ts

@@ -1,3 +1,4 @@
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 // @forgeax/engine-runtime - RenderSystem Extract stage (D-S2 + plan-strategy R-15
 // fallback split). Pure ECS query phase: walks Camera / DirectionalLight /
 // the merged-MeshRenderer renderable archetype and produces SoA-free snapshot
@@ -81,7 +82,9 @@
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
+  materialParametersToParamSchema as projectMaterialParametersToParamSchema,
   resolveAssetHandle,
+  selectMaterialPassProgram,
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
 import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
@@ -909,6 +912,7 @@ export interface MaterialSnapshot {
    * discriminator (M4-T06).
    */
   readonly materialShaderId?: string | undefined;
+  readonly materialProgramKeys?: Readonly<Record<string, string>> | undefined;
   /**
    * Stable source handle for the material asset. Record uses this only for
    * same-frame assembly reuse; GPU bind-group validity still comes from the
@@ -1015,12 +1019,9 @@ export interface MaterialSnapshot {
    * from the legacy `shadingModel` discriminant (feat-20260625 M2 D-3,
    * finalised in w15; `shadingModel` field removed in tweak-20260701 M1).
    *
-   * Extract derives this from the first pass's `renderState.blend !==
-   * undefined` (post-feat-20260626-collapse: blend presence is the
-   * single SSOT for "this material is transparent on the geometry
-   * pipeline cache key"). Multi-pass materials whose mix of opaque +
-   * transparent passes need finer routing should split into separate
-   * MaterialAsset entries (the normal forgeax pattern).
+   * This describes the primary-pass snapshot for consumers that need a
+   * material summary. Actual draw routing and the LDR split read the selected
+   * DispatchEntry.renderState, so mixed opaque/transparent Passes remain valid.
    *
    * Type is `boolean | undefined` (derived): `undefined` means "no
    * passes / unknown"; consumers must read `=== true` / `!== true` to
@@ -1125,7 +1126,7 @@ export function appendMaterialDispatchEntries(
   layer: number,
   paramSnapshot: Readonly<Record<string, number | number[] | string>> | undefined,
   passIndexOffset = 0,
-  materialShaderIdOverride?: string,
+  materialProgramKeys?: Readonly<Record<string, string>>,
 ): void {
   const matchedPasses = selectPasses(passes, {});
   for (let pIdx = 0; pIdx < matchedPasses.length; pIdx++) {
@@ -1138,9 +1139,9 @@ export function appendMaterialDispatchEntries(
     };
     const authoredShaderId = runtimeMaterialShaderId(pass.program.module, pass.name);
     const dispatchShaderId =
-      authoredShaderId === 'forgeax::default-shadow-caster'
-        ? authoredShaderId
-        : (materialShaderIdOverride ?? authoredShaderId);
+      materialProgramKeys === undefined ? authoredShaderId : materialProgramKeys[pass.name];
+    if (materialProgramKeys !== undefined && dispatchShaderId === undefined)
+      throw new Error(`Missing published material program for Pass ${pass.name}`);
     pendingDispatch.push({
       entityIndex: entity,
       materialHandle,
@@ -1155,13 +1156,6 @@ export function appendMaterialDispatchEntries(
       defines: undefined,
       vertexEntry: pass.program.vertexEntry,
       fragmentEntry: pass.program.fragmentEntry,
-      // A cooked Standard publication supplies one specialization key for its
-      // forward/deferred artifact, but its ShadowCaster pass still owns the
-      // engine depth-only shader. Keep the pass-local canonical identity so a
-      // specialized Standard source (which only declares fs_main/fs_gbuffer)
-      // is never asked to build an fs_shadow pipeline. Authored non-Standard
-      // ShadowCaster modules retain the publication override and continue to
-      // use their producer-owned source.
       materialShaderId: dispatchShaderId,
       paramSnapshot,
       ...(passState.stencilReference !== undefined && {
@@ -1419,13 +1413,50 @@ export function runtimeMaterialShaderId(
  * owns the composed material artifact identity; the authored pass module is
  * the built-in fallback used before that publication is ready.
  */
-export function runtimeMaterialShaderIdForMaterial(
+export function materialProgramKeysForMaterial(
   material: MaterialAsset,
-  passes: readonly MaterialPass[],
   assets: AssetRegistry,
+  context: MaterialCookProgramContext | undefined,
+): Readonly<Record<string, string>> | undefined {
+  const projection = assets.getMaterialProjectionForPayload(material);
+  if (projection === undefined) return undefined;
+  if (context === undefined)
+    throw new Error('Published material selection requires renderer-owned compiler context');
+  return Object.fromEntries(
+    projection.passes.map((pass) => {
+      const mode = String(
+        (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+      );
+      const selectedContext: MaterialCookProgramContext = {
+        ...context,
+        pass: /shadow/i.test(mode) ? 'shadow' : /depth/i.test(mode) ? 'depth' : 'forward',
+        pipeline: /deferred|gbuffer/i.test(mode) ? 'deferred' : context.pipeline,
+      };
+      return [
+        pass.name,
+        selectMaterialPassProgram(projection, pass.name, selectedContext).specializationKey,
+      ];
+    }),
+  );
+}
+
+export function runtimeMaterialShaderIdForMaterial(
+  passes: readonly MaterialPass[],
+  programs: Readonly<Record<string, string>> | undefined,
 ): string | undefined {
-  const authored = runtimeMaterialShaderId(passes[0]?.program.module, passes[0]?.name);
-  return assets.getMaterialProjectionForPayload(material)?.specializationKey ?? authored;
+  const pass =
+    passes.find(
+      (pass) =>
+        !/shadow|depth/i.test(
+          String(
+            (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ?? pass.name,
+          ),
+        ),
+    ) ?? passes[0];
+  if (pass === undefined) return undefined;
+  return programs === undefined
+    ? runtimeMaterialShaderId(pass.program.module, pass.name)
+    : programs[pass.name];
 }
 
 export function pipelineRenderState(
@@ -1732,49 +1763,21 @@ export function isEngineInjectedTextureField(
   return isStandardPbrMaterialShader(shaderId) && ENGINE_INJECTED_TEXTURE_FIELDS.has(fieldName);
 }
 
+/**
+ * Project one material's authoring parameters into the runtime ABI.
+ *
+ * Engine-owned Standard roots are compiled against the canonical superset
+ * schema even when the authoring asset omits optional physical fields. A
+ * compact authored schema would move later UBO members (for example `ior`)
+ * into the wrong slots. Custom material roots keep their own published
+ * parameter projection.
+ */
 export function materialParametersToParamSchema(
   parameters: readonly MaterialParameter[],
-  shaderId: string | undefined,
+  shaderId?: string,
 ): readonly ParamSchemaEntry[] {
-  // Engine-owned Standard modules are compiled once against the canonical
-  // boot schema. Materials.standard() exposes a smaller authoring projection,
-  // but using that compact projection as the runtime UBO schema would shift
-  // every field after an omitted physical entry.
-  if (isCanonicalStandardPbrMaterialShader(shaderId)) {
-    return STANDARD_PIPELINE_PARAM_SCHEMA;
-  }
-  const engineInjectedTextureFields = isStandardPbrMaterialShader(shaderId)
-    ? ENGINE_INJECTED_TEXTURE_FIELDS
-    : undefined;
-  return parameters.flatMap((parameter): ParamSchemaEntry[] => {
-    // Boolean material values are runtime-only and have no UBO representation.
-    if (parameter.type === 'bool') return [];
-    if (parameter.type === 'texture' || parameter.type === 'texture_cube') {
-      if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
-      return [
-        {
-          name: parameter.name,
-          type: parameter.type === 'texture_cube' ? 'texture_cube' : 'texture2d',
-          default: parameter.default,
-        },
-      ];
-    }
-    const numericDefault =
-      typeof parameter.default === 'number'
-        ? parameter.default
-        : Array.isArray(parameter.default) &&
-            parameter.default.every((entry) => typeof entry === 'number')
-          ? parameter.default
-          : undefined;
-    const numericEntry = {
-      name: parameter.name,
-      type: parameter.type,
-      ...(parameter.colorSpace === undefined ? {} : { colorSpace: parameter.colorSpace }),
-    };
-    return numericDefault === undefined
-      ? [numericEntry]
-      : [{ ...numericEntry, default: numericDefault }];
-  });
+  if (isCanonicalStandardPbrMaterialShader(shaderId)) return STANDARD_PIPELINE_PARAM_SCHEMA;
+  return projectMaterialParametersToParamSchema(parameters);
 }
 
 /**
@@ -1921,6 +1924,7 @@ export function resolveMaterialSnapshot(
   assetsRef: AssetRegistry,
   materialSnapshotCache?: MaterialSnapshotCache,
   persistentMaterialSnapshotCache?: MaterialSnapshotCache,
+  materialContext?: MaterialCookProgramContext,
 ): MaterialSnapshot {
   if (handleRaw === 0) return defaultMaterialSnapshot(handleRaw);
   const cached = materialSnapshotCache?.get(handleRaw);
@@ -1952,7 +1956,9 @@ export function resolveMaterialSnapshot(
   if (!resolvedResult.ok) return defaultMaterialSnapshot(handleRaw);
   const resolved = resolvedResult.value;
   const allPasses = resolved.passes;
-  const firstPassShader = runtimeMaterialShaderIdForMaterial(asset, allPasses, assetsRef);
+  const materialProgramKeys = materialProgramKeysForMaterial(asset, assetsRef, materialContext);
+  const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, undefined);
+  const firstPassShader = runtimeMaterialShaderIdForMaterial(allPasses, materialProgramKeys);
   const pv = materialValuesToLinearRuntime(
     resolved.values,
     materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assetsRef),
@@ -1979,7 +1985,7 @@ export function resolveMaterialSnapshot(
   }
   const materialParamSchema = materialParametersToParamSchema(
     resolved.parameters ?? [],
-    firstPassShader,
+    authoredFirstPassShader,
   );
   // feat-20260614 M8 (D-19): texture / sampler values are embedded GUIDs
   // (dash-form strings) after loadByGuid. Resolve each to a user-tier column
@@ -2047,6 +2053,7 @@ export function resolveMaterialSnapshot(
     }),
     normalScale: normalScalePv,
     materialShaderId: firstPassShader,
+    materialProgramKeys,
     materialHandle: handleRaw,
     renderState: pipelineRenderState(allPasses[0]?.renderState),
     paramSnapshot: paramSnap,
@@ -2548,6 +2555,7 @@ export interface ExtractFramesOwner {
 }
 
 export interface PreparedExtractContext {
+  readonly materialContext?: MaterialCookProgramContext | undefined;
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
@@ -2748,6 +2756,7 @@ export function tonemapParams(camera: CameraSnapshot): Uint8Array {
 export function prepareExtractContext(
   world: World,
   options: {
+    readonly materialContext?: MaterialCookProgramContext;
     readonly assets?: AssetRegistry | null;
     readonly pipelineState?: ExtractPipelineSurface | null;
     readonly materialSnapshotCache?: MaterialSnapshotCache;
@@ -2765,6 +2774,7 @@ export function prepareExtractContext(
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
   return {
+    materialContext: options.materialContext,
     assets: options.assets,
     pipelineState: options.pipelineState,
     materialSnapshotCache: options.materialSnapshotCache,

package/src/render-system.ts

@@ -2586,6 +2586,25 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
                 internals.getPipelineState(),
                 persistentRenderScene.materialSnapshotCacheStore(),
                 {
+                  ...(internals.device.caps.backendKind === 'null'
+                    ? {}
+                    : {
+                        materialContext: {
+                          backend:
+                            internals.device.caps.backendKind === 'wgpu-webgl2'
+                              ? ('webgl2' as const)
+                              : internals.device.caps.backendKind,
+                          capability: internals.device.caps.storageBuffer
+                            ? ('storage-buffer' as const)
+                            : ('uniform-fallback' as const),
+                          pipeline: 'forward' as const,
+                          geometry: 'mesh' as const,
+                          pass: 'forward' as const,
+                          profile: 'forgeax-material-wgsl-v1' as const,
+                          toolchain: 'naga-oil' as const,
+                          instrumentation: 'none' as const,
+                        },
+                      }),
                   cull: 'none',
                   renderables: request === 'none' ? 'none' : 'full',
                   ...(request === 'none' || request === 'full'