@forgeax/engine-render 0.1.20 → 0.1.23

package/src/record/main-pass-geometry.ts

@@ -17,19 +17,36 @@ import {
   GPU_BUFFER_USAGE_STORAGE,
   GPU_BUFFER_USAGE_UNIFORM,
 } from '../gpu-usage';
+import { createHdrpSkinUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
-import { SKIN_MATERIAL_SHADER_ID } from '../pbr-pipeline';
-import { renderStateHash, variantSetFromVertexLayoutProjection } from '../pipeline-spec';
+import {
+  createPbrSkinMeshBindGroupEntries,
+  isStandardPbrMaterialShader,
+  pbrSkinMeshDynamicOffsets,
+  SKIN_MATERIAL_SHADER_ID,
+} from '../pbr-pipeline';
+import {
+  renderStateHash,
+  standardStorageVariantSet,
+  standardTopologyVariantSet,
+  variantSetFromVertexLayoutProjection,
+} from '../pipeline-spec';
 import type { PointsLinesRecordPlan } from '../points-lines/record';
 import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
+import {
+  PROBE_BLEND_RECORD_BYTE_SIZE,
+  PROBE_BLEND_RECORD_STRIDE,
+  probeBlendRecordOffset,
+} from '../scene/probe-blend-record';
 import { worldEntityKey } from './frame-snapshot';
 import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
   selectGeometryPipeline,
+  selectMaterialGroup2,
 } from './main-pass-material';
 import {
   getOrCreateFromChain,
@@ -40,19 +57,22 @@ import {
   MESH_UBO_FULL_ARRAY_BYTES,
   packInstanceStorageBuffer,
 } from './mesh-ssbo';
-import type { _InternalRenderPipelineContext } from './render-context';
+import type { _InternalRenderPipelineContext, MaterialShaderPipelineEntry } from './render-context';
 import { MATERIAL_PER_ENTITY_STRIDE } from './render-context';
 import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-ubo';
 
 type GeometryInstanceDraw = {
   readonly instanceBuffer: Buffer;
   readonly instanceBindGroup: BindGroup;
+  /** -1 means the no-probe layout and therefore no dynamic offset. */
+  readonly probeOffset: number;
   readonly instanceCount: number;
 };
 
 type GeometryBindingState = {
   pipeline: RenderPipeline | null;
   instancesBuffer: Buffer | null;
+  probeOffset: number;
 };
 
 type MaterialPipelineLookup = {
@@ -66,7 +86,8 @@ type MaterialPipelineLookup = {
   readonly layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection;
   readonly sampleCount: number;
   readonly colorFormatOverride: GPUTextureFormat | undefined;
-  readonly handle: RenderPipeline | null;
+  readonly additionalColorFormats: readonly GPUTextureFormat[] | undefined;
+  readonly handle: MaterialShaderPipelineEntry | null;
 };
 
 type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection' | 'draw-submit';
@@ -127,9 +148,17 @@ function submitSubmeshDraws(
     state.pipeline = pipeline;
   }
   for (const instanceDraw of instanceDraws) {
-    if (instanceDraw.instanceBuffer !== state.instancesBuffer) {
-      pass.setBindGroup(3, instanceDraw.instanceBindGroup);
+    if (
+      instanceDraw.instanceBuffer !== state.instancesBuffer ||
+      instanceDraw.probeOffset !== state.probeOffset
+    ) {
+      if (instanceDraw.probeOffset < 0) {
+        pass.setBindGroup(3, instanceDraw.instanceBindGroup);
+      } else {
+        pass.setBindGroup(3, instanceDraw.instanceBindGroup, [instanceDraw.probeOffset]);
+      }
       state.instancesBuffer = instanceDraw.instanceBuffer;
+      state.probeOffset = instanceDraw.probeOffset;
     }
     if (indexed) {
       pass.drawIndexed(indexCount, instanceDraw.instanceCount, indexOffset, 0, 0);
@@ -197,8 +226,13 @@ export function recordGeometryDraws(
     validatedOrdered,
     splitLdrSprite,
     viewBindGroup,
+    viewBindGroupDynamicOffset = 0,
   } = c;
   const colorFormatOverride = c.transparentColorFormat as GPUTextureFormat | undefined;
+  // The prepared Standard topology is the frame authority. A bind-group
+  // identity is only a resource result; using it to infer the shader lane
+  // would silently fall back to URP when the clustered resource is missing.
+  const clusteredLighting = c.standardLighting?.kind === 'clustered';
   // A no-tone frame may still render into the graph-owned rgba16float target
   // (the linear-LDR route). Shader variants must follow the attachment's
   // numeric domain rather than the camera's tone-map switch, otherwise the
@@ -210,19 +244,20 @@ export function recordGeometryDraws(
   const bindingState: GeometryBindingState = {
     pipeline: null,
     instancesBuffer: null,
+    probeOffset: -1,
   };
   const identityInstanceBuffer = pipelineState.identityInstanceBuffer;
   const identityInstanceDraws: readonly GeometryInstanceDraw[] = [
     {
       instanceBuffer: identityInstanceBuffer,
-      instanceBindGroup: resolveGeometryInstancesBindGroup(c, identityInstanceBuffer),
+      instanceBindGroup: resolveGeometryInstancesBindGroup(c, identityInstanceBuffer, undefined),
+      probeOffset: -1,
       instanceCount: 1,
     },
   ];
   const profilePhase = c.profilePhase;
   const materialGroup1DynamicOffsets = new Uint32Array(1);
   const meshGroup2DynamicOffsets = [0];
-  const skinGroup2DynamicOffsets = [0, 0];
   let lastStencilReference: number | null = null;
   // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w14 (D-7):
   // sprite PSO selection no longer maintains a dedicated tag — the
@@ -238,6 +273,9 @@ export function recordGeometryDraws(
   // renderer's authoritative cache still owns lifetime/invalidation, while
   // this frame-local table removes the hot call/lookup overhead.
   const materialPipelineLookupCache = new Map<string, Map<string, MaterialPipelineLookup[]>>();
+  const recordOcclusionCandidate = (draw: () => void): void => {
+    draw();
+  };
   const resolveMaterialPipeline = (
     materialShaderId: string,
     renderState: MaterialSnapshot['renderState'],
@@ -246,7 +284,20 @@ export function recordGeometryDraws(
     variantSet: string | undefined,
     colorFormat: GPUTextureFormat | undefined,
     layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection,
-  ): RenderPipeline | null => {
+  ): MaterialShaderPipelineEntry | null => {
+    // The fallback MRT is an extension of the built-in Standard PBR output
+    // contract only.  The render pass may carry a second attachment whenever
+    // another renderable needs S_fallback, but shaders such as unlit, sprite,
+    // and the skin PBR variant still expose only @location(0).  Passing that
+    // attachment into their PSO would make WebGPU reject the pipeline before
+    // the first draw ("Color target has no corresponding fragment stage
+    // output").  Keep the graph attachment shared while deriving pipeline
+    // targets from the shader's actual output contract.
+    const reflectionFallbackFormats =
+      materialShaderId === 'forgeax::default-standard-pbr' &&
+      c.reflectionFallbackColorFormat !== undefined
+        ? [c.reflectionFallbackColorFormat]
+        : undefined;
     const renderStateKey = renderStateHash(renderState);
     const shaderLookupCache = materialPipelineLookupCache.get(materialShaderId);
     const cachedLookups = shaderLookupCache?.get(renderStateKey);
@@ -261,7 +312,8 @@ export function recordGeometryDraws(
           cached.passKind === passKind &&
           cached.layoutProjection.digest === layoutProjection.digest &&
           cached.sampleCount === sampleCount &&
-          cached.colorFormatOverride === colorFormat
+          cached.colorFormatOverride === colorFormat &&
+          cached.additionalColorFormats?.join(',') === reflectionFallbackFormats?.join(',')
         ) {
           return cached.handle;
         }
@@ -277,14 +329,20 @@ export function recordGeometryDraws(
       return null;
     }
     const resolvedVariantSet = resolvedVariantSetResult.value;
+    const fallbackVariantSet =
+      materialShaderId !== 'forgeax::default-standard-pbr'
+        ? resolvedVariantSet
+        : c.reflectionFallbackColorFormat !== undefined && resolvedVariantSet === ''
+          ? ''
+          : `${resolvedVariantSet === undefined || resolvedVariantSet === '' ? '' : `${resolvedVariantSet}+`}REFLECTION_FALLBACK_AVAILABLE=${c.reflectionFallbackColorFormat !== undefined}`;
     const resolvePipeline = () =>
-      runtime.getMaterialShaderPipeline?.(
+      runtime.getMaterialShaderPipelineEntry?.(
         materialShaderId,
         isHdrTarget,
         renderState,
         topology,
         indexFormat,
-        resolvedVariantSet,
+        fallbackVariantSet,
         passKind,
         undefined,
         sampleCount,
@@ -293,6 +351,9 @@ export function recordGeometryDraws(
         undefined,
         undefined,
         layoutProjection,
+        undefined,
+        undefined,
+        reflectionFallbackFormats,
       ) ?? null;
     const handle =
       profilePhase === undefined
@@ -317,6 +378,7 @@ export function recordGeometryDraws(
         layoutProjection,
         sampleCount,
         colorFormatOverride: colorFormat,
+        additionalColorFormats: reflectionFallbackFormats,
         handle,
       };
       if (shaderLookupCache === undefined) {
@@ -340,13 +402,18 @@ export function recordGeometryDraws(
     // Points/Lines share the Standard geometry pass. Their retained source
     // is prepared once by the renderer owner, while this loop remains the
     // sole pass/draw submission owner and preserves the authored topology.
-    const pointsLinesSubmission = c.pointsLines?.prepare(entry, frameState.isHdrpActive);
+    const pointsLinesSubmission = c.pointsLines?.prepare(entry, clusteredLighting);
     if (entry.source.pointsLines !== undefined && pointsLinesSubmission?.plan.drawCount !== 1)
       continue;
 
     if (
       passKind === 'forward' &&
-      c.gpuDrivenEntityKeys.has(worldEntityKey(entry.source.worldId, entry.source.entityKey))
+      c.gpuDrivenEntityKeys.has(
+        worldEntityKey(
+          c.gpuDrivenWorldKeys?.[entry.source.worldId] ?? entry.source.worldId,
+          entry.source.entityKey,
+        ),
+      )
     ) {
       continue;
     }
@@ -399,7 +466,7 @@ export function recordGeometryDraws(
         entry.source.entityKey,
         entry.world ?? c.world,
       );
-      const pointsLinesPipeline = resolveMaterialPipeline(
+      const pointsLinesPipelineEntry = resolveMaterialPipeline(
         POINTS_LINES_MATERIAL_SHADER_ID,
         {
           ...pointsLinesMaterial.renderState,
@@ -411,7 +478,8 @@ export function recordGeometryDraws(
         colorFormatOverride,
         pointsLinesSubmission.layoutProjection,
       );
-      if (pointsLinesPipeline === null) continue;
+      if (pointsLinesPipelineEntry === null) continue;
+      const pointsLinesPipeline = pointsLinesPipelineEntry.pipeline;
       if (pipelineState.pointsLinesViewBuffer === undefined) continue;
       writePointsLinesViewUbo(
         runtime.device.queue,
@@ -426,9 +494,9 @@ export function recordGeometryDraws(
       pass.setBindGroup(
         0,
         viewBindGroup as BindGroup,
-        new Uint32Array([i * POINTS_LINES_VIEW_SLOT_STRIDE]),
+        new Uint32Array([0, i * POINTS_LINES_VIEW_SLOT_STRIDE]),
         0,
-        1,
+        2,
       );
       pass.setPipeline(pointsLinesPipeline);
       pass.setVertexBuffer(0, pointsLinesSubmission.vertexBuffer);
@@ -438,13 +506,12 @@ export function recordGeometryDraws(
       const pointsLinesMeshGroup = meshBindGroup ?? meshGroup2;
       if (pointsLinesMeshGroup === null) continue;
       pass.setBindGroup(2, pointsLinesMeshGroup, meshGroup2DynamicOffsets);
-      pass.setBindGroup(
-        3,
+      const pointsLinesInstancesBg =
         identityInstanceDraws[0]?.instanceBindGroup ??
-          resolveGeometryInstancesBindGroup(c, identityInstanceBuffer),
-      );
-      recordPointsLinesDraw(pass, pointsLinesSubmission.plan);
-      pass.setBindGroup(0, viewBindGroup as BindGroup, [0]);
+        resolveGeometryInstancesBindGroup(c, identityInstanceBuffer, undefined);
+      pass.setBindGroup(3, pointsLinesInstancesBg);
+      recordOcclusionCandidate(() => recordPointsLinesDraw(pass, pointsLinesSubmission.plan));
+      pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
       continue;
     }
 
@@ -471,14 +538,15 @@ export function recordGeometryDraws(
     // length instead.
     if (pipelineTag === 'unlit') dispatchCounts.unlit += 1;
 
-    const instanceDraws = resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws);
+    const instanceDraws = resolveGeometryInstanceBuffer(c, entry, identityInstanceDraws, false);
     if (instanceDraws === null) continue;
 
-    // feat-20260611 R2 / M8 / w28 (IS-14): skin entries need a 2-binding
+    // feat-20260611 R2 / M8 / w28 (IS-14): skin entries need a 3-binding
     // group(2) BG matching `pbr-skin-pl` (binding 0 mesh-array UBO +
-    // binding 1 palette UBO). Building this here -- not in the
+    // binding 1 current palette UBO + binding 2 previous palette UBO).
+    // Building this here -- not in the
     // `meshBindGroup` factory above -- because the binding-shape
-    // (1-entry vs 2-entry) is per-entry, not per-frame. URP / HDRP
+    // (1-entry vs 3-entry) is per-entry, not per-frame. URP / HDRP
     // entries keep using `meshGroup2` (1-entry mesh-array or HDRP
     // unified). The skin-variant cache key includes both buffer
     // identities so a future allocator-driven palette buffer rotation
@@ -489,7 +557,7 @@ export function recordGeometryDraws(
     // BGL-build failure), AND (b) the skin PSO cache returns a non-null
     // pipeline for this entry. Without (b), the per-submesh selector
     // below falls back to URP `standardPipeline` (`pbr-pl` layout,
-    // 1-entry mesh-array BGL); binding the 2-entry skin BG against
+    // 1-entry mesh-array BGL); binding the 3-entry skin BG against
     // that pipeline reproduces the exact `pbr-mesh-array-bgl ... does
     // not match layout pbr-skin-mesh-array-bgl` device error R1
     // captured. Mirrors the uniform null skip-draw pattern (M6-T1).
@@ -501,6 +569,8 @@ export function recordGeometryDraws(
     meshGroup2DynamicOffsets[0] = i * MESH_PER_ENTITY_STRIDE;
     let group2DynamicOffsets: readonly number[] = meshGroup2DynamicOffsets;
     const isSkinEntry = entry.source.skin !== undefined;
+    const probeBlendRecordAvailable =
+      runtime.device.caps.storageBuffer && entry.source.probeBlendRecord !== undefined;
     // feat-20260612-skin-palette-per-frame-upload M1 / m1-3 + M6: the
     // record stage reads the GPU buffer reference through
     // `entry.source.skin.buffer` (per-slice carrier set at extract time
@@ -517,28 +587,41 @@ export function recordGeometryDraws(
     // and walks 0, 1536, 3072, ... on the storage path.
     const skinAllocator = pipelineState.skinPaletteAllocator;
     const skinSlice = entry.source.skin;
+    const clusteredSkin = clusteredLighting;
+    const skinMeshBindGroupLayout = clusteredSkin
+      ? pipelineState.hdrpSkinMeshBindGroupLayout
+      : pipelineState.pbrSkinMeshBindGroupLayout;
+    const hdrpSkinBuffers =
+      isSkinEntry && clusteredSkin
+        ? getOrCreateHdrpBuffers(runtime, frameState.installedPipelineConfig?.clusterGrid)
+        : null;
     const skinResources =
       isSkinEntry &&
-      pipelineState.pbrSkinMeshBindGroupLayout !== null &&
+      skinMeshBindGroupLayout !== null &&
       skinAllocator !== null &&
-      skinSlice !== undefined
+      skinSlice !== undefined &&
+      (!clusteredSkin || hdrpSkinBuffers !== null)
         ? {
-            meshArrayBgl: pipelineState.pbrSkinMeshBindGroupLayout,
+            meshArrayBgl: skinMeshBindGroupLayout,
             paletteBuffer: skinSlice.buffer,
             paletteBindingWindowBytes: skinAllocator.bindingWindowBytes,
+            hdrpBuffers: hdrpSkinBuffers,
           }
         : null;
     // Probe the skin PSO cache up front so we can decide whether to swap
-    // to the 2-binding skin BG. The same probe + selector is repeated in
+    // to the skin BG. The same probe + selector is repeated in
     // the per-submesh loop below (the loop's variantSet derivation is
     // identical -- skin shader registers a single all-true variant so
     // the canonical empty-key rule applies on HDRP and the URP key is
     // the explicit expanded form, mirroring the standard PBR path).
     const skinVariantSetResult = variantSetFromVertexLayoutProjection(
       entry.mesh.layoutProjection,
-      frameState.isHdrpActive
-        ? ''
-        : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true',
+      standardTopologyVariantSet(
+        c.standardLighting,
+        runtime.device.caps.storageBuffer,
+        entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
+        probeBlendRecordAvailable,
+      ),
     );
     if (!skinVariantSetResult.ok) runtime.errorRegistry.fire(skinVariantSetResult.error);
     const skinVariantSet = skinVariantSetResult.ok ? skinVariantSetResult.value : undefined;
@@ -559,6 +642,9 @@ export function recordGeometryDraws(
             undefined,
             undefined,
             entry.mesh.layoutProjection,
+            undefined,
+            undefined,
+            undefined,
           ) ?? null)
         : null;
     if (skinResources !== null && skinPsoProbe !== null) {
@@ -579,45 +665,47 @@ export function recordGeometryDraws(
       const skinMissesBefore = bindGroupCounts.createBindGroup;
       const skinBindGroup: BindGroup = getOrCreateFromChain(
         frameState.meshBindGroupCache,
-        [pipelineState.meshStorageBuffer.buffer, skinResources.paletteBuffer],
+        [
+          pipelineState.meshStorageBuffer.buffer,
+          skinResources.paletteBuffer,
+          ...(skinResources.hdrpBuffers === null
+            ? []
+            : [
+                skinResources.hdrpBuffers.lightDataBuffer,
+                skinResources.hdrpBuffers.clusterGridBuffer,
+                skinResources.hdrpBuffers.lightIndexListBuffer,
+                skinResources.hdrpBuffers.clusterUniformBuffer,
+              ]),
+        ],
         'pbr-skin-mesh',
         () => {
+          if (skinResources.hdrpBuffers !== null) {
+            const result = createHdrpSkinUnifiedBindGroup(
+              runtime,
+              skinResources.hdrpBuffers,
+              skinResources.meshArrayBgl,
+              pipelineState.meshStorageBuffer.buffer,
+              skinResources.paletteBuffer,
+              skinResources.paletteBindingWindowBytes,
+            );
+            if (result === null) {
+              throw new RhiError({
+                code: 'webgpu-runtime-error',
+                expected: 'HDRP clustered skin BindGroup creation succeeds',
+                hint: 'inspect prior errorRegistry events for createBindGroup failure detail',
+              });
+            }
+            return result;
+          }
           const result = runtime.device.createBindGroup({
             label: 'pbr-skin-mesh-bg',
             layout: skinResources.meshArrayBgl,
-            entries: [
-              {
-                binding: 0,
-                resource: {
-                  kind: 'buffer',
-                  value: {
-                    buffer: pipelineState.meshStorageBuffer.buffer,
-                    offset: 0,
-                    size: meshBindSize,
-                  },
-                },
-              },
-              {
-                binding: 1,
-                resource: {
-                  kind: 'buffer',
-                  value: {
-                    buffer: skinResources.paletteBuffer,
-                    offset: 0,
-                    // M6 SSOT: static BG entry size (= MAX_JOINTS * 64 =
-                    // 16320 B) sourced from the allocator. The per-draw
-                    // window slides via `group2DynamicOffsets[1]`
-                    // (= entry.source.skin.byteOffset) so this size
-                    // stays at the worst case across all skin entries
-                    // -- one BG covers every skinned draw in the frame
-                    // (m3-1b miss=1 + hit=N-1 contract). The allocator
-                    // guarantees `buffer.size >= byteOffset + this size`
-                    // so dynOffset[1] passes WebGPU validation.
-                    size: skinResources.paletteBindingWindowBytes,
-                  },
-                },
-              },
-            ],
+            entries: createPbrSkinMeshBindGroupEntries(
+              pipelineState.meshStorageBuffer.buffer,
+              meshBindSize,
+              skinResources.paletteBuffer,
+              skinResources.paletteBindingWindowBytes,
+            ),
           });
           if (!result.ok) throw result.error;
           return result.value;
@@ -634,9 +722,10 @@ export function recordGeometryDraws(
       // Replaces the prior PR #353 hard-coded `0` second slot -- every
       // skin entry now points the palette window at its own slice while
       // sharing the worst-case BG entry size above.
-      skinGroup2DynamicOffsets[0] = i * MESH_PER_ENTITY_STRIDE;
-      skinGroup2DynamicOffsets[1] = entry.source.skin?.byteOffset ?? 0;
-      group2DynamicOffsets = skinGroup2DynamicOffsets;
+      group2DynamicOffsets = pbrSkinMeshDynamicOffsets(
+        i * MESH_PER_ENTITY_STRIDE,
+        entry.source.skin?.byteOffset ?? 0,
+      );
     } else if (isSkinEntry) {
       // Skin entry but skin PSO not ready (cache miss / async build pending,
       // or skin pipeline layout failed at boot). Skip the draw rather than
@@ -762,6 +851,8 @@ export function recordGeometryDraws(
         entry.source.skin !== undefined
           ? SKIN_MATERIAL_SHADER_ID
           : submeshMaterial.materialShaderId;
+      const probeBlendAvailable =
+        probeBlendRecordAvailable && isStandardPbrMaterialShader(smMaterialShaderId);
       const isSpriteShader =
         smMaterialShaderId === 'forgeax::sprite' || smMaterialShaderId === 'forgeax::sprite-lit';
       // Preserve the dedicated sprite-pass state when the linear-LDR graph
@@ -778,6 +869,8 @@ export function recordGeometryDraws(
         : geometryRenderStateForTopology(smTopology, submeshMaterial.renderState);
       const pipelineRenderState = geometryRenderStateForPass(basePipelineRenderState, passKind);
       let smPipelineHandle: typeof pipelineState.unlitPipeline;
+      let materialGroup2Contract: 'mesh' | 'skin' | 'cluster' | 'skin-cluster' | undefined;
+      let materialPipelineEntry: MaterialShaderPipelineEntry | null = null;
       if (smMaterialShaderId === undefined || smMaterialShaderId === 'forgeax::default-unlit') {
         const unlitShaderId = smMaterialShaderId ?? 'forgeax::default-unlit';
         const unlitProjectionVariantResult = variantSetFromVertexLayoutProjection(
@@ -789,9 +882,10 @@ export function recordGeometryDraws(
           continue;
         }
         const unlitHasColor = unlitProjectionVariantResult.value === 'VERTEX_COLOR_AVAILABLE=true';
-        const unlitVariantSet = unlitHasColor
-          ? ''
-          : 'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+        const unlitVariantSet = standardStorageVariantSet(
+          runtime.device.caps.storageBuffer,
+          unlitHasColor,
+        );
         const unlitRsp = resolveMaterialPipeline(
           unlitShaderId,
           pipelineRenderState,
@@ -801,8 +895,9 @@ export function recordGeometryDraws(
           colorFormatOverride,
           entry.mesh.layoutProjection,
         );
+        materialPipelineEntry = unlitRsp;
         smPipelineHandle =
-          unlitRsp ??
+          unlitRsp?.pipeline ??
           (colorFormatOverride === undefined
             ? selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive)
             : null);
@@ -829,11 +924,12 @@ export function recordGeometryDraws(
         // VERTEX_COLOR_AVAILABLE=false axis, so retain the two capability
         // axes explicitly or the selector would silently choose the URP
         // group(2) layout for an HDRP cluster bind group.
-        const capabilityVariantSet = frameState.isHdrpActive
-          ? hasVertexColor
-            ? ''
-            : 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true'
-          : 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+        const capabilityVariantSet = standardTopologyVariantSet(
+          c.standardLighting,
+          runtime.device.caps.storageBuffer,
+          hasVertexColor,
+          probeBlendAvailable,
+        );
         // Sprite's base request must retain the boot-selected artifact. Only
         // SpriteInstances uses the explicit empty key for the
         // PER_INSTANCE_REGION=true variant; synthesizing the generic PBR
@@ -848,19 +944,12 @@ export function recordGeometryDraws(
             : capabilityVariantSet === ''
               ? entry.variantSet
               : `${capabilityVariantSet}+${entry.variantSet}`;
-        const projectionVariantSetResult = isSpriteShader
-          ? ({ ok: true, value: variantSet } as const)
-          : variantSetFromVertexLayoutProjection(entry.mesh.layoutProjection, variantSet);
-        if (!projectionVariantSetResult.ok) {
-          runtime.errorRegistry.fire(projectionVariantSetResult.error);
-          continue;
-        }
         const cachedPipeline = resolveMaterialPipeline(
           smMaterialShaderId,
           pipelineRenderState,
           smTopology,
           entry.mesh.indexFormat,
-          projectionVariantSetResult.value,
+          variantSet,
           colorFormatOverride,
           entry.mesh.layoutProjection,
         );
@@ -877,7 +966,8 @@ export function recordGeometryDraws(
         // build resolves. The pre-loop skin-PSO probe still skips the
         // entire entry on first-submesh probe miss; this site only
         // fires on per-submesh topology variance miss.
-        smPipelineHandle = cachedPipeline ?? null;
+        materialPipelineEntry = cachedPipeline;
+        smPipelineHandle = cachedPipeline?.pipeline ?? null;
       } else {
         smPipelineHandle = selectGeometryPipeline(pipelineState, isHdrTarget, msaaActive);
       }
@@ -885,37 +975,38 @@ export function recordGeometryDraws(
       if (smPipelineHandle === null) {
         continue;
       }
+      // The probe record is an ABI extension of the built-in Standard PBR
+      // shaders only. RenderScene may retain a record on every projected
+      // renderable, but unlit/custom shaders still use the one-binding
+      // instances BGL and must never receive the probe bind group. Resolve
+      // this per submesh so mixed-material meshes cannot cross the layouts.
+      const instanceDraws = resolveGeometryInstanceBuffer(
+        c,
+        entry,
+        identityInstanceDraws,
+        probeBlendAvailable,
+      );
+      if (instanceDraws === null) continue;
       // Standard clustered PBR variants declare the unified cluster/SSAO
       // group(2) layout. Unlit and other URP-layout materials must bind the
       // ordinary mesh group instead; choosing one group for the whole pass
       // makes Dawn reject an otherwise valid unlit pipeline and invalidates
       // the command buffer before it reaches the surface.
-      const usesStandardClusterBindings = smMaterialShaderId === 'forgeax::default-standard-pbr';
       if (!isSkinEntry) {
-        if (usesStandardClusterBindings) {
-          if (meshGroup2 === null) continue;
-          group2BindGroup = meshGroup2;
-        } else {
-          const fallbackGroup = meshBindGroup ?? meshGroup2;
-          if (fallbackGroup === null) continue;
-          group2BindGroup = fallbackGroup;
-        }
+        materialGroup2Contract = materialPipelineEntry?.group2Contract;
+        if (materialGroup2Contract === undefined) continue;
+        const selectedGroup = selectMaterialGroup2(
+          meshGroup2,
+          meshBindGroup,
+          materialGroup2Contract,
+        );
+        if (selectedGroup === null) continue;
+        group2BindGroup = selectedGroup;
       }
       pass.setBindGroup(2, group2BindGroup, group2DynamicOffsets);
 
       if (profilePhase === undefined) {
-        submitSubmeshDraws(
-          pass,
-          bindingState,
-          smPipelineHandle,
-          instanceDraws,
-          entry.mesh.indexed,
-          sm.indexCount,
-          sm.vertexCount,
-          sm.indexOffset,
-        );
-      } else {
-        profileGeometrySegment(c, passKind, 'draw-submit', () =>
+        recordOcclusionCandidate(() =>
           submitSubmeshDraws(
             pass,
             bindingState,
@@ -927,6 +1018,21 @@ export function recordGeometryDraws(
             sm.indexOffset,
           ),
         );
+      } else {
+        profileGeometrySegment(c, passKind, 'draw-submit', () =>
+          recordOcclusionCandidate(() =>
+            submitSubmeshDraws(
+              pass,
+              bindingState,
+              smPipelineHandle,
+              instanceDraws,
+              entry.mesh.indexed,
+              sm.indexCount,
+              sm.vertexCount,
+              sm.indexOffset,
+            ),
+          ),
+        );
       }
     }
   }
@@ -941,10 +1047,38 @@ function resolveGeometryInstanceBuffer(
   c: _InternalRenderPipelineContext,
   entry: _InternalRenderPipelineContext['validatedOrdered'][number],
   identityInstanceDraws: readonly GeometryInstanceDraw[],
+  useProbeBlend: boolean,
 ): readonly GeometryInstanceDraw[] | null {
   const { runtime, pipelineState, frameState } = c;
   const inst = entry.source.instances;
-  if (inst === undefined) return identityInstanceDraws;
+  const probeBinding =
+    !useProbeBlend ||
+    !runtime.device.caps.storageBuffer ||
+    entry.source.probeBlendRecord === undefined
+      ? undefined
+      : resolveProbeBlendBuffer(
+          c,
+          entry.source.probeBlendRecord,
+          worldEntityKey(entry.source.worldId, entry.source.entityKey),
+        );
+  if (inst === undefined) {
+    const identity = identityInstanceDraws[0];
+    if (identity === undefined) return null;
+    return [
+      {
+        ...identity,
+        instanceBindGroup: resolveGeometryInstancesBindGroup(
+          c,
+          pipelineState.identityInstanceBuffer,
+          probeBinding?.buffer,
+        ),
+        probeOffset: probeBinding?.offset ?? -1,
+      },
+    ];
+  }
+  // A present, empty Instances array means zero draws. Do not fall back to
+  // the shared identity buffer, which would silently render one instance.
+  if (inst.instanceCount === 0) return [];
   let instanceBuffer: Buffer = pipelineState.identityInstanceBuffer;
   let instanceCount = 1;
   {
@@ -982,7 +1116,12 @@ function resolveGeometryInstanceBuffer(
         }
         draws.push({
           instanceBuffer: buffer.handle,
-          instanceBindGroup: resolveGeometryInstancesBindGroup(c, buffer.handle),
+          instanceBindGroup: resolveGeometryInstancesBindGroup(
+            c,
+            buffer.handle,
+            probeBinding?.buffer,
+          ),
+          probeOffset: probeBinding?.offset ?? -1,
           instanceCount: count,
         });
       }
@@ -1074,25 +1213,80 @@ function resolveGeometryInstanceBuffer(
   return [
     {
       instanceBuffer,
-      instanceBindGroup: resolveGeometryInstancesBindGroup(c, instanceBuffer),
+      instanceBindGroup: resolveGeometryInstancesBindGroup(c, instanceBuffer, probeBinding?.buffer),
+      probeOffset: probeBinding?.offset ?? -1,
       instanceCount,
     },
   ];
 }
 
-function resolveGeometryInstancesBindGroup(
+export function resolveProbeBlendBuffer(
+  c: _InternalRenderPipelineContext,
+  record: import('../scene/probe-blend-record').ProbeBlendRecord | undefined,
+  entityKey?: number,
+): { readonly buffer: Buffer; readonly offset: number } {
+  const { runtime, frameState } = c;
+  const usage = runtime.device.caps.storageBuffer
+    ? GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST
+    : GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST;
+  if (record === undefined) throw new Error('probe blend record is required for probe allocation');
+  if (entityKey === undefined) throw new Error('probe blend record requires an entity key');
+  const offset = probeBlendRecordOffset(record.objectKey);
+  const requiredCapacity = record.objectKey + 2;
+  let buffer = frameState.probeBlendRecordBuffer;
+  if (buffer === undefined || frameState.probeBlendRecordBufferCapacity < requiredCapacity) {
+    const created = runtime.device.createBuffer({
+      label: 'probe-blend-records',
+      size: requiredCapacity * PROBE_BLEND_RECORD_STRIDE,
+      usage,
+      mappedAtCreation: false,
+    });
+    if (!created.ok) throw created.error;
+    buffer = new GpuBuffer(runtime.device, created.value);
+    frameState.probeBlendRecordBuffer = buffer;
+    frameState.probeBlendRecordBufferCapacity = requiredCapacity;
+    // The cache is tied to the previous backing allocation. A new buffer has
+    // no valid record contents, so every later object must upload its full
+    // 160B payload even when generation/bytes match the old allocation.
+    frameState.probeBlendBuffers.clear();
+  }
+  const cached = frameState.probeBlendBuffers.get(entityKey);
+  const unchanged =
+    cached !== undefined &&
+    cached.generation === record.generation &&
+    cached.bytes.length === record.bytes.length &&
+    cached.bytes.every((value, index) => value === record.bytes[index]);
+  if (!unchanged) {
+    const uploaded = runtime.device.queue.writeBuffer(buffer.handle, offset, record.bytes);
+    if (!uploaded.ok) throw uploaded.error;
+    // Publish the generation only after the complete 160B queue write succeeds.
+    frameState.probeBlendBuffers.set(entityKey, {
+      generation: record.generation,
+      bytes: new Uint8Array(record.bytes),
+    });
+  }
+  return { buffer: buffer.handle, offset };
+}
+
+export function resolveGeometryInstancesBindGroup(
   c: _InternalRenderPipelineContext,
   instanceBuffer: Buffer,
+  probeBuffer?: Buffer,
 ): BindGroup {
   const { runtime, pipelineState, frameState, bindGroupCounts } = c;
+  const layout =
+    probeBuffer === undefined
+      ? pipelineState.instancesBindGroupLayout
+      : pipelineState.probeInstancesBindGroupLayout;
+  if (layout === undefined) throw new Error('probe instances bind-group layout is unavailable');
   return getOrCreateFromChain(
     frameState.instancesBgShared,
-    [pipelineState.instancesBindGroupLayout, instanceBuffer],
-    'instances',
+    probeBuffer === undefined ? [layout, instanceBuffer] : [layout, instanceBuffer, probeBuffer],
+    probeBuffer === undefined ? 'instances-no-probe' : 'instances-probe',
     () => {
       const result = runtime.device.createBindGroup({
         label: 'pbr-instances-bg',
-        layout: pipelineState.instancesBindGroupLayout,
+        layout,
         entries: [
           {
             binding: 0,
@@ -1101,6 +1295,17 @@ function resolveGeometryInstancesBindGroup(
               value: { buffer: instanceBuffer },
             },
           },
+          ...(probeBuffer === undefined
+            ? []
+            : [
+                {
+                  binding: 1,
+                  resource: {
+                    kind: 'buffer' as const,
+                    value: { buffer: probeBuffer, offset: 0, size: PROBE_BLEND_RECORD_BYTE_SIZE },
+                  },
+                },
+              ]),
         ],
       });
       if (!result.ok) throw result.error;