@forgeax/engine-render 0.1.21 → 0.1.24

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

@@ -10,7 +10,7 @@ import {
   RhiError,
   type RhiRenderPassEncoder,
 } from '@forgeax/engine-rhi';
-import type { PassKind, PrimitiveTopology } from '@forgeax/engine-types';
+import type { ParamSchemaEntry, PassKind, PrimitiveTopology } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
 import {
   GPU_BUFFER_USAGE_COPY_DST,
@@ -22,7 +22,12 @@ import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
 import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '../materials';
 import {
   createPbrSkinMeshBindGroupEntries,
+  isCanonicalStandardPbrMaterialShader,
+  isStandardPbrMaterialShader,
+  isStandardPbrSkinMaterialShader,
+  materialBindGroupLayoutIdentity,
   pbrSkinMeshDynamicOffsets,
+  physicalTextureFields,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
 import {
@@ -35,7 +40,12 @@ 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 { worldEntityKey } from './frame-snapshot';
+import {
+  PROBE_BLEND_RECORD_BYTE_SIZE,
+  PROBE_BLEND_RECORD_STRIDE,
+  probeBlendRecordOffset,
+} from '../scene/probe-blend-record';
+import { getOpaqueResourceIdentity, worldEntityKey } from './frame-snapshot';
 import {
   geometryRenderStateForTopology,
   isEntityFullyTransparent,
@@ -58,14 +68,29 @@ import { POINTS_LINES_VIEW_SLOT_STRIDE, writePointsLinesViewUbo } from './view-u
 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;
 };
 
+function materialDiagnosticsEnabled(): boolean {
+  if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
+    return false;
+  }
+  const processValue = (
+    globalThis as {
+      readonly process?: { readonly env?: Record<string, string | undefined> };
+    }
+  ).process;
+  return processValue?.env?.FORGEAX_MATERIAL_DIAGNOSTICS === '1';
+}
+
 type MaterialPipelineLookup = {
   readonly materialShaderId: string;
   readonly isHdrTarget: boolean;
@@ -77,6 +102,7 @@ type MaterialPipelineLookup = {
   readonly layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection;
   readonly sampleCount: number;
   readonly colorFormatOverride: GPUTextureFormat | undefined;
+  readonly additionalColorFormats: readonly GPUTextureFormat[] | undefined;
   readonly handle: MaterialShaderPipelineEntry | null;
 };
 
@@ -84,6 +110,121 @@ type GeometryRecordProfileSegment = 'material-bind-groups' | 'pipeline-selection
 
 type GeometryRenderState = ReturnType<typeof geometryRenderStateForTopology>;
 
+/**
+ * Select the transmission shader axis from authored material data, not the
+ * canonical boot schema.  The latter reserves transmission fields for the
+ * shared Standard ABI even when a material remains base-only.
+ */
+export function requestsStandardTransmissionVariant(
+  material: Pick<MaterialSnapshot, 'materialShaderId' | 'paramSnapshot'>,
+): boolean {
+  return (
+    material.materialShaderId === 'forgeax::default-standard-pbr' &&
+    material.paramSnapshot?.transmission !== undefined
+  );
+}
+
+function recordIblPipelineBinding(
+  c: _InternalRenderPipelineContext,
+  material: MaterialSnapshot,
+  pipeline: RenderPipeline,
+  materialGroup: BindGroup,
+): void {
+  const receipt = c.frameState.iblBindingInspection;
+  if (receipt === undefined || !isStandardPbrMaterialShader(material.materialShaderId)) return;
+  const materialBgl =
+    c.runtime.getMaterialBindGroupLayout?.(
+      material.materialShaderId ?? 'forgeax::default-standard-pbr',
+    ) ?? c.pipelineState.materialBindGroupLayout;
+  c.frameState.iblBindingInspection = {
+    ...receipt,
+    pipeline: {
+      pipelineIdentity: getOpaqueResourceIdentity(pipeline as object),
+      effectiveMaterialLayoutIdentity: effectiveMaterialLayoutIdentity(
+        material.materialShaderId ?? 'forgeax::default-standard-pbr',
+        material.materialParamSchema,
+      ),
+      materialBglIdentity: getOpaqueResourceIdentity(materialBgl as object),
+      bindGroupIdentity: getOpaqueResourceIdentity(materialGroup as object),
+      drawFrameId: c.frameState.frameNumber,
+    },
+  };
+  const materialReceipt = c.frameState.iblBindingInspection.material;
+  const errors: string[] = [];
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.materialBglIdentity !== getOpaqueResourceIdentity(materialBgl as object)
+  ) {
+    errors.push('material-pipeline-bgl-identity-mismatch');
+  }
+  if (
+    materialReceipt !== undefined &&
+    materialReceipt.bindGroupIdentity !== getOpaqueResourceIdentity(materialGroup as object)
+  ) {
+    errors.push('material-bind-group-identity-mismatch');
+  }
+  if (materialReceipt !== undefined) {
+    const expectedResourceIdentities = [
+      receipt.resources.irradiance.viewIdentity,
+      receipt.resources.irradiance.samplerIdentity,
+      receipt.resources.prefilter.viewIdentity,
+      receipt.resources.prefilter.samplerIdentity,
+      receipt.resources.brdfLut.viewIdentity,
+      receipt.resources.brdfLut.samplerIdentity,
+      receipt.resources.intensityBufferIdentity,
+    ];
+    const actualResourceIdentities = materialReceipt.entries
+      .filter((entry) => entry.binding >= materialReceipt.skylightBindingStart)
+      .slice(0, expectedResourceIdentities.length)
+      .map((entry) => entry.resourceIdentity);
+    if (
+      actualResourceIdentities.length !== expectedResourceIdentities.length ||
+      actualResourceIdentities.some(
+        (identity, index) => identity !== expectedResourceIdentities[index],
+      )
+    ) {
+      errors.push('material-ibl-resource-identity-mismatch');
+    }
+  }
+  c.frameState.iblBindingInspection = {
+    ...c.frameState.iblBindingInspection,
+    status: errors.length === 0 ? 'binding-chain-consistent' : 'binding-chain-mismatch',
+    errors,
+  };
+}
+
+const SHARED_BOOT_MATERIAL_SHADER_IDS = new Set([
+  'forgeax::default-unlit',
+  'forgeax::default-shadow-caster',
+  'forgeax::sprite',
+  'forgeax::sprite-lit',
+  'forgeax::default-sprite',
+  'forgeax::msdf-text',
+  'forgeax::default-standard-pbr',
+  'forgeax::pbr-skin',
+  'forgeax::default-standard-pbr-skin',
+]);
+
+/**
+ * Returns the layout identity that can distinguish a material PSO in the
+ * record cache. Shared boot shaders keep the boot layout identity even when a
+ * manifest exposes a schema; Standard PBR only opts into a schema-derived
+ * identity when authored clearcoat texture bindings extend that layout.
+ */
+export function effectiveMaterialLayoutIdentity(
+  materialShaderId: string,
+  materialParamSchema?: readonly ParamSchemaEntry[],
+): string | undefined {
+  if (materialParamSchema === undefined) return undefined;
+  const hasStandardPhysicalMaps =
+    isStandardPbrMaterialShader(materialShaderId) &&
+    physicalTextureFields(materialParamSchema).length > 0;
+  if (SHARED_BOOT_MATERIAL_SHADER_IDS.has(materialShaderId) && !hasStandardPhysicalMaps) {
+    return undefined;
+  }
+  return materialBindGroupLayoutIdentity(materialShaderId, materialParamSchema);
+}
+
 /**
  * Resolve the depth contract for a geometry pass without changing the base
  * material state. Temporal scene-data shares the main pass depth attachment:
@@ -138,9 +279,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);
@@ -210,6 +359,7 @@ export function recordGeometryDraws(
     viewBindGroup,
     viewBindGroupDynamicOffset = 0,
   } = c;
+  const diagnosticsEnabled = materialDiagnosticsEnabled();
   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
@@ -226,12 +376,14 @@ 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,
     },
   ];
@@ -253,6 +405,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'],
@@ -262,6 +417,19 @@ export function recordGeometryDraws(
     colorFormat: GPUTextureFormat | undefined,
     layoutProjection: import('@forgeax/engine-geometry').VertexLayoutProjection,
   ): 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);
@@ -276,7 +444,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;
         }
@@ -292,6 +461,12 @@ 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.getMaterialShaderPipelineEntry?.(
         materialShaderId,
@@ -299,7 +474,7 @@ export function recordGeometryDraws(
         renderState,
         topology,
         indexFormat,
-        resolvedVariantSet,
+        fallbackVariantSet,
         passKind,
         undefined,
         sampleCount,
@@ -308,6 +483,9 @@ export function recordGeometryDraws(
         undefined,
         undefined,
         layoutProjection,
+        undefined,
+        undefined,
+        reflectionFallbackFormats,
       ) ?? null;
     const handle =
       profilePhase === undefined
@@ -332,6 +510,7 @@ export function recordGeometryDraws(
         layoutProjection,
         sampleCount,
         colorFormatOverride: colorFormat,
+        additionalColorFormats: reflectionFallbackFormats,
         handle,
       };
       if (shaderLookupCache === undefined) {
@@ -361,7 +540,12 @@ export function recordGeometryDraws(
 
     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;
     }
@@ -454,12 +638,11 @@ 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);
+        resolveGeometryInstancesBindGroup(c, identityInstanceBuffer, undefined);
+      pass.setBindGroup(3, pointsLinesInstancesBg);
+      recordOcclusionCandidate(() => recordPointsLinesDraw(pass, pointsLinesSubmission.plan));
       pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
       continue;
     }
@@ -487,7 +670,7 @@ 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 3-binding
@@ -518,6 +701,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
@@ -534,7 +719,22 @@ export function recordGeometryDraws(
     // and walks 0, 1536, 3072, ... on the storage path.
     const skinAllocator = pipelineState.skinPaletteAllocator;
     const skinSlice = entry.source.skin;
-    const clusteredSkin = clusteredLighting;
+    // Authored Standard skin aliases deliberately publish the physical root
+    // with only their STORAGE_BUFFER capability axis. Their composed WGSL is
+    // the direct-lighting/palette (`skin`) ABI, even when the frame's
+    // canonical Standard lane uses clustered lighting. Only the canonical
+    // engine skin artifact can consume the HDRP unified skin group(2) layout;
+    // selecting it from the frame topology alone would bind
+    // `hdrp-skin-unified-bg-group2` to a three-entry URP skin PSO.
+    const clusteredSkin =
+      clusteredLighting &&
+      entry.source.materials.every((material) => {
+        const shaderId = material.materialShaderId;
+        return (
+          !isStandardPbrSkinMaterialShader(shaderId) ||
+          isCanonicalStandardPbrMaterialShader(shaderId)
+        );
+      });
     const skinMeshBindGroupLayout = clusteredSkin
       ? pipelineState.hdrpSkinMeshBindGroupLayout
       : pipelineState.pbrSkinMeshBindGroupLayout;
@@ -567,6 +767,7 @@ export function recordGeometryDraws(
         c.standardLighting,
         runtime.device.caps.storageBuffer,
         entry.mesh.layoutProjection.attributes.some((attribute) => attribute.key === 'color'),
+        probeBlendRecordAvailable,
       ),
     );
     if (!skinVariantSetResult.ok) runtime.errorRegistry.fire(skinVariantSetResult.error);
@@ -588,6 +789,9 @@ export function recordGeometryDraws(
             undefined,
             undefined,
             entry.mesh.layoutProjection,
+            undefined,
+            undefined,
+            undefined,
           ) ?? null)
         : null;
     if (skinResources !== null && skinPsoProbe !== null) {
@@ -677,6 +881,19 @@ export function recordGeometryDraws(
       // the async PSO compile resolves the cache hits and the next frame
       // routes the skin BG + skin pipeline together. Mirrors the uniform
       // null skip-draw shape (M6-T1, charter P3 explicit failure).
+      if (diagnosticsEnabled) {
+        console.error(
+          `[render-material] skin draw skipped: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: entry.source.material.materialHandle,
+            reason: 'skin-pipeline-unavailable',
+            skinResourcesReady: skinResources !== null,
+            skinPsoReady: skinPsoProbe !== null,
+            paletteBufferReady: skinSlice?.buffer !== undefined,
+            paletteByteOffset: skinSlice?.byteOffset,
+          })}`,
+        );
+      }
       continue;
     }
     // feat-20260520-2d-sprite-layer-mvp M-3 / w25 (@fallback sprite
@@ -771,6 +988,26 @@ export function recordGeometryDraws(
       // injection, and Skylight merge; deduped cross-entity via the
       // shaderId-outer `materialBgShared` cache.
       const materialSlot = materialSlotIndices[i]?.[matSlotIdx] ?? materialSlotIndices[i]?.[0] ?? 0;
+      const processValue = (
+        globalThis as {
+          process?: { env?: Record<string, string | undefined> };
+        }
+      ).process;
+      if (
+        processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
+        (submeshMaterial.materialShaderId === 'forgeax::default-standard-pbr' ||
+          submeshMaterial.materialShaderId === 'forgeax::pbr-skin')
+      ) {
+        console.error(
+          `[render-material] draw receipt: ${JSON.stringify({
+            entityIndex: entry.renderableIndex,
+            materialSlot,
+            materialHandle: submeshMaterial.materialHandle,
+            clearcoat: submeshMaterial.paramSnapshot?.clearcoat,
+            shader: submeshMaterial.materialShaderId,
+          })}`,
+        );
+      }
       perSubmeshBg =
         profilePhase === undefined
           ? resolveMaterialBindGroup(
@@ -792,8 +1029,12 @@ export function recordGeometryDraws(
       const smTopology = sm.topology;
       const smMaterialShaderId =
         entry.source.skin !== undefined
-          ? SKIN_MATERIAL_SHADER_ID
+          ? isStandardPbrSkinMaterialShader(submeshMaterial.materialShaderId)
+            ? submeshMaterial.materialShaderId
+            : 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
@@ -869,7 +1110,13 @@ export function recordGeometryDraws(
           c.standardLighting,
           runtime.device.caps.storageBuffer,
           hasVertexColor,
+          probeBlendAvailable,
         );
+        const transmissionAvailable = requestsStandardTransmissionVariant(submeshMaterial);
+        const materialCapabilityVariantSet =
+          transmissionAvailable && !capabilityVariantSet.includes('TRANSMISSION_AVAILABLE=')
+            ? `${capabilityVariantSet === '' ? '' : `${capabilityVariantSet}+`}TRANSMISSION_AVAILABLE=true`
+            : capabilityVariantSet;
         // 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
@@ -880,23 +1127,16 @@ export function recordGeometryDraws(
             ? ''
             : undefined
           : entry.variantSet === undefined
-            ? capabilityVariantSet
+            ? materialCapabilityVariantSet
             : 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,
         );
@@ -920,8 +1160,30 @@ export function recordGeometryDraws(
       }
 
       if (smPipelineHandle === null) {
+        if (diagnosticsEnabled) {
+          console.error(
+            `[render-material] draw skipped: ${JSON.stringify({
+              entityKey: entry.source.entityKey,
+              materialHandle: submeshMaterial.materialHandle,
+              shader: smMaterialShaderId,
+              reason: 'pipeline-unavailable',
+            })}`,
+          );
+        }
         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
@@ -938,21 +1200,35 @@ export function recordGeometryDraws(
         if (selectedGroup === null) continue;
         group2BindGroup = selectedGroup;
       }
+      if (diagnosticsEnabled && submeshMaterial.textureHandles !== undefined) {
+        console.error(
+          `[render-material] draw submitted: ${JSON.stringify({
+            entityKey: entry.source.entityKey,
+            materialHandle: submeshMaterial.materialHandle,
+            shader: smMaterialShaderId,
+            textureHandles: [...submeshMaterial.textureHandles.entries()].map(
+              ([field, handle]) => ({
+                field,
+                handle,
+              }),
+            ),
+            skin: isSkinEntry
+              ? {
+                  resourcesReady: skinResources !== null,
+                  psoReady: skinPsoProbe !== null,
+                  paletteBufferReady: skinSlice?.buffer !== undefined,
+                  paletteByteOffset: skinSlice?.byteOffset,
+                  dynamicOffsets: [...group2DynamicOffsets],
+                }
+              : undefined,
+            pipelineReady: true,
+          })}`,
+        );
+      }
       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,
@@ -964,6 +1240,24 @@ 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,
+            ),
+          ),
+        );
+      }
+      if (diagnosticsEnabled && perSubmeshBg !== null) {
+        recordIblPipelineBinding(c, submeshMaterial, smPipelineHandle, perSubmeshBg);
       }
     }
   }
@@ -978,10 +1272,35 @@ 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 [];
@@ -1022,7 +1341,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,
         });
       }
@@ -1114,25 +1438,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,
@@ -1141,6 +1520,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;