@forgeax/engine-render 0.1.24 → 0.1.26

package/src/render-system-extract-tail.ts

@@ -15,6 +15,7 @@ import {
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
 import { box3, frustum, type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { MaterialCookProgramContext } from '@forgeax/engine-pack/material-cook';
 import { RhiError } from '@forgeax/engine-rhi';
 import { GlobalTransform, MorphWeights, Transform } from '@forgeax/engine-scene';
 import type { MaterialShaderArtifact } from '@forgeax/engine-shader';
@@ -88,7 +89,8 @@ import type {
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
 import type { GpuDrivenGeometryReceipt } from './gpu-driven/prepared-draw';
-import { deriveInstancesUnionBounds } from './instances-derived-bounds';
+import type { InstanceProjectionStore } from './instances';
+import { deriveInstancesUnionBounds, fingerprintNumericArray } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
   type MeshMaterialBindingSource,
@@ -147,6 +149,7 @@ import {
   materialColorParameterSchema,
   materialNormalScale,
   materialParametersToParamSchema,
+  materialProgramKeysForMaterial,
   materialTextureFields,
   materialTextureRef,
   pipelineRenderState,
@@ -156,7 +159,7 @@ import {
   readStablePersistentMaterialSnapshot,
   resolveMaterialSnapshot,
   resolveVideoFieldHandle,
-  runtimeMaterialShaderId,
+  runtimeMaterialShaderIdForMaterial,
   Severity,
   selectCameraRoles,
   selectFogFrame,
@@ -173,11 +176,15 @@ export function extractFrames(
   pipelineState?: ExtractPipelineSurface | null,
   materialSnapshotCachesByWorld?: MaterialSnapshotCachesByWorld,
   options: {
+    readonly materialContext?: MaterialCookProgramContext;
     readonly cull?: 'normal' | 'none';
     readonly renderables?: 'full' | 'none';
+    readonly renderableEntitiesByWorld?: readonly (ReadonlySet<number> | undefined)[];
+    readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
     ) => MaterialShaderArtifact | undefined;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -247,11 +254,21 @@ export function extractFrames(
                   return cache;
                 })(),
             }),
+        ...(options.materialContext === undefined
+          ? {}
+          : { materialContext: options.materialContext }),
         cull: options.cull === 'none' ? 'none' : isCameraOwner ? 'self' : 'external',
         renderables: options.renderables ?? 'full',
+        ...(options.renderableEntitiesByWorld?.[wi] === undefined
+          ? {}
+          : { renderableEntities: options.renderableEntitiesByWorld[wi] }),
+        retainHidden: options.retainHidden ?? false,
         ...(options.getMaterialShaderArtifact === undefined
           ? {}
           : { getMaterialShaderArtifact: options.getMaterialShaderArtifact }),
+        ...(options.instanceCollections === undefined
+          ? {}
+          : { instanceCollections: options.instanceCollections }),
         ...(cameraOwnerFrame === undefined ? {} : { cullCameras: cameraOwnerFrame.cameras }),
       });
       const frame = extractFrame(world, prepared);
@@ -495,6 +512,30 @@ export function extractFrames(
     return (f.reflectionProbes ?? []).map((probe) => ({ ...probe, worldId }));
   });
 
+  if (options.renderables !== 'none' && options.renderableEntitiesByWorld === undefined) {
+    options.instanceCollections?.retain(
+      new Set(
+        renderables.flatMap((row) =>
+          row.instances?.collectionId === undefined ? [] : [row.instances.collectionId],
+        ),
+      ),
+    );
+    if (
+      skinPaletteAllocator !== null &&
+      typeof skinPaletteAllocator.retainSliceKeys === 'function'
+    ) {
+      skinPaletteAllocator.retainSliceKeys(
+        new Set(
+          renderables.flatMap((row) =>
+            row.skin === undefined
+              ? []
+              : [`${worlds[row.worldId]?.identity ?? row.worldId}:${row.entityKey}`],
+          ),
+        ),
+      );
+    }
+  }
+
   return {
     cameras,
     auxiliaryCameras,
@@ -604,6 +645,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     cull: cullMode,
     resourceOwnerFog,
     getMaterialShaderArtifact,
+    instanceCollections,
+    renderableEntities,
+    retainHidden,
   } = context;
   // Environment reads are owned by the retained resource projection and are
   // established at the frame boundary; record never revisits World state.
@@ -1521,22 +1565,18 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // extraction. Shared handles are immutable inputs for the frame, while
   // dispatch entries still need to be rebuilt for each entity.
   const materialSnapshotCache: MaterialSnapshotCache = new Map();
+  const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
   // (`row.get(X) !== undefined` edge sniff) replaces the prior
   // `arch.components.some` row-internal back-door. K-3 invariant: the
-  // variable-length array reads (`MeshRenderer.materials`,
-  // `Instances.transforms`) still flow through `_getArrayView` /
-  // `world.get(e, Instances)` -- only the `entity` source switches to
-  // `row.entity`.
+  // variable-length array reads (`MeshRenderer.materials`, SpriteInstances
+  // arrays) still flow through `_getArrayView`; explicit Instances bytes also come
+  // from World, before projection into renderer-owned snapshots.
   //
-  // archVersion plumbing exception: the `RenderableSnapshot.instances
-  // .archVersion` cache key is keyed off the live archetype's mutation
-  // counter (record stage `instanceBuffers` cache invalidation). The
-  // QueryRow does not surface this number, so a single archetype
-  // graph access is retained for instance-bearing rows -- match by entity
-  // packed handle. AC-01 grep ≤ current - 1 still holds: the stale
-  // archetype-graph traversal commentary at the prior call site is gone.
+  // archVersion remains the content fingerprint for SpriteInstances' managed
+  // arrays; explicit Instances use the collection revision below and never
+  // need an archetype graph access for their matrix bytes.
   // feat-20260521-sprite-atlas-animation M3 / T-16: SpriteRegionOverride
   // column id for the sprite-bucket per-entity region override read
   void SpriteRegionOverride;
@@ -1564,11 +1604,10 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           })
           .unwrap();
   // QueryRow deliberately exposes component data, not an archetype version.
-  // The optimized ECS owner keeps table storage private, so instance-buffer
-  // invalidation uses a content fingerprint of the managed arrays instead.
+  // SpriteInstances still uses a content fingerprint for its managed arrays;
+  // explicit Instances use the renderer-owned collection revision below.
   const resolveArchVersion = (entity: EntityHandle): number => {
     const values = [
-      worldInternal._getArrayView(entity, Instances, 'transforms'),
       worldInternal._getArrayView(entity, SpriteInstances, 'transforms'),
       worldInternal._getArrayView(entity, SpriteInstances, 'regions'),
     ];
@@ -1591,6 +1630,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     for (const entry of pending) dispatch.push(entry);
   };
   for (const row of meshRendererQuery) {
+    if (
+      context.renderables === 'full' &&
+      renderableEntities !== undefined &&
+      !renderableEntities.has(row.entity)
+    ) {
+      continue;
+    }
     // K-2 archetype-edge sniff (scheme B): a missing optional component
     // surfaces as an absent bundle key, not a row-internal optional chain.
     // Presence-only checks use QueryRow.has so large array-bearing components
@@ -1687,8 +1733,9 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     {
       // feat-20260608 M2 / w11: read materials array via _getArrayView
       const entity = row.entity;
-      if (isRenderable && visibility?.effective(entity) === 'hidden') {
-        explicitlyHidden.add(entity);
+      const authorVisible = !(isRenderable && visibility?.effective(entity) === 'hidden');
+      if (!authorVisible) explicitlyHidden.add(entity);
+      if (!authorVisible && !retainHidden) {
         continue;
       }
       const layerVal = fLayerValue ?? 0;
@@ -1886,6 +1933,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             renderables.length,
             layerVal,
             materialSnap.paramSnapshot,
+            0,
+            materialSnap.materialProgramKeys,
           );
         }
       } else if (handleRaw === 0 || assets === undefined || assets === null) {
@@ -1913,6 +1962,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               renderables.length,
               layerVal,
               materialSnap.paramSnapshot,
+              0,
+              materialSnap.materialProgramKeys,
             );
           }
         } else {
@@ -1976,10 +2027,26 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             }
             const resolved = resolvedResult.value;
             const allPasses = resolved.passes;
-            const firstPassShader =
-              allPasses.length > 0
-                ? runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
-                : undefined;
+            const materialContext =
+              context.materialContext === undefined
+                ? undefined
+                : {
+                    ...context.materialContext,
+                    geometry: hasSkin ? ('skinned' as const) : context.materialContext.geometry,
+                  };
+            const materialProgramKeys = materialProgramKeysForMaterial(
+              asset,
+              assets,
+              materialContext,
+            );
+            const authoredFirstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              undefined,
+            );
+            const firstPassShader = runtimeMaterialShaderIdForMaterial(
+              allPasses,
+              materialProgramKeys,
+            );
             const pv = materialValuesToLinearRuntime(
               resolved.values,
               materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assets),
@@ -2008,7 +2075,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
 
             const materialParamSchema = materialParametersToParamSchema(
               resolved.parameters ?? [],
-              firstPassShader,
+              authoredFirstPassShader,
             );
             // feat-20260611-fox-skinning-vertex-attribute-chain M4 / w17 (D-5):
             // bidirectional Skin <-> pbr-skin material fail-fast at extract.
@@ -2297,6 +2364,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               }),
               normalScale: normalScalePv,
               materialShaderId: firstPassShader,
+              materialProgramKeys,
               materialHandle: handleRaw,
               renderState: pipelineRenderState(allPasses[0]?.renderState),
               paramSnapshot: paramSnap,
@@ -2357,6 +2425,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
                 renderables.length,
                 layerVal,
                 paramSnap,
+                0,
+                materialProgramKeys,
               );
             }
           }
@@ -2512,7 +2582,18 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             // surface is absent (test fixtures that pass undefined) the
             // hasSkin segment is skipped silently — bind-pose equivalent.
             if (skinPaletteAllocator !== null) {
-              const slice = skinPaletteAllocator.allocateSlice(skeleton.jointCount);
+              // Keep the narrow extraction seam compatible with older test or
+              // host-owned allocator doubles while the real renderer uses the
+              // stable-key path. The fallback is frame-local and therefore
+              // cannot affect production allocators that implement the new
+              // method.
+              const slice =
+                typeof skinPaletteAllocator.allocateSliceFor === 'function'
+                  ? skinPaletteAllocator.allocateSliceFor(
+                      `${world.identity}:${entity}`,
+                      skeleton.jointCount,
+                    )
+                  : skinPaletteAllocator.allocateSlice(skeleton.jointCount);
               skinPaletteAllocator.writeJointPalette(slice, ibms, jointWorlds);
               skinSlice = {
                 jointCount: slice.jointCount,
@@ -2556,15 +2637,22 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         if (assets !== undefined && assets !== null) {
           for (let mi = 1; mi < materialHandles.length; mi++) {
             const subHandle = materialHandles[mi] ?? 0;
-            const cachedSubmaterial = materialSnapshotCache.get(subHandle);
+            const subCache = hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache;
+            const cachedSubmaterial = subCache.get(subHandle);
             materialsArr.push(
               cachedSubmaterial?.snapshot ??
                 resolveMaterialSnapshot(
                   subHandle,
                   world,
                   assets,
-                  materialSnapshotCache,
-                  persistentMaterialSnapshotCache,
+                  subCache,
+                  hasSkin ? undefined : persistentMaterialSnapshotCache,
+                  context.materialContext === undefined
+                    ? undefined
+                    : {
+                        ...context.materialContext,
+                        geometry: hasSkin ? 'skinned' : context.materialContext.geometry,
+                      },
                 ),
             );
           }
@@ -2574,8 +2662,14 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
             const subHandle = materialHandles[mi] ?? 0;
             if (subHandle === handleRaw) continue;
             const subEntry =
-              materialSnapshotCache.get(subHandle) ??
-              readPersistentMaterialSnapshot(persistentMaterialSnapshotCache, subHandle, assets);
+              (hasSkin ? skinnedMaterialSnapshotCache : materialSnapshotCache).get(subHandle) ??
+              (hasSkin
+                ? undefined
+                : readPersistentMaterialSnapshot(
+                    persistentMaterialSnapshotCache,
+                    subHandle,
+                    assets,
+                  ));
             appendMaterialDispatchEntries(
               pendingDispatch,
               subEntry?.passes ?? (subHandle === 0 ? [DEFAULT_FORWARD_PASS] : []),
@@ -2584,6 +2678,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               renderables.length,
               layerVal,
               materialsArr[mi]?.paramSnapshot,
+              0,
+              materialsArr[mi]?.materialProgramKeys,
             );
           }
         }
@@ -2727,39 +2823,35 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // Instances are snapshotted before the CPU visibility decision so the
         // culling owner can derive the union of every instance's transformed
         // mesh bounds. The same detached snapshot is then carried to record;
-        // do not re-read the ECS array after culling (a structural write must
-        // not make the cull and draw disagree within one frame).
+        // do not re-read the collection after culling (a mutation must not
+        // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const transforms = worldInternal._getArrayView(entity, Instances, 'transforms');
-          if (transforms === undefined) {
-            // A present component with an unavailable array is an empty
-            // instance contribution, not an absent component. Preserve the
-            // zero-draw contract so the record stage cannot synthesize one
-            // identity instance from an incomplete row.
-            instancesSnap = {
-              transforms: new Float32Array(),
-              instanceCount: 0,
-              cacheKey: entity,
-              archVersion,
-            };
-          } else {
-            const actualLength = transforms.length;
-            if (actualLength % 16 !== 0) {
-              worldInternal._routeError(new InstanceTransformsStrideMismatchError(actualLength), {
+          const transforms =
+            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
+          if (transforms.length % 16 !== 0) {
+            worldInternal._routeError(
+              new InstanceTransformsStrideMismatchError(transforms.length),
+              {
                 severity: Severity.Error,
                 systemName: 'RenderSystem.extract (Instances stride)',
-              });
-              continue;
-            }
-            const snapshotCopy = new Float32Array(transforms);
-            instancesSnap = {
-              transforms: snapshotCopy,
-              instanceCount: actualLength / 16,
-              cacheKey: entity,
-              archVersion,
-            };
+              },
+            );
+            continue;
           }
+          const projected = instanceCollections?.project(world, entity, transforms);
+          instancesSnap = {
+            transforms: projected?.transforms ?? new Float32Array(transforms),
+            instanceCount: transforms.length / 16,
+            cacheKey: entity,
+            archVersion: projected === undefined ? fingerprintNumericArray(transforms) : 0,
+            ...(projected === undefined
+              ? {}
+              : {
+                  collectionId: projected.collectionId,
+                  revision: projected.revision,
+                }),
+          };
         }
 
         const baseRenderable: RenderableSnapshot = {
@@ -2774,7 +2866,11 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           materialBindingDiagnostics,
           worldId: 0,
           entityKey: entity,
+          ...(authorVisible ? {} : { authorVisible: false }),
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
+          ...(skin?.joints === undefined
+            ? {}
+            : { skinJointEntities: Array.from(skin.joints, (joint) => Number(joint)) }),
           ...(morph !== undefined ? { morph } : {}),
           ...(instancesSnap !== undefined ? { instances: instancesSnap } : {}),
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),