@forgeax/engine-render 0.1.7 → 0.1.19

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

@@ -20,6 +20,7 @@ import {
 import {
   DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
   DEFAULT_SPRITE_PARAM_SCHEMA,
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
   DEFAULT_UNLIT_PARAM_SCHEMA,
 } from '@forgeax/engine-shader';
 import type {
@@ -36,8 +37,8 @@ import type { GpuResidencyCache } from '../device/gpu-residency';
 import { VideoUploadUnsupportedError } from '../errors/render';
 import {
   assembleMaterialWithSkylightEntries,
-  type EmissiveAoBindGroupResources,
   type SkylightBindGroupResources,
+  type TransmissionBindGroupResources,
 } from '../ibl/skylight-bind-group';
 import { isStandardPbrMaterialShader } from '../pbr-pipeline';
 import { deriveTextureExtent } from '../render-data';
@@ -376,10 +377,16 @@ export const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
   'specularTintTexture',
   'emissiveTexture',
   'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
 ];
 
 const LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET = 80;
-const STANDARD_PBR_TEXTURE_SCALE_OFFSET = 96;
+// The Standard schema owns five transmission numeric fields between
+// normalScale and the engine-owned coordinate records. Keep this fallback
+// aligned with derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA): the first record is
+// at byte 128, not the pre-transmission byte 96.
+const STANDARD_PBR_TEXTURE_SCALE_OFFSET = 128;
 const MATERIAL_TEXTURE_SCALE_FIELDS = [
   'baseColorTexture',
   'metallicRoughnessTexture',
@@ -387,6 +394,8 @@ const MATERIAL_TEXTURE_SCALE_FIELDS = [
   'specularTintTexture',
   'emissiveTexture',
   'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
 ] as const;
 const LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS = [
   'baseColorTexture',
@@ -395,12 +404,12 @@ const LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS = [
   'emissiveTexture',
   'occlusionTexture',
 ] as const;
-const STANDARD_PBR_TEXTURE_COORDINATE_OFFSET = 96;
+const STANDARD_PBR_TEXTURE_COORDINATE_OFFSET = 128;
 const STANDARD_PBR_TEXTURE_COORDINATE_STRIDE = 8;
 const DEFAULT_LEGACY_TEXTURE_SCALES = new Float32Array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
 const DEFAULT_STANDARD_TEXTURE_COORDINATES = new Float32Array([
   0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0,
-  0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
+  0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
 ]);
 
 /** Derives the logical-content UV scale for an uploaded material texture. */
@@ -465,9 +474,9 @@ export function applyMaterialTextureUvScales(
     }
     return;
   }
-  // Standard PBR grew two authored coat fields before the engine-owned UV
-  // tail. Sprite, sprite-lit, unlit, and text keep their own 80-byte tail
-  // position because their WGSL layouts do not carry clearcoat.
+  // Standard PBR has a schema-derived 128-byte authored region before the
+  // engine-owned UV records. Sprite, sprite-lit, unlit, and text keep their
+  // own legacy tail positions because their WGSL layouts differ.
   const textureScaleOffset = isStandardPbrMaterialShader(material.materialShaderId)
     ? STANDARD_PBR_TEXTURE_SCALE_OFFSET
     : LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET;
@@ -523,6 +532,12 @@ export function applyMaterialTextureUvScales(
 function materialCoordinateSchema(
   material: MaterialSnapshot,
 ): readonly ParamSchemaEntry[] | undefined {
+  if (
+    isStandardPbrMaterialShader(material.materialShaderId) &&
+    material.paramSnapshot !== undefined
+  ) {
+    return DEFAULT_STANDARD_PBR_PARAM_SCHEMA;
+  }
   if (material.materialParamSchema !== undefined && material.materialParamSchema.length > 0) {
     return material.materialParamSchema;
   }
@@ -543,15 +558,16 @@ function materialCoordinateSchema(
  * feat-20260621-learn-render-5-5-parallax M2 / w8 (D-3): ordered user-region
  * texture field names for a material's bind-group assembly, derived from the
  * shader's paramSchema via the `derive()` SSOT (insertion order = sampler/
- * texture pair order in derive().bglEntries). Falls back to the built-in 4
- * fields when the schema is unavailable.
+ * texture pair order in derive().bglEntries). Falls back to the built-in
+ * fields only when the schema is unavailable; an explicit empty schema means
+ * the authored material has no user-region textures.
  */
 export function userRegionTextureFieldOrder(
   schema: Parameters<typeof derive>[0] | undefined,
 ): readonly string[] {
-  if (schema === undefined || schema.length === 0) return BUILTIN_USER_REGION_TEXTURE_FIELDS;
+  if (schema === undefined) return BUILTIN_USER_REGION_TEXTURE_FIELDS;
   const fields = [...derivedParamSchema(schema).textureFieldNames];
-  return fields.length === 0 ? BUILTIN_USER_REGION_TEXTURE_FIELDS : fields;
+  return fields;
 }
 
 /**
@@ -613,7 +629,7 @@ export function detectNineSliceScaleTooSmall(
 }
 
 /**
- * Build the 128-byte Material UBO payload for a PBR / unlit material entry
+ * Build the 384-byte Material UBO payload for a PBR / unlit material entry
  * (feat-20260527-sprite-nineslice M2 / w11; D-7 regression-net helper).
  *
  * Byte-for-byte equivalent to the legacy hard-coded PBR write path; each
@@ -634,7 +650,7 @@ export function buildPbrMaterialUboPayload(material: MaterialSnapshot): Uint8Arr
  *
  * The allocating wrapper above remains the byte-stable test/helper surface,
  * while the frame recorder reuses one scratch slot for all materials. A
- * scene with thousands of submeshes otherwise allocates one 304-byte
+ * scene with thousands of submeshes otherwise allocates one 384-byte
  * Uint8Array per material per frame, creating avoidable GC pressure without
  * changing GPU-visible bytes.
  */
@@ -667,9 +683,13 @@ export function writePbrMaterialUboPayload(
   //   f32[18]     clearcoat          (offset 72)
   //   f32[19]     clearcoatRoughness (offset 76)
   //   f32[20..22] specularTint       (offset 80, vec3)
-  //                                  (offset 92..95 alignment pad)
-  //   f32[24..71] engine-owned texture coordinate records (offset 96)
-  //   f32[72]     normalScale        (offset 288)
+  //   f32[23]     normalScale        (offset 92)
+  //   f32[24]     transmission       (offset 96)
+  //   f32[25]     ior                (offset 100)
+  //   f32[26]     thickness          (offset 104)
+  //   f32[28..30] attenuationColor   (offset 112, vec3)
+  //   f32[31]     attenuationDistance(offset 124)
+  //   f32[32..95] engine-owned texture coordinate records (offset 128)
   f32[0] = material.baseColor[0] ?? 0;
   f32[1] = material.baseColor[1] ?? 0;
   f32[2] = material.baseColor[2] ?? 0;
@@ -700,7 +720,28 @@ export function writePbrMaterialUboPayload(
   f32[20] = specularTint?.[0] ?? 1;
   f32[21] = specularTint?.[1] ?? 1;
   f32[22] = specularTint?.[2] ?? 1;
-  f32[72] = material.normalScale ?? 1;
+  const snapshotNumber = (name: string, fallback: number): number => {
+    const value = material.paramSnapshot?.[name];
+    return typeof value === 'number' ? value : fallback;
+  };
+  const snapshotVec3 = (
+    name: string,
+    fallback: readonly [number, number, number],
+  ): readonly [number, number, number] => {
+    const value = material.paramSnapshot?.[name];
+    return Array.isArray(value)
+      ? [value[0] ?? fallback[0], value[1] ?? fallback[1], value[2] ?? fallback[2]]
+      : fallback;
+  };
+  f32[23] = material.normalScale ?? snapshotNumber('normalScale', 1);
+  f32[24] = snapshotNumber('transmission', 0);
+  f32[25] = snapshotNumber('ior', 1.5);
+  f32[26] = snapshotNumber('thickness', 0);
+  const attenuationColor = snapshotVec3('attenuationColor', [1, 1, 1]);
+  f32[28] = attenuationColor[0];
+  f32[29] = attenuationColor[1];
+  f32[30] = attenuationColor[2];
+  f32[31] = snapshotNumber('attenuationDistance', 0);
   // Schema-driven paramSnapshot overlay (feat-20260523 M9-T05, AC-14):
   // for user-shaders with a paramSnapshot, project the first vec4/color
   // entry onto slot 0 and the first two f32 entries onto slot 1's first
@@ -780,7 +821,13 @@ export function applyParamSnapshotToUbo(
   if (paramSchema === undefined) return;
   if (paramSnapshot === undefined) return;
   const f32 = materialUboFloatView(payload);
-  const { uboLayout } = derivedParamSchema(paramSchema);
+  const effectiveSchema =
+    Object.hasOwn(paramSnapshot, 'transmission') &&
+    Object.hasOwn(paramSnapshot, 'ior') &&
+    Object.hasOwn(paramSnapshot, 'thickness')
+      ? DEFAULT_STANDARD_PBR_PARAM_SCHEMA
+      : paramSchema;
+  const { uboLayout } = derivedParamSchema(effectiveSchema);
   for (const entry of uboLayout.entries) {
     const value = paramSnapshot[entry.name];
     if (value === undefined) continue;
@@ -837,6 +884,8 @@ export interface PerSubmeshMaterialBgDeps {
   readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
   /** Cross-frame final BG reuse keyed by the stable source material handle. */
   readonly materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
+  /** Active transmission backdrop; undefined/null means layout placeholder. */
+  readonly transmissionBackdropView?: TextureView | null;
   readonly bindGroupCounts: BindGroupCounts;
 }
 
@@ -848,7 +897,9 @@ export function isMaterialBgAssemblyCacheHit(
   materialBuffer: Buffer,
   skylightResources: SkylightBindGroupResources,
   materialResourceEpoch: number,
+  transmissionBackdropView?: TextureView | null,
 ): cached is MaterialBgAssemblyCacheEntry {
+  if (transmissionBackdropView != null) return false;
   return (
     cached?.material === material &&
     cached.materialResourceEpoch === materialResourceEpoch &&
@@ -879,6 +930,7 @@ export function buildPerSubmeshMaterialBg(
     skylightResources,
     materialBgShared,
     materialBgAssemblyCache,
+    transmissionBackdropView,
     bindGroupCounts,
   } = deps;
   const smMaterialHandle = submeshMaterial.materialHandle;
@@ -889,7 +941,8 @@ export function buildPerSubmeshMaterialBg(
   const smPerShaderBgl =
     smShaderId !== undefined ? runtime.getMaterialBindGroupLayout?.(smShaderId) : undefined;
   const smMaterialBgl = smPerShaderBgl ?? pipelineState.materialBindGroupLayout;
-  if (smMaterialHandle !== undefined && !smHasVideoFields) {
+  const hasActiveTransmissionBackdrop = transmissionBackdropView != null;
+  if (smMaterialHandle !== undefined && !smHasVideoFields && !hasActiveTransmissionBackdrop) {
     const cached =
       materialCacheKey === undefined ? undefined : materialBgAssemblyCache.get(materialCacheKey);
     if (
@@ -900,6 +953,7 @@ export function buildPerSubmeshMaterialBg(
         pipelineState.materialUniformBuffer.buffer,
         skylightResources,
         store.materialResourceEpoch,
+        transmissionBackdropView,
       )
     ) {
       return cached.bindGroup;
@@ -908,12 +962,11 @@ export function buildPerSubmeshMaterialBg(
   const smSchema =
     submeshMaterial.materialParamSchema ??
     (smShaderId !== undefined ? runtime.getParamSchema?.(smShaderId) : undefined);
-  // The shipped PBR shaders always own the six texture pairs declared by the
-  // standard shader artifact. Authored material snapshots may intentionally
-  // carry a compact four-field schema because emissive/occlusion are engine
-  // injected values, but the runtime PBR BGL still exposes bindings 9..12 for
-  // those pairs. Keep the record projection on the shader-owned layout so IBL
-  // starts at binding 13 rather than colliding with emissiveSampler.
+  // The shipped PBR shaders always own the eight texture pairs declared by the
+  // standard shader artifact. The runtime PBR BGL exposes those pairs directly;
+  // emissive and occlusion are not duplicated in an engine injection region.
+  // Keep the record projection on the shader-owned layout so IBL starts at
+  // binding 17 rather than colliding with transmissionSampler.
   const smUserRegionFields =
     smPerShaderBgl === undefined || isStandardPbrMaterialShader(smShaderId)
       ? BUILTIN_USER_REGION_TEXTURE_FIELDS
@@ -986,48 +1039,43 @@ export function buildPerSubmeshMaterialBg(
       },
     );
   }
-  let smEmissiveView: TextureView = pipelineState.defaultWhiteTextureView;
-  const smEmissiveHandle = submeshMaterial.emissiveTexture;
-  if (smEmissiveHandle !== undefined) {
-    const view = residentTextureView(materialWorld, store, runtime, smEmissiveHandle);
-    if (view !== undefined) smEmissiveView = view;
-    else materialResourcesResident = false;
-  }
-  let smOcclusionView: TextureView = pipelineState.defaultWhiteTextureView;
-  const smOcclusionHandle = submeshMaterial.occlusionTexture;
-  if (smOcclusionHandle !== undefined) {
-    const view = residentTextureView(materialWorld, store, runtime, smOcclusionHandle);
-    if (view !== undefined) smOcclusionView = view;
-    else materialResourcesResident = false;
-  }
-  const smEmissiveAo: EmissiveAoBindGroupResources = {
-    emissiveSampler: smSamplerForField('emissiveTexture'),
-    emissiveView: smEmissiveView,
-    occlusionSampler: smSamplerForField('occlusionTexture'),
-    occlusionView: smOcclusionView,
+  // The backdrop is a full mip-chain view owned by the pipeline. Reuse the
+  // pipeline's existing filtering/clamp sampler for screen-space sampling;
+  // the material default sampler intentionally keeps repeat addressing for
+  // authored UV textures and is not a backdrop sampler.
+  const transmissionSampler =
+    transmissionBackdropView != null
+      ? skylightResources.prefilterSampler
+      : pipelineState.defaultSampler;
+  const smMergedEntries = assembleMaterialWithSkylightEntries(smBaseEntries, skylightResources, {
+    sampler: transmissionSampler,
+    ...(transmissionBackdropView === undefined ? {} : { backdropView: transmissionBackdropView }),
+  } satisfies TransmissionBindGroupResources);
+  const createBindGroup = (): BindGroup => {
+    const result = runtime.device.createBindGroup({
+      label: 'pbr-material-skylight-bg',
+      layout: smMaterialBgl,
+      entries: smMergedEntries,
+    });
+    if (!result.ok) throw result.error;
+    return result.value;
   };
-  const smMergedEntries = assembleMaterialWithSkylightEntries(
-    smBaseEntries,
-    skylightResources,
-    smEmissiveAo,
-  );
-  const smBindGroup = getOrCreatePerEntity(
-    materialBgShared,
-    smShaderId ?? '',
-    smMergedEntries.map((e) => extractEntryResourceHandle(e)),
-    'material-shared',
-    () => {
-      const result = runtime.device.createBindGroup({
-        label: 'pbr-material-skylight-bg',
-        layout: smMaterialBgl,
-        entries: smMergedEntries,
-      });
-      if (!result.ok) throw result.error;
-      return result.value;
-    },
-    bindGroupCounts,
-  );
-  if (smMaterialHandle !== undefined && !smHasVideoFields && materialResourcesResident) {
+  const smBindGroup = hasActiveTransmissionBackdrop
+    ? createBindGroup()
+    : getOrCreatePerEntity(
+        materialBgShared,
+        smShaderId ?? '',
+        smMergedEntries.map((e) => extractEntryResourceHandle(e)),
+        'material-shared',
+        createBindGroup,
+        bindGroupCounts,
+      );
+  if (
+    smMaterialHandle !== undefined &&
+    !smHasVideoFields &&
+    materialResourcesResident &&
+    !hasActiveTransmissionBackdrop
+  ) {
     if (materialCacheKey !== undefined) {
       materialBgAssemblyCache.set(materialCacheKey, {
         material: submeshMaterial,

package/src/record/main-pass-sprite-draws.ts

@@ -5,10 +5,12 @@
 import type { World } from '@forgeax/engine-ecs';
 import {
   type BindGroup,
+  type BindGroupEntry,
   type Buffer,
   type RenderPipeline,
   RhiError,
   type RhiRenderPassEncoder,
+  type TextureView,
 } from '@forgeax/engine-rhi';
 import type { Handle, MaterialRenderState } from '@forgeax/engine-types';
 import { GpuBuffer } from '../gpu-resource';
@@ -19,7 +21,6 @@ import {
 } from '../gpu-usage';
 import {
   assembleMaterialWithSkylightEntries,
-  type EmissiveAoBindGroupResources,
   type SkylightBindGroupResources,
 } from '../ibl/skylight-bind-group';
 import type { InstanceBufferCacheEntry } from '../instance-buffer-cache';
@@ -31,7 +32,12 @@ import {
 } from '../pipeline-spec';
 import type { MaterialSnapshot, SpriteInstancesSnapshot } from '../render-system-extract';
 import { worldEntityKey } from './frame-snapshot';
-import { entityHasTransparentSubmesh, residentTextureView } from './main-pass-material';
+import {
+  BUILTIN_USER_REGION_TEXTURE_FIELDS,
+  defaultViewForUserRegionField,
+  entityHasTransparentSubmesh,
+  residentTextureView,
+} from './main-pass-material';
 import {
   extractEntryResourceHandle,
   getOrCreatePerEntity,
@@ -44,6 +50,51 @@ import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-cont
 
 export type { SpriteInstancesSnapshot };
 
+/**
+ * Build the sprite material's Standard user-region from the shared field-order
+ * owner. The sprite shader uses the same Standard material bind-group layout;
+ * keeping this projection derived from the shared list prevents IBL injection
+ * from moving ahead of newly added material texture pairs.
+ */
+export function buildSpritePassBaseMaterialEntries(
+  pipelineState: _InternalRenderPipelineContext['pipelineState'],
+  spriteTexView: TextureView,
+): BindGroupEntry[] {
+  const entries: BindGroupEntry[] = [
+    {
+      binding: 0,
+      resource: {
+        kind: 'buffer' as const,
+        value: {
+          buffer: pipelineState.materialUniformBuffer.buffer,
+          offset: 0,
+          size: STANDARD_PBR_UBO_SIZE,
+        },
+      },
+    },
+  ];
+  for (const [index, field] of BUILTIN_USER_REGION_TEXTURE_FIELDS.entries()) {
+    const view =
+      field === 'baseColorTexture'
+        ? spriteTexView
+        : defaultViewForUserRegionField(field, pipelineState);
+    entries.push(
+      {
+        binding: 1 + index * 2,
+        resource: {
+          kind: 'sampler' as const,
+          value: index === 0 ? pipelineState.nearestSampler : pipelineState.defaultSampler,
+        },
+      },
+      {
+        binding: 2 + index * 2,
+        resource: { kind: 'textureView' as const, value: view },
+      },
+    );
+  }
+  return entries;
+}
+
 /**
  * Build the interleaved sprite instance payload consumed by this record owner.
  * The extract stage validates the two packed arrays before they reach this
@@ -159,6 +210,12 @@ export function recordSpritePass(
     viewBindGroup,
     splitLdrSprite,
   } = c;
+  // The split pass is also used by the no-tone linear-LDR route. That route
+  // keeps transparent draws in the graph-owned rgba16float attachment, so
+  // sprite shaders must use their linear/HDR fragment entry point even though
+  // the camera itself has no tone map enabled.
+  const spriteIsHdr =
+    c.tonemapActive || transparentPassColorFormat(c, pipelineState) === 'rgba16float';
   let geometryPassEnded = false;
   if (splitLdrSprite && (graphPass !== undefined || ldrSpritePassView !== null)) {
     if (graphPass === undefined) {
@@ -253,7 +310,7 @@ export function recordSpritePass(
     const spritePH =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite',
-        /* isHdr */ false,
+        spriteIsHdr,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -273,7 +330,7 @@ export function recordSpritePass(
     const spritePH_withRegion =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite',
-        /* isHdr */ false,
+        spriteIsHdr,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -296,7 +353,6 @@ export function recordSpritePass(
     // present), then fall through to the PBR loop. A PBR-only transparent
     // scene (e.g. a glTF BLEND decal, no sprites) renders regardless of
     // whether sprite.wgsl is in the manifest.
-    const spriteUnavailable = spritePH === null;
     let spriteUnavailableReported = false;
     const reportSpriteUnavailable = (): void => {
       if (spriteUnavailableReported) return;
@@ -316,7 +372,7 @@ export function recordSpritePass(
     const spriteLitPH =
       runtime.getMaterialShaderPipeline?.(
         'forgeax::sprite-lit',
-        /* isHdr */ false,
+        spriteIsHdr,
         spritePremulBlend,
         'triangle-list',
         undefined,
@@ -326,7 +382,6 @@ export function recordSpritePass(
         msaaActive ? 4 : 1,
         transparentPassColorFormat(c) as GPUTextureFormat,
       ) ?? null;
-
     recordSpriteEntityDraws(
       c,
       spritePass,
@@ -335,7 +390,6 @@ export function recordSpritePass(
       spritePH,
       spritePH_withRegion,
       spriteLitPH,
-      spriteUnavailable,
       reportSpriteUnavailable,
     );
 
@@ -397,6 +451,8 @@ function recordSpriteTransparentPbrDraws(
 ): void {
   const { runtime, pipelineState, frameState, bindGroupCounts, validatedOrdered, meshBindGroup } =
     c;
+  const isHdrTarget =
+    c.tonemapActive || transparentPassColorFormat(c, pipelineState) === 'rgba16float';
   let lastPbrSubPipelineHandle: typeof pipelineState.unlitPipeline = null;
   let lastPbrSubVertexBuffer: GpuBuffer | null = null;
   let lastPbrSubIndexBuffer: GpuBuffer | null = null;
@@ -495,7 +551,7 @@ function recordSpriteTransparentPbrDraws(
       const subPipeline =
         runtime.getMaterialShaderPipeline?.(
           smShaderId,
-          /* isHdr */ false,
+          isHdrTarget,
           submeshMaterial.renderState,
           sm.topology,
           entry.mesh.indexFormat,
@@ -546,7 +602,6 @@ function recordSpriteEntityDraws(
   spritePH: RenderPipeline | null,
   spritePH_withRegion: RenderPipeline | null,
   spriteLitPH: RenderPipeline | null,
-  spriteUnavailable: boolean,
   reportSpriteUnavailable: () => void,
 ): void {
   const {
@@ -582,22 +637,18 @@ function recordSpriteEntityDraws(
       const isSpriteShader = sid === 'forgeax::sprite' || sid === 'forgeax::sprite-lit';
       if (!isSpriteShader) continue;
     }
-    // Sprite PSO unavailable (sprite.wgsl absent / still compiling): skip
-    // sprite entities and report once, but do NOT abort the sub-pass — the
-    // PBR transparent loop below is independent of the sprite shader.
-    if (spriteUnavailable) {
-      reportSpriteUnavailable();
-      continue;
-    }
-
     // feat-20260622-chunk-gpu-instancing-sprite-tilemap M1 / w4-record-swap
     // (D-1): fold-bucket non-head member — skip; the bucket head emits one
     // instanced drawIndexed covering all members.
-    if (foldDispatchPlan?.skipIndices.has(i) === true) continue;
+    if (foldDispatchPlan?.skipIndices.has(i) === true) {
+      continue;
+    }
     const foldHeadBucket = foldDispatchPlan?.headBuckets.get(i);
 
     // feat-20260609 M2: skip entities that don't match the pass selector.
-    if (matchedIndices !== null && !matchedIndices.has(spriteEntry.renderableIndex)) continue;
+    if (matchedIndices !== null && !matchedIndices.has(spriteEntry.renderableIndex)) {
+      continue;
+    }
 
     // feat-20260624 M1' / t7: select sprite vs sprite-lit PSO per
     // entity. Both paths share the LDR sub-pass + the same UBO
@@ -629,7 +680,9 @@ function recordSpriteEntityDraws(
       // way fail-safe-skip is the closest the renderer can get to
       // "show nothing visibly wrong" without ending the sprite pass
       // (which would drop remaining sprite entities for the frame).
-      if (entityShaderId === 'forgeax::sprite-lit') {
+      if (entityShaderId === 'forgeax::sprite') {
+        reportSpriteUnavailable();
+      } else if (entityShaderId === 'forgeax::sprite-lit') {
         runtime.errorRegistry.fire(
           new RhiError({
             code: 'shader-compile-failed',
@@ -919,89 +972,13 @@ function recordSpriteEntityDraws(
       const tv = residentTextureView(spriteEntry.world ?? world, store, runtime, spriteTexHandle);
       if (tv !== undefined) spriteTexView = tv as never;
     }
-    const spritePassBaseMaterialEntries = [
-      {
-        binding: 0,
-        resource: {
-          kind: 'buffer' as const,
-          value: {
-            buffer: pipelineState.materialUniformBuffer.buffer,
-            offset: 0,
-            size: STANDARD_PBR_UBO_SIZE,
-          },
-        },
-      },
-      {
-        binding: 1,
-        resource: { kind: 'sampler' as const, value: pipelineState.nearestSampler },
-      },
-      { binding: 2, resource: { kind: 'textureView' as const, value: spriteTexView } },
-      {
-        binding: 3,
-        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-      },
-      {
-        binding: 4,
-        resource: {
-          kind: 'textureView' as const,
-          value: pipelineState.defaultWhiteTextureView,
-        },
-      },
-      {
-        binding: 5,
-        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-      },
-      {
-        binding: 6,
-        resource: {
-          kind: 'textureView' as const,
-          value: pipelineState.defaultNormalTextureView,
-        },
-      },
-      {
-        binding: 7,
-        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-      },
-      {
-        binding: 8,
-        resource: {
-          kind: 'textureView' as const,
-          value: pipelineState.defaultWhiteTextureView,
-        },
-      },
-      {
-        binding: 9,
-        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-      },
-      {
-        binding: 10,
-        resource: {
-          kind: 'textureView' as const,
-          value: pipelineState.defaultWhiteTextureView,
-        },
-      },
-      {
-        binding: 11,
-        resource: { kind: 'sampler' as const, value: pipelineState.defaultSampler },
-      },
-      {
-        binding: 12,
-        resource: {
-          kind: 'textureView' as const,
-          value: pipelineState.defaultWhiteTextureView,
-        },
-      },
-    ];
-    const spritePassEmissiveAo: EmissiveAoBindGroupResources = {
-      emissiveSampler: pipelineState.defaultSampler,
-      emissiveView: pipelineState.defaultWhiteTextureView,
-      occlusionSampler: pipelineState.defaultSampler,
-      occlusionView: pipelineState.defaultWhiteTextureView,
-    };
+    const spritePassBaseMaterialEntries = buildSpritePassBaseMaterialEntries(
+      pipelineState,
+      spriteTexView,
+    );
     const spritePassMergedEntries = assembleMaterialWithSkylightEntries(
       spritePassBaseMaterialEntries,
       skylightResources,
-      spritePassEmissiveAo,
     );
 
     // Sprite-pass material BG cache: keyed on shader id (shared across all