@forgeax/engine-render 0.1.4 → 0.1.6

package/src/record/main-pass.ts

@@ -1,3 +1,4 @@
+import type { World } from '@forgeax/engine-ecs';
 import { probeVideoHighPerfUpload } from '@forgeax/engine-graphics-extras';
 import {
   type BindGroup,
@@ -6,25 +7,28 @@ import {
   type TextureView,
 } from '@forgeax/engine-rhi';
 import type { Handle, PassKind, PassSelector } from '@forgeax/engine-types';
-import { environmentConsumerSnapshot } from '../environment/generation';
-import { isEnvironmentGpuBundle } from '../environment/gpu-bundle';
 import { createHdrpUnifiedBindGroup, getOrCreateHdrpBuffers } from '../hdrp-buffers';
 import { getOrCreateIblCache } from '../ibl/IblPipelineCache';
 import { buildBeginRenderPassDescriptor } from '../pipeline-spec';
-import type { _InternalRenderPipelineContext } from '../render-pipeline-context';
-import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
+import type { RenderRecordPhase } from '../render-contract';
 import type { MaterialSnapshot } from '../render-system-extract';
-import type { RenderRecordPhase } from '../renderer';
 import { recordGeometryDraws } from './main-pass-geometry';
 import {
+  applyMaterialTextureUvScales,
+  applyParamSnapshotToUbo,
   buildPerSubmeshMaterialBg as buildPerSubmeshMaterialBgImpl,
   detectNineSliceScaleTooSmall,
   type PerSubmeshMaterialBgDeps,
   residentTextureView,
-  writeMaterialSnapshotPayload,
+  writePbrMaterialUboPayload,
 } from './main-pass-material';
 import { recordSpritePass } from './main-pass-sprite-draws';
-import { buildMatchedRenderableIndices } from './shadow-pass';
+import type { _InternalRenderPipelineContext } from './render-context';
+import { MATERIAL_PER_ENTITY_STRIDE, STANDARD_PBR_UBO_SIZE } from './render-context';
+import {
+  buildMatchedMaterialHandlesByRenderable,
+  buildMatchedRenderableIndices,
+} from './shadow-pass';
 
 const ZERO_SKYLIGHT_PAYLOAD = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1]);
 
@@ -191,14 +195,20 @@ export function recordMainPass(
   // material uploads + drawIndexed.
 
   // feat-20260609 M2: filter entities by pass selector.
-  let matchedIndices =
+  const matchedIndices =
     selector !== undefined ? buildMatchedRenderableIndices(dispatch, selector) : null;
+  const matchedMaterials =
+    selector !== undefined ? buildMatchedMaterialHandlesByRenderable(dispatch, selector) : null;
 
   if (validatedOrdered.length > 0) {
-    // The dynamic-offset stride is an engine buffer-alignment constraint. The
-    // bind-group range and written bytes below are owned by the derived
-    // material interface and may be smaller than that stride.
-    const MATERIAL_SLICE = MATERIAL_PER_ENTITY_STRIDE;
+    // feat-20260518-pbr-direct-lighting-mvp M5 / w22.10 (D-4 + D-9 +
+    // AC-07 std140): per-entity material slice grew from 32 B (legacy
+    // baseColor:vec4 + metallic + roughness + 8B padding) to 48 B
+    // mirroring the post-w22.10 `Material` WGSL struct field-for-field
+    // (see STANDARD_PBR_UBO_SIZE JSDoc in render-system.ts). The dynamic-
+    // offset stride is MATERIAL_PER_ENTITY_STRIDE; the BindGroup entry's
+    // `size` remains the derived material payload size.
+    const MATERIAL_SLICE = STANDARD_PBR_UBO_SIZE;
     // feat-20260515 M3 / T-M3-05 (research F-6 fix): materialBindGroup now
     // carries 3 entries -- the per-entity material UBO (binding 0,
     // dynamic-offset retained from D-P9), the default sampler (binding 1,
@@ -223,7 +233,7 @@ export function recordMainPass(
     // translation; record consumes the snapshot POD only (charter
     // proposition 5 consistent abstraction; AC-07 reverse-grep gate
     // `scripts/forgeax/check-render-record-no-material-asset-get.mjs`
-    // forbids both the cast pattern and any direct material asset
+    // forbids both the cast pattern and a direct material asset
     // typed-lookup regrowth in this file).
     // bug-20260522-per-entity-material-texture-binding D-1/D-2:
     // the pre-loop `firstMaterial` / `materialTextureView` / `
@@ -259,39 +269,13 @@ export function recordMainPass(
     // 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: unknown; pref: unknown; brdf: unknown } | undefined;
+    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(
-      // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
-      skylightFallback.intensityBuffer as any,
-      0,
-      ZERO_SKYLIGHT_PAYLOAD,
-    );
-    const activeEnvironmentRecord =
-      frameState.environmentGeneration.candidate ?? frameState.environmentGeneration.active;
-    const activeEnvironmentBundle =
-      activeEnvironmentRecord !== undefined &&
-      isEnvironmentGpuBundle(activeEnvironmentRecord.handle)
-        ? activeEnvironmentRecord.handle
-        : undefined;
-    const environmentSunSnapshot = environmentConsumerSnapshot(frameState.environmentGeneration);
-    if (environmentSunSnapshot !== undefined && activeEnvironmentBundle !== undefined) {
-      const sun = environmentSunSnapshot.direct;
-      runtime.device.queue.writeBuffer(
-        // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
-        skylightFallback.intensityBuffer as any,
-        0,
-        new Float32Array([1, sun.color[0] ?? 1, sun.color[1] ?? 1, sun.color[2] ?? 1, 0, 0, 0, 1]),
-      );
-      activeViews = {
-        irr: activeEnvironmentBundle.irradianceView,
-        pref: activeEnvironmentBundle.prefilterView,
-        brdf: skylightFallback.brdfLutView,
-      };
-    } else if (skylight !== undefined && skylightCount >= 1) {
+    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
@@ -302,14 +286,8 @@ export function recordMainPass(
       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(
-        // biome-ignore lint/suspicious/noExplicitAny: opaque Buffer handle
-        skylightFallback.intensityBuffer as any,
-        0,
-        uniformPayload,
-      );
-      // biome-ignore lint/suspicious/noExplicitAny: device is the opaque RhiDevice
-      const cache = getOrCreateIblCache(runtime.device as any);
+      runtime.device.queue.writeBuffer(skylightFallback.intensityBuffer, 0, uniformPayload);
+      const cache = getOrCreateIblCache(runtime.deviceScope);
       if (
         cache.irradianceView !== undefined &&
         cache.prefilterView !== undefined &&
@@ -325,11 +303,11 @@ export function recordMainPass(
     const skylightResources =
       activeViews !== undefined
         ? {
-            irradianceView: activeViews.irr as never,
+            irradianceView: activeViews.irr,
             irradianceSampler: skylightFallback.sampler,
-            prefilterView: activeViews.pref as never,
+            prefilterView: activeViews.pref,
             prefilterSampler: skylightFallback.sampler,
-            brdfLutView: activeViews.brdf as never,
+            brdfLutView: activeViews.brdf,
             brdfLutSampler: skylightFallback.sampler,
             intensityBuffer: skylightFallback.intensityBuffer,
           }
@@ -342,9 +320,25 @@ export function recordMainPass(
             brdfLutSampler: skylightFallback.sampler,
             intensityBuffer: skylightFallback.intensityBuffer,
           };
-    // Per-entity material uploads (D-P9 retained path). The payload is derived
-    // from each material's effective paramSchema; engine-owned resources bind
-    // separately and never add a second layout owner here.
+    // Per-entity material uploads (D-P9 retained path).
+    // feat-20260613 fix-issue-1 (D-8 channelMap split): the payload mirrors
+    // the post-split sidecar paramSchema for default-standard-pbr (14 entries
+    // packed std140 across a 96 B schema tail):
+    //   [0..3]   baseColor          vec4<f32>     (offset 0)
+    //   [4]      metallic           f32           (offset 16)
+    //   [5]      roughness          f32           (offset 20)
+    //   [6]      metallicChannel    f32           (offset 24)
+    //   [7]      roughnessChannel   f32           (offset 28)
+    //   [8]      aoChannel          f32           (offset 32)
+    //   [9]      extraChannel       f32           (offset 36)
+    //   [12..14] emissive           vec3<f32>     (offset 48, vec3 align=16)
+    //   [15]     emissiveIntensity  f32           (offset 60)
+    //   [16]     occlusionStrength  f32           (offset 64)
+    // Channel selectors default to (B,G,R,_) = (2,1,0,0) per glTF 2.0
+    // KHR_materials_pbrSpecularGlossiness ARM packing; the fragment casts
+    // each f32 to u32 at the pick_channel call site. The full 128 B bind window is
+    // overwritten per-entity so unlit entities still produce a deterministic
+    // payload (charter P3 explicit failure: zero-init via fresh ArrayBuffer).
     //
     // Material snapshots are interned by extract-owned identity before this
     // pass. Repeated scene instances therefore share one 256-byte UBO slot;
@@ -372,61 +366,107 @@ export function recordMainPass(
     const buildPerSubmeshMaterialBg = (
       submeshMaterial: MaterialSnapshot,
       entityKey: number,
+      materialWorld: World = world,
     ): BindGroup =>
-      buildPerSubmeshMaterialBgImpl(perSubmeshMaterialBgDeps, submeshMaterial, entityKey);
+      buildPerSubmeshMaterialBgImpl(
+        perSubmeshMaterialBgDeps,
+        submeshMaterial,
+        entityKey,
+        materialWorld,
+      );
 
     const cachedMaterialUboPayload = c.materialUboPayloadCache;
     let materialUboPayload: Uint8Array;
     if (
       cachedMaterialUboPayload?.materialSlots === materialSlots &&
-      cachedMaterialUboPayload.materialSlotCount === materialSlotCount &&
-      cachedMaterialUboPayload.materialResourceEpoch === store.materialResourceEpoch
+      cachedMaterialUboPayload.materialSlotCount === materialSlotCount
     ) {
       materialUboPayload = cachedMaterialUboPayload.payload;
     } else {
       materialUboPayload = new Uint8Array(materialSlotCount * MATERIAL_PER_ENTITY_STRIDE);
-      const invalidMaterialSlots = new Set<number>();
+      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;
-        const payload = writeMaterialSnapshotPayload(
-          mat,
-          MATERIAL_PER_ENTITY_STRIDE,
-          runtime.paramSchemaProjectionCensus,
-        );
-        if (!payload.ok) {
-          invalidMaterialSlots.add(materialSlot);
-          runtime.errorRegistry.fire(payload.error as never);
-          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 baseColorTextureHandle = mat.baseColorTexture as
-          | Handle<'TextureAsset', 'shared'>
-          | undefined;
-        if (baseColorTextureHandle !== undefined) {
-          const baseColorView = residentTextureView(world, store, runtime, baseColorTextureHandle);
-          if (baseColorView === undefined) {
-            const rawId = baseColorTextureHandle as unknown as number;
-            if (!frameState.warnedMissingBaseColorTextureHandles.has(rawId)) {
-              frameState.warnedMissingBaseColorTextureHandles.add(rawId);
-              console.warn(
-                `[forgeax] baseColor texture ${rawId} missing GPU view, skipping draw (shader=${materialShaderId ?? '<none>'} entityIndex=${entry.renderableIndex})`,
+        const schema =
+          mat.materialParamSchema ??
+          (materialShaderId !== undefined ? runtime.getParamSchema?.(materialShaderId) : undefined);
+        applyParamSnapshotToUbo(slotPayloadF32, schema, 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;
             }
-            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 }); the affected material draw is skipped until then',
-                detail: { assetHandle: rawId },
-              }),
-            );
-            invalidMaterialSlots.add(materialSlot);
-            continue;
           }
         }
-        materialUboPayload.set(payload.value, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
+
+        materialUboPayload.set(slotPayload, materialSlot * MATERIAL_PER_ENTITY_STRIDE);
       }
 
       // Material UBO slots can share one snapshot identity, but nine-slice
@@ -455,28 +495,11 @@ export function recordMainPass(
           runtime.metrics,
         );
       }
-      if (invalidMaterialSlots.size === 0) {
-        c.materialUboPayloadCache = {
-          materialSlots,
-          materialSlotCount,
-          materialResourceEpoch: store.materialResourceEpoch,
-          payload: materialUboPayload,
-        };
-      }
-
-      const recordableIndices = new Set<number>();
-      for (let index = 0; index < validatedOrdered.length; index += 1) {
-        const entry = validatedOrdered[index];
-        if (entry === undefined) continue;
-        const slots = materialSlotIndices[index] ?? [];
-        if (slots.some((slot) => invalidMaterialSlots.has(slot))) continue;
-        if (matchedIndices === null || matchedIndices.has(entry.renderableIndex)) {
-          recordableIndices.add(entry.renderableIndex);
-        }
-      }
-      if (invalidMaterialSlots.size > 0 || matchedIndices !== null) {
-        matchedIndices = recordableIndices;
-      }
+      c.materialUboPayloadCache = {
+        materialSlots,
+        materialSlotCount,
+        payload: materialUboPayload,
+      };
     }
 
     // All material slots are staged before the first geometry draw. One
@@ -489,7 +512,6 @@ export function recordMainPass(
       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:
@@ -504,14 +526,17 @@ export function recordMainPass(
       preparedMaterialBindGroups[materialSlot] = buildPerSubmeshMaterialBg(
         material,
         owner.source.entityKey,
+        owner.world ?? world,
       );
     }
     const resolveMaterialBindGroup = (
       materialSlot: number,
       material: MaterialSnapshot,
       entityKey: number,
+      materialWorld: World = world,
     ): BindGroup =>
-      preparedMaterialBindGroups[materialSlot] ?? buildPerSubmeshMaterialBg(material, entityKey);
+      preparedMaterialBindGroups[materialSlot] ??
+      buildPerSubmeshMaterialBg(material, entityKey, materialWorld);
 
     pass.setBindGroup(0, viewBindGroup as BindGroup);
 
@@ -521,33 +546,27 @@ export function recordMainPass(
     // most entities share BUILTIN_CUBE + unlit). Initial nulls force the
     // first iteration to bind unconditionally.
     // M-3 / w12: vertexBuffer/indexBuffer state locals migrate to GpuBuffer.
-    if (passKind !== 'forward' || !c.gpuDrivenOwnsAllForwardItems) {
-      const recordGeometry = (): void => {
-        recordGeometryDraws(
-          c,
-          pass,
-          matchedIndices,
-          materialSlotIndices,
-          sampleCount,
-          meshGroup2,
-          resolveMaterialBindGroup,
-          passKind,
-        );
-      };
-      if (c.profilePhase === undefined) {
-        recordGeometry();
-      } else {
-        const passName =
-          passKind === 'deferred'
-            ? 'g-buffer'
-            : passKind === 'temporal'
-              ? 'scene-temporal'
-              : 'forward';
-        c.profilePhase(
-          `record/graph-execute/${passName}/geometry-loop` as RenderRecordPhase,
-          recordGeometry,
-        );
-      }
+    const recordGeometry = (): void => {
+      recordGeometryDraws(
+        c,
+        pass,
+        matchedMaterials,
+        materialSlotIndices,
+        sampleCount,
+        meshGroup2,
+        meshBindGroup,
+        resolveMaterialBindGroup,
+        passKind,
+      );
+    };
+    if (c.profilePhase === undefined) {
+      recordGeometry();
+    } else {
+      const passName = passKind === 'deferred' ? 'g-buffer' : 'forward';
+      c.profilePhase(
+        `record/graph-execute/${passName}/geometry-loop` as RenderRecordPhase,
+        recordGeometry,
+      );
     }
 
     // D-2: LDR sprite pass. Runs after the geometry pass when there are