@forgeax/engine-render 0.1.24 → 0.1.25

package/src/render-system-extract.ts

@@ -75,27 +75,9 @@
 //                               `MeshFilter.assetHandle` dangling path
 //                               (charter proposition 5; AC-11).
 //
-// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w15:
-//   The legacy `Instances { buffer, count }` form (cross-coupled with the
-//   deleted `AssetRegistry.createInstancedBuffer` triplet + the retired
-//   `InstancedBufferAsset` POD) is gone. Per-entity instance transforms now
-//   live inside the ECS `Instances { transforms: 'array<f32>' }` column;
-//   extract materialises a `Float32Array` snapshot per Instances-bearing
-//   entity (via `world.get(e, Instances).transforms`) so the record stage
-//   can upload to a per-entity GPU storage buffer cached by entity packed
-//   u32.
-//
-// feat-20260515-buffer-array-vocab-collapse M3 / w15: the component-level
-// `arrayStride` hook on `Instances.transforms` was retired (decision section
-// 2.3 stride responsibility migration -- AI users gate at the set / push
-// call sites + RenderSystem extract entry holds a defensive fail-fast).
-// The extract entry checks `transforms.length % 16 === 0` directly after
-// the `world.get(entity, Instances)` snapshot is taken; violations route
-// `InstanceTransformsStrideMismatchError`
-// (`code: 'instance-transforms-stride-mismatch'`,
-// `detail: { actualLength, expectedStride: 16 }`) through the World
-// Layer-3 ErrorHandler and the renderable is skipped. The record stage
-// trusts the invariant and does not re-check.
+// World owns explicit Instances transforms. Extraction makes a detached
+// per-renderer projection; GPU residents acknowledge complete snapshots only
+// after successful uploads. Reading a snapshot never changes author state.
 
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
@@ -166,6 +148,7 @@ import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
+import type { InstanceCollectionId, InstanceProjectionStore } from './instances';
 import type {
   MeshMaterialBindingDiagnostic,
   MeshMaterialBindingSource,
@@ -696,6 +679,8 @@ export interface RenderableSnapshot {
   readonly materialBindingSources: readonly MeshMaterialBindingSource[];
   /** Active structured override diagnostics for this renderable. */
   readonly materialBindingDiagnostics?: readonly MeshMaterialBindingDiagnostic[];
+  /** Effective authored visibility retained by the persistent scene owner. */
+  readonly authorVisible?: boolean;
   /**
    * feat-20260708-composited-multi-world-rendering M1 / D-1: the worldId
    * of the world this renderable was extracted from. Defaults to 0 in
@@ -761,6 +746,8 @@ export interface RenderableSnapshot {
    * Absent (`undefined`) means the entity is not skinned.
    */
   readonly skin?: SkinPaletteSlice;
+  /** Joint entity identities used by the persistent skin dependency index. */
+  readonly skinJointEntities?: readonly number[];
   /**
    * ECS-owned morph weights. Presence selects the Standard Pipeline CPU
    * specialized deformation lane; the asset remains the source of target
@@ -822,10 +809,14 @@ export interface GpuDrivenDrawSnapshot {
 }
 
 export interface InstancesSnapshot {
+  /** Renderer-owned collection identity. */
+  readonly collectionId?: InstanceCollectionId;
   /** Packed column-major mat4 transforms (16 f32 per instance). */
   readonly transforms: Float32Array;
   /** Number of instances (transforms.length / 16). */
   readonly instanceCount: number;
+  /** Collection revision captured by this detached frame snapshot. */
+  readonly revision?: number;
   /** Stable per-entity GPU buffer cache key (the packed Entity u32). */
   readonly cacheKey: number;
   /**
@@ -1134,6 +1125,7 @@ export function appendMaterialDispatchEntries(
   layer: number,
   paramSnapshot: Readonly<Record<string, number | number[] | string>> | undefined,
   passIndexOffset = 0,
+  materialShaderIdOverride?: string,
 ): void {
   const matchedPasses = selectPasses(passes, {});
   for (let pIdx = 0; pIdx < matchedPasses.length; pIdx++) {
@@ -1144,6 +1136,11 @@ export function appendMaterialDispatchEntries(
       readonly queue?: number;
       readonly stencilReference?: number;
     };
+    const authoredShaderId = runtimeMaterialShaderId(pass.program.module, pass.name);
+    const dispatchShaderId =
+      authoredShaderId === 'forgeax::default-shadow-caster'
+        ? authoredShaderId
+        : (materialShaderIdOverride ?? authoredShaderId);
     pendingDispatch.push({
       entityIndex: entity,
       materialHandle,
@@ -1158,7 +1155,14 @@ export function appendMaterialDispatchEntries(
       defines: undefined,
       vertexEntry: pass.program.vertexEntry,
       fragmentEntry: pass.program.fragmentEntry,
-      materialShaderId: runtimeMaterialShaderId(pass.program.module, pass.name),
+      // A cooked Standard publication supplies one specialization key for its
+      // forward/deferred artifact, but its ShadowCaster pass still owns the
+      // engine depth-only shader. Keep the pass-local canonical identity so a
+      // specialized Standard source (which only declares fs_main/fs_gbuffer)
+      // is never asked to build an fs_shadow pipeline. Authored non-Standard
+      // ShadowCaster modules retain the publication override and continue to
+      // use their producer-owned source.
+      materialShaderId: dispatchShaderId,
       paramSnapshot,
       ...(passState.stencilReference !== undefined && {
         stencilReference: passState.stencilReference,
@@ -1410,6 +1414,20 @@ export function runtimeMaterialShaderId(
   }
 }
 
+/**
+ * Select the runtime identity for one resolved material. A cooked publication
+ * owns the composed material artifact identity; the authored pass module is
+ * the built-in fallback used before that publication is ready.
+ */
+export function runtimeMaterialShaderIdForMaterial(
+  material: MaterialAsset,
+  passes: readonly MaterialPass[],
+  assets: AssetRegistry,
+): string | undefined {
+  const authored = runtimeMaterialShaderId(passes[0]?.program.module, passes[0]?.name);
+  return assets.getMaterialProjectionForPayload(material)?.specializationKey ?? authored;
+}
+
 export function pipelineRenderState(
   renderState:
     | (MaterialRenderState & {
@@ -1934,10 +1952,7 @@ export function resolveMaterialSnapshot(
   if (!resolvedResult.ok) return defaultMaterialSnapshot(handleRaw);
   const resolved = resolvedResult.value;
   const allPasses = resolved.passes;
-  const firstPassShader =
-    allPasses.length > 0
-      ? runtimeMaterialShaderId(allPasses[0]?.program.module, allPasses[0]?.name)
-      : undefined;
+  const firstPassShader = runtimeMaterialShaderIdForMaterial(asset, allPasses, assetsRef);
   const pv = materialValuesToLinearRuntime(
     resolved.values,
     materialColorParameterSchema(resolved.parameters ?? [], firstPassShader, assetsRef),
@@ -2542,11 +2557,17 @@ export interface PreparedExtractContext {
   readonly cull: 'self' | 'none' | 'external';
   readonly cullCameras: readonly CameraSnapshot[] | undefined;
   readonly renderables: 'full' | 'none';
+  /** Restrict renderable extraction to these entities while still reading frame resources. */
+  readonly renderableEntities: ReadonlySet<number> | undefined;
+  /** Keep authored-hidden renderables in the persistent source projection. */
+  readonly retainHidden: boolean;
   readonly visibility: VisibilitySnapshot;
   /** Producer-owned artifact lookup; extraction only, never record-time asset reads. */
   readonly getMaterialShaderArtifact:
     | ((materialShaderId: string) => MaterialShaderArtifact | undefined)
     | undefined;
+  /** Renderer-owned canonical source for explicit large instance collections. */
+  readonly instanceCollections: InstanceProjectionStore | undefined;
 }
 
 const ALL_VISIBLE: VisibilitySnapshot = {
@@ -2734,9 +2755,12 @@ export function prepareExtractContext(
     readonly cull?: 'self' | 'none' | 'external';
     readonly cullCameras?: readonly CameraSnapshot[];
     readonly renderables?: 'full' | 'none';
+    readonly renderableEntities?: ReadonlySet<number>;
+    readonly retainHidden?: boolean;
     readonly getMaterialShaderArtifact?: (
       materialShaderId: string,
     ) => MaterialShaderArtifact | undefined;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): PreparedExtractContext {
   const renderables = options.renderables ?? 'full';
@@ -2748,8 +2772,11 @@ export function prepareExtractContext(
     cull: options.cull ?? 'self',
     cullCameras: options.cullCameras,
     renderables,
+    renderableEntities: options.renderableEntities,
+    retainHidden: options.retainHidden ?? false,
     visibility: renderables === 'none' ? ALL_VISIBLE : resolveVisibility(world),
     getMaterialShaderArtifact: options.getMaterialShaderArtifact,
+    instanceCollections: options.instanceCollections,
   };
 }
 

package/src/render-system.ts

@@ -118,7 +118,13 @@ import type { EnvironmentInspection } from './environment/inspection';
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from './gpu-usage';
 import { resetHdrpBuffers } from './hdrp-buffers';
 import { assembleMaterialWithSkylightEntries } from './ibl/skylight-bind-group';
-import { disposeInstanceBuffers, disposeTransientInstanceBuffers } from './instance-buffer-cache';
+import {
+  disposeInstanceBufferChunks,
+  disposeInstanceBuffers,
+  disposeTransientInstanceBuffers,
+} from './instance-buffer-cache';
+import type { InstanceCollectionInspection } from './instances';
+import { InstanceProjectionStore } from './instances';
 import {
   type MeshMaterialBindingObservation,
   type MeshMaterialBindingPreparationFailure,
@@ -182,7 +188,11 @@ import type {
   RenderableSnapshot,
 } from './render-system-extract';
 import { extractFrames } from './render-system-extract';
-import { type PersistentGpuDrivenCandidate, PersistentRenderScene } from './scene/render-scene';
+import {
+  type PersistentGpuDrivenCandidate,
+  type PersistentRenderCandidateRequest,
+  PersistentRenderScene,
+} from './scene/render-scene';
 import { inspectLodOcclusion } from './scene/visibility/inspection';
 import { resolveSsaoParameters } from './ssao-config';
 import { projectSsrDependencies, resolveSsrAdmissionGeneration } from './ssr/admission';
@@ -660,7 +670,7 @@ export interface RenderSystem {
   /** Prepare a detached graph candidate without entering the frame record path. */
   prepareRecoveryGraphCandidate(
     runtime: RecoveryGraphCandidateRuntime,
-  ): RecoveryGraphCandidatePreparation;
+  ): Promise<RecoveryGraphCandidatePreparation>;
   /** Finish and submit detached candidate setup, never a frame receipt. */
   submitCandidateSetup(
     candidate: RecoveryGraphCandidate,
@@ -686,6 +696,8 @@ export interface RenderSystem {
   readonly pipelineDispatchCounts: {
     readonly unlit: number;
   };
+  /** Detached residency and upload facts for explicit instance collections. */
+  readonly instanceCollectionsInspection: readonly InstanceCollectionInspection[];
   /**
    * feat-20260528-frustum-culling M5 / w14: per-frame frustum-culling counters.
    * Updated by `draw([world], { cameraOwner: 0, resourceOwner: 0 })` on every call from the Extract stage.
@@ -1071,6 +1083,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
   let preparedWorlds: readonly World[] = [];
   let latestCamera: CameraSnapshot | undefined;
   const pointsLinesOwner = new StandardPointsLinesOwner(internals);
+  const instanceCollections = new InstanceProjectionStore();
   const reflectionProbeOwner = new ReflectionProbeRecordOwner(internals);
   let ssrFormatReceipt: import('@forgeax/engine-rhi').RhiTextureFormatCapabilityReceipt | undefined;
   let ssrFormatProbeGeneration = -1;
@@ -1112,6 +1125,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     onSharedRefMutation: (worldId, handle) => {
       internals.gpuStore.invalidateMesh(handle, preparedWorlds[worldId] ?? worldId);
     },
+    instanceCollections,
+    getSkinPaletteAllocator: () => internals.getPipelineState()?.skinPaletteAllocator ?? null,
   });
   let environmentLifecycle = new EnvironmentLifecycle(internals.deviceScope);
   const transmissionAdmission = new TransmissionCandidateAdmission();
@@ -1362,6 +1377,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     currentDirectionalShadowView: null,
     currentSpotShadowView: null,
     instanceBuffers: new Map(),
+    instanceResidency: new Map(),
+    instanceBufferChunks: new Map(),
     probeBlendBuffers: new Map(),
     probeBlendRecordBufferCapacity: 0,
     morphBuffers: new Map(),
@@ -2294,6 +2311,12 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     createPreparedResolverCaches,
   });
   return {
+    get instanceCollectionsInspection(): readonly InstanceCollectionInspection[] {
+      return instanceCollections._inspections(
+        frameState.instanceResidency,
+        frameState.frameNumber - 1,
+      );
+    },
     releaseProfilerCatalog(): void {
       releaseProfilerCatalog?.();
       releaseProfilerCatalog = undefined;
@@ -2555,7 +2578,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             compositionWorlds,
             { cameraOwner, resourceOwner },
             internals.assets.catalogEpoch,
-            (renderables) =>
+            (request: PersistentRenderCandidateRequest) =>
               extractFrames(
                 compositionWorlds,
                 { cameraOwner, resourceOwner },
@@ -2564,7 +2587,12 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
                 persistentRenderScene.materialSnapshotCacheStore(),
                 {
                   cull: 'none',
-                  renderables,
+                  renderables: request === 'none' ? 'none' : 'full',
+                  ...(request === 'none' || request === 'full'
+                    ? {}
+                    : { renderableEntitiesByWorld: request.entitiesByWorld }),
+                  retainHidden: true,
+                  instanceCollections,
                   ...(internals.getMaterialShaderArtifact === undefined
                     ? {}
                     : { getMaterialShaderArtifact: internals.getMaterialShaderArtifact }),
@@ -3496,6 +3524,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       (internals as TimingSessionHost).gpuPassTimingBeginReason = undefined;
       pointsLinesOwner.dispose();
       persistentRenderScene.dispose();
+      instanceCollections.dispose();
       gpuDrivenProduction.dispose();
       occlusionRuntime?.dispose();
       disposeFeatureGpuWork();
@@ -3565,6 +3594,10 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       // so destroy failures fire structured errors (unified per-frame +
       // dispose error strategy).
       disposeInstanceBuffers(frameState.instanceBuffers, internals.errorRegistry);
+      frameState.instanceResidency?.clear();
+      if (frameState.instanceBufferChunks !== undefined) {
+        disposeInstanceBufferChunks(frameState.instanceBufferChunks, internals.errorRegistry);
+      }
       disposeTransientInstanceBuffers(frameState.transientInstanceBuffers, internals.errorRegistry);
       if (frameState.probeBlendRecordBuffer !== undefined) {
         if (!frameState.probeBlendRecordBuffer.isDestroyed) {
@@ -3706,6 +3739,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       }
       frameState.retiredCompiledFrameGraphs.clear();
       frameState.instanceBuffers.clear();
+      frameState.instanceBufferChunks?.clear();
+      frameState.instanceResidency?.clear();
       delete frameState.probeBlendRecordBuffer;
       frameState.probeBlendRecordBufferCapacity = 0;
       frameState.probeBlendBuffers.clear();

package/src/scene/render-scene-types.ts

@@ -36,6 +36,8 @@ export interface RenderSceneApplyResult {
   readonly ignoredLateUpdates: number;
   readonly createdSlots: readonly RenderSceneSlot[];
   readonly updatedSlots: readonly RenderSceneSlot[];
+  /** Full retained-snapshot updates; transform spans stay in updatedSlots only. */
+  readonly contentUpdatedSlots?: readonly RenderSceneSlot[];
   readonly removedSlots: readonly RenderSceneRecord[];
   readonly recreatedSlots: readonly RenderSceneSlot[];
   readonly resynced: number;