@forgeax/engine-render 0.1.24 → 0.1.26

package/src/record/main-pass.ts

@@ -6,7 +6,7 @@ import {
   type RhiRenderPassEncoder,
   type TextureView,
 } from '@forgeax/engine-rhi';
-import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
+import type { PassKind, PassSelector } from '@forgeax/engine-types';
 import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import type { SkylightBindGroupResources } from '../ibl/skylight-bind-group';
@@ -19,20 +19,17 @@ import { resolveReflectionProbeBinding } from './frame-lighting';
 import { getOpaqueResourceIdentity } from './frame-snapshot';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
-  applyMaterialTextureUvScales,
-  applyParamSnapshotToUbo,
   buildPerSubmeshMaterialBg as buildPerSubmeshMaterialBgImpl,
-  detectNineSliceScaleTooSmall,
   type PerSubmeshMaterialBgDeps,
-  residentTextureView,
-  writePbrMaterialUboPayload,
+  prepareMaterialSkylight,
 } from './main-pass-material';
 import { recordSpritePass } from './main-pass-sprite-draws';
 import type { _InternalRenderPipelineContext } from './render-context';
-import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
+import { STANDARD_PBR_UBO_SIZE } from './render-context';
 import {
   buildMatchedMaterialHandlesByRenderable,
   buildMatchedRenderableIndices,
+  filterDispatchBySelector,
 } from './shadow-pass';
 
 export function standardReflectionProbeIndex(
@@ -41,8 +38,6 @@ export function standardReflectionProbeIndex(
   return resolveReflectionProbeBinding(selection).probeIndex;
 }
 
-const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
-
 function materialDiagnosticsEnabled(): boolean {
   if (typeof globalThis !== 'object' || globalThis === null || !('process' in globalThis)) {
     return false;
@@ -138,8 +133,6 @@ export function recordMainPass(
     meshBindGroup,
     frameState,
     bindGroupCounts,
-    skylight,
-    skylightCount,
     skyboxActive,
     splitLdrSprite,
     msaaActive,
@@ -289,6 +282,13 @@ export function recordMainPass(
   const selectorMatchedMaterials =
     selector !== undefined ? buildMatchedMaterialHandlesByRenderable(dispatch, selector) : null;
   const matchedMaterials = matchedMaterialsForRecordMode(c, selectorMatchedMaterials, recordMode);
+  const selectedDispatch =
+    dispatch.length === 0
+      ? undefined
+      : filterDispatchBySelector(
+          dispatch,
+          selector ?? { LightMode: [passKind === 'deferred' ? 'Deferred' : 'Forward'] },
+        );
   const recordContext =
     recordMode === undefined
       ? c
@@ -355,78 +355,7 @@ export function recordMainPass(
     // (single `skylightResources` resolved once below); only the first 7
     // material entries are rebuilt per-entity with the correct
     // per-entity textureView at binding=2.
-    const skylightFallback = pipelineState.skylightFallback;
-    if (skylightFallback === null) {
-      throw new RhiError({
-        code: 'webgpu-runtime-error',
-        expected: 'pipelineState.skylightFallback != null when PBR pipeline is active',
-        hint: 'createRenderer must allocate skylightFallback alongside the PBR pipeline (D-5 round-4)',
-      });
-    }
-    // feat-20260520-skylight-ibl-cubemap M4 round-4 / t60 (D-5 round-4):
-    // select active vs fallback Skylight resources by `skylightCount` from
-    // the extract stage. Active path reaches into the per-device
-    // `IblPipelineCache` slots (irradianceView / prefilterView / brdfLutView)
-    // populated by the internal equirect-to-cubemap projection; fallback uses the
-    // 1x1-zero identity bundle that converges ambient to 0 (D-4 physical
-    // convergence -- no `if (hasSkylight)` shader branch).
-    // The samplers are reused from `skylightFallback.sampler` for both
-    // paths (linear / clamp-to-edge is correct for IBL cube + 2D LUT
-    // sampling either way). The intensity uniform is rewritten per-frame
-    // when active so `sampleIblSpecular * intensity` carries the user's
-    // Skylight.intensity value; fallback keeps intensity=0 (createSkylightFallback
-    // seed) so ambient = 0 even when the same buffer is shared.
-    let activeViews: { irr: TextureView; pref: TextureView; brdf: TextureView } | undefined;
-    // Per-frame Skylight uniform: std140 32 B = [intensity, colorR, colorG,
-    // colorB, rotation quaternion]. Default to all-zero so a transition from "has Skylight" ->
-    // "no Skylight" does not leak the prior frame's ambient (intensity 0
-    // muzzles everything, including the white fallback irradiance cube).
-    runtime.device.queue.writeBuffer(skylightFallback.intensityBuffer, 0, ZERO_SKYLIGHT_PAYLOAD);
-    if (skylight !== undefined && skylightCount >= 1) {
-      // A Skylight exists. Write its intensity + color regardless of whether
-      // a cubemap is bound: with a cubemap the IBL views below light the
-      // ambient; WITHOUT one, the white fallback irradiance cube + this color
-      // give an instant solid-color ambient (downstream integration #4) with
-      // no async precompute. The white fallback only contributes when a
-      // Skylight is present because the zero-payload above sets intensity 0
-      // when no Skylight exists.
-      const [cr, cg, cb] = skylight.color;
-      const [qx, qy, qz, qw] = skylight.rotation;
-      const uniformPayload = new Float32Array([skylight.intensity, cr, cg, cb, qx, qy, qz, qw]);
-      runtime.device.queue.writeBuffer(skylightFallback.intensityBuffer, 0, uniformPayload);
-      const cache = getOrCreateIblCache(runtime.deviceScope);
-      if (
-        cache.irradianceView !== undefined &&
-        cache.prefilterView !== undefined &&
-        cache.brdfLutView !== undefined
-      ) {
-        activeViews = {
-          irr: cache.irradianceView,
-          pref: cache.prefilterView,
-          brdf: cache.brdfLutView,
-        };
-      }
-    }
-    const skylightResources =
-      activeViews !== undefined
-        ? {
-            irradianceView: activeViews.irr,
-            irradianceSampler: skylightFallback.sampler,
-            prefilterView: activeViews.pref,
-            prefilterSampler: skylightFallback.sampler,
-            brdfLutView: activeViews.brdf,
-            brdfLutSampler: skylightFallback.sampler,
-            intensityBuffer: skylightFallback.intensityBuffer,
-          }
-        : {
-            irradianceView: skylightFallback.irradianceView,
-            irradianceSampler: skylightFallback.sampler,
-            prefilterView: skylightFallback.prefilterView,
-            prefilterSampler: skylightFallback.sampler,
-            brdfLutView: skylightFallback.brdfLutView,
-            brdfLutSampler: skylightFallback.sampler,
-            intensityBuffer: skylightFallback.intensityBuffer,
-          };
+    const { skylightResources, activeViews } = prepareMaterialSkylight(c);
     if (materialDiagnosticsEnabled()) {
       const activeCache =
         activeViews === undefined ? undefined : getOrCreateIblCache(runtime.deviceScope);
@@ -438,7 +367,9 @@ export function recordMainPass(
         deviceGeneration: runtime.deviceScope.generation,
         active: activeViews === undefined ? 'fallback' : 'active',
         cache: {
-          identity: getOpaqueResourceIdentity((activeCache ?? skylightFallback) as object),
+          identity: getOpaqueResourceIdentity(
+            (activeCache ?? pipelineState.skylightFallback) as object,
+          ),
           generation: runtime.deviceScope.generation,
           prefilterMipCount: prefilterViewMipCount,
           prefilterViewMipCount,
@@ -563,173 +494,16 @@ export function recordMainPass(
       submeshMaterial: MaterialSnapshot,
       entityKey: number,
       materialWorld: World = world,
+      materialShaderId: string | undefined = submeshMaterial.materialShaderId,
     ): BindGroup =>
       buildPerSubmeshMaterialBgImpl(
         perSubmeshMaterialBgDeps,
         submeshMaterial,
         entityKey,
         materialWorld,
+        materialShaderId,
       );
 
-    const cachedMaterialUboPayload = c.materialUboPayloadCache;
-    let materialUboPayload: Uint8Array;
-    if (
-      cachedMaterialUboPayload?.materialSlots === materialSlots &&
-      cachedMaterialUboPayload.materialSlotCount === materialSlotCount
-    ) {
-      materialUboPayload = cachedMaterialUboPayload.payload;
-    } else {
-      materialUboPayload = new Uint8Array(materialSlotCount * MATERIAL_PER_ENTITY_STRIDE);
-      const slotPayload = new Uint8Array(STANDARD_PBR_UBO_SIZE);
-      const slotPayloadF32 = new Float32Array(
-        slotPayload.buffer,
-        slotPayload.byteOffset,
-        slotPayload.byteLength / 4,
-      );
-      for (let materialSlot = 0; materialSlot < materialSlots.length; materialSlot += 1) {
-        const mat = materialSlots[materialSlot];
-        const entry = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
-        if (mat === undefined || entry === undefined) continue;
-
-        // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13 (D-2):
-        // single unified Material UBO write path. Sprite materials now flow
-        // through the same `buildPbrMaterialUboPayload` baseline +
-        // `applyParamSnapshotToUbo` generic std140 overlay every other
-        // paramSchema-driven material uses. Extract folds the sprite-specific
-        // user inputs into the UBO-aligned paramSnapshot vec4 entries
-        // (colorTint / region / pivotAndSize / slicesAndMode); the writer
-        // walks `derive(paramSchema).uboLayout.entries` and writes each at
-        // its std140 offset. The legacy sprite-specific UBO builder + the
-        // sprite-vs-PBR branch are gone (AC-03).
-        writePbrMaterialUboPayload(slotPayloadF32, mat);
-        // Schema-driven paramSnapshot overlay generalised in feat-20260625
-        // M1 / w3: the writer walks `derive(paramSchema).uboLayout.entries`
-        // and writes each numeric field at its std140 offset (plan-strategy
-        // section 2 D-2). The engine's stock PBR material ships
-        // `paramSnapshot: undefined`, so this is a no-op on the default
-        // PBR path -- the explicit field writes in buildPbrMaterialUboPayload
-        // already cover every byte. User shaders carrying a paramSnapshot
-        // (including the post-ablation sprite path) get their fields
-        // written at the derive-computed offsets; R-H gate keeps the
-        // helper snapshot-only, no asset get.
-        const materialShaderId = mat.materialShaderId;
-        const schema =
-          mat.materialParamSchema ??
-          (materialShaderId !== undefined ? runtime.getParamSchema?.(materialShaderId) : undefined);
-        applyParamSnapshotToUbo(slotPayloadF32, schema, mat.paramSnapshot);
-        const processValue = (
-          globalThis as {
-            process?: { env?: Record<string, string | undefined> };
-          }
-        ).process;
-        if (
-          processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
-          (materialShaderId === 'forgeax::default-standard-pbr' ||
-            materialShaderId === 'forgeax::pbr-skin')
-        ) {
-          console.error(
-            `[render-material] UBO receipt: ${JSON.stringify({
-              entityIndex: entry.renderableIndex,
-              materialHandle: mat.materialHandle,
-              materialShaderId,
-              clearcoat: slotPayloadF32[32],
-              clearcoatRoughness: slotPayloadF32[33],
-              clearcoatNormalScale: slotPayloadF32[34],
-              paramSnapshot: mat.paramSnapshot,
-            })}`,
-          );
-        }
-        applyMaterialTextureUvScales(slotPayloadF32, mat, world);
-        // Missing-texture detection: structural debug-pink fallback overrides
-        // the baseColor/colorTint slot when a bound baseColorTexture handle
-        // resolves to no GPU view. Runs for every textured material path
-        // (sprite / sprite-lit / standard-pbr / pbr-skin / unlit) — the bound
-        // texture would otherwise silently fall back to the 1x1 white view in
-        // the per-submesh BG (main-pass-material.ts), rendering flat with no
-        // warn / RhiError. Mirroring the telemetry here makes a missing/failed
-        // GLB texture immediately diagnosable instead of a silent flat render
-        // (feat-future-pbr-missing-texture-fallback-explicit; feedback
-        // 2026-07-04-glb-pbr-textures-not-applied-flat-render).
-        //
-        // Reads only `mat.baseColorTexture` + the GPU view registry (plan R-H
-        // gate: no asset.get<MaterialAsset> reach-back). The debug-pink write
-        // lands on f32[0..2], which is baseColor.rgb for the PBR/skin UBO and
-        // colorTint.rgb for the sprite UBO — same offset, so one override
-        // covers both.
-        {
-          const matHandleRaw = mat.baseColorTexture as Handle<'TextureAsset', 'shared'> | undefined;
-          if (matHandleRaw !== undefined) {
-            const view = residentTextureView(entry.world ?? world, store, runtime, matHandleRaw);
-            if (view === undefined) {
-              const rawId: number = matHandleRaw;
-              if (!frameState.warnedMissingBaseColorTextureHandles.has(rawId)) {
-                frameState.warnedMissingBaseColorTextureHandles.add(rawId);
-                console.warn(
-                  `[forgeax] baseColor texture ${rawId} missing GPU view, rendering debug pink (shader=${materialShaderId ?? '<none>'} entityIndex=${entry.renderableIndex})`,
-                );
-              }
-              runtime.errorRegistry.fire(
-                new RhiError({
-                  code: 'asset-not-registered',
-                  expected: 'material baseColor TextureAsset uploaded to GPU',
-                  hint: 'register + uploadTexture the baseColor texture before draw([world], { cameraOwner: 0, resourceOwner: 0 }); rendering falls back to debug pink until then',
-                  detail: { assetHandle: rawId },
-                }),
-              );
-              // Debug pink override on slot 0 baseColor/colorTint.rgb (alpha preserved).
-              slotPayloadF32[0] = 1.0;
-              slotPayloadF32[1] = 0.4;
-              slotPayloadF32[2] = 0.7;
-            }
-          }
-        }
-
-        materialUboPayload.set(slotPayload, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
-      }
-
-      // Material UBO slots can share one snapshot identity, but nine-slice
-      // validity depends on each entity's transform. Preserve diagnostics per
-      // renderable instead of inheriting the first owner of a shared slot.
-      for (const entry of validatedOrdered) {
-        const mat = entry.source.material;
-        const materialShaderId = mat.materialShaderId;
-        if (materialShaderId !== 'forgeax::sprite' && materialShaderId !== 'forgeax::sprite-lit')
-          continue;
-        const slicesAndMode = mat.paramSnapshot?.slicesAndMode as readonly number[] | undefined;
-        if (slicesAndMode === undefined || slicesAndMode.length < 4) continue;
-        const slicesArr: readonly [number, number, number, number] = [
-          slicesAndMode[0] ?? 0,
-          slicesAndMode[1] ?? 0,
-          slicesAndMode[2] ?? 0,
-          slicesAndMode[3] ?? 0,
-        ];
-        if (slicesArr[0] === 0 && slicesArr[1] === 0 && slicesArr[2] === 0 && slicesArr[3] === 0)
-          continue;
-        detectNineSliceScaleTooSmall(
-          entry.source.transform.world,
-          slicesArr,
-          entry.renderableIndex,
-          frameState.warnedNineSliceScaleEntities,
-          runtime.metrics,
-        );
-      }
-      c.materialUboPayloadCache = {
-        materialSlots,
-        materialSlotCount,
-        payload: materialUboPayload,
-      };
-    }
-
-    // All material slots are staged before the first geometry draw. One
-    // stride-shaped upload preserves every dynamic offset while avoiding one
-    // queue call per material; the RHI still validates alignment and bounds at
-    // this single owner-level write boundary.
-    const materialUboUpload = runtime.device.queue.writeBuffer(
-      pipelineState.materialUniformBuffer.buffer,
-      0,
-      materialUboPayload,
-    );
-    if (!materialUboUpload.ok) throw materialUboUpload.error;
     // Static material resources are a property of the frame-local material
     // slot, not of each submesh draw. Resolve them once here so the geometry
     // loop only selects a prepared binding. Video fields remain entity-bound:
@@ -752,11 +526,13 @@ export function recordMainPass(
       material: MaterialSnapshot,
       entityKey: number,
       materialWorld: World = world,
+      materialShaderId: string | undefined = material.materialShaderId,
     ): BindGroup =>
-      material.materialShaderId !== POINTS_LINES_MATERIAL_SHADER_ID
+      materialShaderId === material.materialShaderId &&
+      materialShaderId !== POINTS_LINES_MATERIAL_SHADER_ID
         ? (preparedMaterialBindGroups[materialSlot] ??
-          buildPerSubmeshMaterialBg(material, entityKey, materialWorld))
-        : buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
+          buildPerSubmeshMaterialBg(material, entityKey, materialWorld, materialShaderId))
+        : buildPerSubmeshMaterialBg(material, entityKey, materialWorld, materialShaderId);
 
     pass.setBindGroup(0, viewBindGroup as BindGroup, [viewBindGroupDynamicOffset, 0]);
 
@@ -777,6 +553,7 @@ export function recordMainPass(
         meshBindGroup,
         resolveMaterialBindGroup,
         passKind,
+        selectedDispatch,
       );
     };
     if (c.profilePhase === undefined) {
@@ -808,6 +585,7 @@ export function recordMainPass(
         resolveMaterialBindGroup,
         skylightResources,
         graphPass,
+        selectedDispatch,
       );
     }
   } // end if (validatedOrdered.length > 0) -- Case E falls through to pass.end()

package/src/record/material-uniforms.ts

@@ -0,0 +1,186 @@
+import { RhiError } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import {
+  applyMaterialTextureUvScales,
+  applyParamSnapshotToUbo,
+  detectNineSliceScaleTooSmall,
+  residentTextureView,
+  writePbrMaterialUboPayload,
+} from './main-pass-material';
+import type { _InternalRenderPipelineContext } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
+
+/** Stage the root parameter storage before any shadow or color pass consumes it. */
+export function uploadMaterialUniforms(c: _InternalRenderPipelineContext): void {
+  const {
+    runtime,
+    world,
+    store,
+    pipelineState,
+    validatedOrdered,
+    frameState,
+    materialSlots,
+    materialSlotOwners,
+    materialSlotCount,
+  } = c;
+  if (materialSlotCount === 0) return;
+  const cachedMaterialUboPayload = c.materialUboPayloadCache;
+  let materialUboPayload: Uint8Array;
+  if (
+    cachedMaterialUboPayload?.materialSlots === materialSlots &&
+    cachedMaterialUboPayload.materialSlotCount === materialSlotCount
+  ) {
+    materialUboPayload = cachedMaterialUboPayload.payload;
+  } else {
+    materialUboPayload = new Uint8Array(materialSlotCount * MATERIAL_PER_ENTITY_STRIDE);
+    const slotPayload = new Uint8Array(STANDARD_PBR_UBO_SIZE);
+    const slotPayloadF32 = new Float32Array(
+      slotPayload.buffer,
+      slotPayload.byteOffset,
+      slotPayload.byteLength / 4,
+    );
+    for (let materialSlot = 0; materialSlot < materialSlots.length; materialSlot += 1) {
+      const mat = materialSlots[materialSlot];
+      const entry = validatedOrdered[materialSlotOwners[materialSlot] ?? -1];
+      if (mat === undefined || entry === undefined) continue;
+
+      // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13 (D-2):
+      // single unified Material UBO write path. Sprite materials now flow
+      // through the same `buildPbrMaterialUboPayload` baseline +
+      // `applyParamSnapshotToUbo` generic std140 overlay every other
+      // paramSchema-driven material uses. Extract folds the sprite-specific
+      // user inputs into the UBO-aligned paramSnapshot vec4 entries
+      // (colorTint / region / pivotAndSize / slicesAndMode); the writer
+      // walks `derive(paramSchema).uboLayout.entries` and writes each at
+      // its std140 offset. The legacy sprite-specific UBO builder + the
+      // sprite-vs-PBR branch are gone (AC-03).
+      writePbrMaterialUboPayload(slotPayloadF32, mat);
+      // Schema-driven paramSnapshot overlay generalised in feat-20260625
+      // M1 / w3: the writer walks `derive(paramSchema).uboLayout.entries`
+      // and writes each numeric field at its std140 offset (plan-strategy
+      // section 2 D-2). The engine's stock PBR material ships
+      // `paramSnapshot: undefined`, so this is a no-op on the default
+      // PBR path -- the explicit field writes in buildPbrMaterialUboPayload
+      // already cover every byte. User shaders carrying a paramSnapshot
+      // (including the post-ablation sprite path) get their fields
+      // written at the derive-computed offsets; R-H gate keeps the
+      // helper snapshot-only, no asset get.
+      const materialShaderId = mat.materialShaderId;
+      const schema =
+        mat.materialParamSchema ??
+        (materialShaderId !== undefined ? runtime.getParamSchema?.(materialShaderId) : undefined);
+      applyParamSnapshotToUbo(slotPayloadF32, schema, mat.paramSnapshot);
+      const processValue = (
+        globalThis as {
+          process?: { env?: Record<string, string | undefined> };
+        }
+      ).process;
+      if (
+        processValue?.env?.FORGEAX_MATERIAL_PIPELINE_DIAGNOSTICS === '1' &&
+        (materialShaderId === 'forgeax::default-standard-pbr' ||
+          materialShaderId === 'forgeax::pbr-skin')
+      ) {
+        console.error(
+          `[render-material] UBO receipt: ${JSON.stringify({
+            entityIndex: entry.renderableIndex,
+            materialHandle: mat.materialHandle,
+            materialShaderId,
+            clearcoat: slotPayloadF32[32],
+            clearcoatRoughness: slotPayloadF32[33],
+            clearcoatNormalScale: slotPayloadF32[34],
+            paramSnapshot: mat.paramSnapshot,
+          })}`,
+        );
+      }
+      applyMaterialTextureUvScales(slotPayloadF32, mat, world);
+      // Missing-texture detection: structural debug-pink fallback overrides
+      // the baseColor/colorTint slot when a bound baseColorTexture handle
+      // resolves to no GPU view. Runs for every textured material path
+      // (sprite / sprite-lit / standard-pbr / pbr-skin / unlit) — the bound
+      // texture would otherwise silently fall back to the 1x1 white view in
+      // the per-submesh BG (main-pass-material.ts), rendering flat with no
+      // warn / RhiError. Mirroring the telemetry here makes a missing/failed
+      // GLB texture immediately diagnosable instead of a silent flat render
+      // (feat-future-pbr-missing-texture-fallback-explicit; feedback
+      // 2026-07-04-glb-pbr-textures-not-applied-flat-render).
+      //
+      // Reads only `mat.baseColorTexture` + the GPU view registry (plan R-H
+      // gate: no asset.get<MaterialAsset> reach-back). The debug-pink write
+      // lands on f32[0..2], which is baseColor.rgb for the PBR/skin UBO and
+      // colorTint.rgb for the sprite UBO — same offset, so one override
+      // covers both.
+      {
+        const matHandleRaw = mat.baseColorTexture as Handle<'TextureAsset', 'shared'> | undefined;
+        if (matHandleRaw !== undefined) {
+          const view = residentTextureView(entry.world ?? world, store, runtime, matHandleRaw);
+          if (view === undefined) {
+            const rawId: number = matHandleRaw;
+            if (!frameState.warnedMissingBaseColorTextureHandles.has(rawId)) {
+              frameState.warnedMissingBaseColorTextureHandles.add(rawId);
+              console.warn(
+                `[forgeax] baseColor texture ${rawId} missing GPU view, rendering debug pink (shader=${materialShaderId ?? '<none>'} entityIndex=${entry.renderableIndex})`,
+              );
+            }
+            runtime.errorRegistry.fire(
+              new RhiError({
+                code: 'asset-not-registered',
+                expected: 'material baseColor TextureAsset uploaded to GPU',
+                hint: 'register + uploadTexture the baseColor texture before draw([world], { cameraOwner: 0, resourceOwner: 0 }); rendering falls back to debug pink until then',
+                detail: { assetHandle: rawId },
+              }),
+            );
+            // Debug pink override on slot 0 baseColor/colorTint.rgb (alpha preserved).
+            slotPayloadF32[0] = 1.0;
+            slotPayloadF32[1] = 0.4;
+            slotPayloadF32[2] = 0.7;
+          }
+        }
+      }
+
+      materialUboPayload.set(slotPayload, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
+    }
+
+    // Material UBO slots can share one snapshot identity, but nine-slice
+    // validity depends on each entity's transform. Preserve diagnostics per
+    // renderable instead of inheriting the first owner of a shared slot.
+    for (const entry of validatedOrdered) {
+      const mat = entry.source.material;
+      const materialShaderId = mat.materialShaderId;
+      if (materialShaderId !== 'forgeax::sprite' && materialShaderId !== 'forgeax::sprite-lit')
+        continue;
+      const slicesAndMode = mat.paramSnapshot?.slicesAndMode as readonly number[] | undefined;
+      if (slicesAndMode === undefined || slicesAndMode.length < 4) continue;
+      const slicesArr: readonly [number, number, number, number] = [
+        slicesAndMode[0] ?? 0,
+        slicesAndMode[1] ?? 0,
+        slicesAndMode[2] ?? 0,
+        slicesAndMode[3] ?? 0,
+      ];
+      if (slicesArr[0] === 0 && slicesArr[1] === 0 && slicesArr[2] === 0 && slicesArr[3] === 0)
+        continue;
+      detectNineSliceScaleTooSmall(
+        entry.source.transform.world,
+        slicesArr,
+        entry.renderableIndex,
+        frameState.warnedNineSliceScaleEntities,
+        runtime.metrics,
+      );
+    }
+    c.materialUboPayloadCache = {
+      materialSlots,
+      materialSlotCount,
+      payload: materialUboPayload,
+    };
+  }
+
+  // All material slots are staged before the first geometry draw. One
+  // stride-shaped upload preserves every dynamic offset while avoiding one
+  // queue call per material; the RHI still validates alignment and bounds at
+  // this single owner-level write boundary.
+  const materialUboUpload = runtime.device.queue.writeBuffer(
+    pipelineState.materialUniformBuffer.buffer,
+    0,
+    materialUboPayload,
+  );
+  if (!materialUboUpload.ok) throw materialUboUpload.error;
+}

package/src/record/render-context.ts

@@ -26,6 +26,7 @@ import {
   type MaterialShaderArtifact,
 } from '@forgeax/engine-shader';
 import type {
+  MaterialAsset,
   MaterialRenderState,
   ParamSchemaEntry,
   PassKind,
@@ -155,6 +156,9 @@ export interface RenderSystemRuntime {
   readonly errorRegistry: RhiErrorListenerRegistry;
   readonly debugOverlay?: RenderDebugOverlay | undefined;
   readonly healthRegistry: HealthListenerRegistry;
+  readonly getMaterialProjectionForPayload?: (
+    material: MaterialAsset,
+  ) => MaterialRenderProjection | undefined;
   readonly getMaterialProjection?: (materialGuid: string) => MaterialRenderProjection | undefined;
   readonly getMaterialArtifact?: (specializationKey: string) => MaterialRuntimeArtifact | undefined;
   /** Producer-owned cooked Standard PBR artifact used by GPU-driven projection. */
@@ -179,6 +183,8 @@ export interface RenderSystemRuntime {
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    fragmentEntry?: string,
   ) => RhiRenderPipeline | null;
   readonly getMaterialShaderPipelineEntry?: (
     materialShaderId: string,
@@ -198,6 +204,8 @@ export interface RenderSystemRuntime {
     shaderModuleMode?: RenderFeatureShaderModuleMode,
     layoutKindOverride?: 'pbr' | 'pbr-skin',
     additionalColorFormats?: readonly GPUTextureFormat[],
+    vertexEntry?: string,
+    fragmentEntry?: string,
   ) => MaterialShaderPipelineEntry | null;
   /** Reflection-derived UV count included in the material PipelineSpec cache key. */
   readonly getMaterialShaderUvSetCount?: (materialShaderId: string) => number | undefined;