@forgeax/engine-render 0.1.34 → 0.1.35

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

@@ -183,7 +183,7 @@ import {
 } from './render-system-extract';
 import { buildShadowFrusta } from './scene/shadow-visibility';
 import { SHADOW_ATLAS_DEFAULT_LAYERS } from './shadow-atlas';
-import type { SkinPaletteReceipt } from './systems/skin-palette-types';
+import type { SkinPaletteReceipt, SkinPose } from './systems/skin-palette-types';
 
 function skinPaletteIdentity(world: World, entity: number): string {
   return `skin:${world.identity}:${entity}`;
@@ -2739,6 +2739,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // resolve / validate / write chain (D-9 reset already fired at
         // extractFrame entry; per-entity allocate + writeJointPalette here).
         let skinSlice: SkinPaletteReceipt | undefined;
+        let skinPose: SkinPose | undefined;
         const skinIdentity = hasSkin ? skinPaletteIdentity(world, entity) : undefined;
         const releaseSkinIdentity = (): void => {
           if (skinIdentity !== undefined) {
@@ -2850,6 +2851,17 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               });
               skinPaletteAllocator.writePersistentJointPalette(receipt, ibms, jointWorlds);
               skinSlice = receipt;
+            } else {
+              skinPose = {
+                identity: skinPaletteIdentity(world, entity),
+                generation: ((skeletonHandleRaw >>> 0) ^ skeleton.jointCount) >>> 0,
+                jointCount: skeleton.jointCount,
+                ...(hasFiniteOrderedLocalAabb(skeleton.bounds)
+                  ? { bounds: new Float32Array(skeleton.bounds) }
+                  : {}),
+                inverseBindMatrices: ibms,
+                jointWorlds,
+              };
             }
           }
         }
@@ -2858,7 +2870,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // projection. Do not publish a renderable or its staged dispatch when
         // palette extraction was unavailable; the record stage must never
         // reinterpret a skinned vertex stream through an ordinary mesh group.
-        if (skinSlice === undefined && hasSkin) {
+        if (skinSlice === undefined && skinPose === undefined && hasSkin) {
           releaseSkinIdentity();
           if (
             materialSnap.materialShaderId === 'forgeax::pbr-skin' ||
@@ -3128,6 +3140,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           entityKey: entity,
           ...(authorVisible ? {} : { authorVisible: false }),
           ...(skinSlice !== undefined ? { skin: skinSlice } : {}),
+          ...(skinPose === undefined ? {} : { skinPose }),
           ...(skin?.joints === undefined
             ? {}
             : { skinJointEntities: Array.from(skin.joints, (joint) => Number(joint)) }),
@@ -3136,21 +3149,24 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
           ...(spriteInstancesSnap !== undefined ? { spriteInstances: spriteInstancesSnap } : {}),
           ...(pointsLines !== undefined ? { pointsLines } : {}),
         };
-        const gpuDrivenDraws = buildGpuDrivenDraws({
-          mesh: gpuDrivenMesh,
-          materials: materialsArr,
-          fallbackMaterial: materialSnap,
-          baseSnapshot: baseRenderable,
-          ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
-          ...(lods === undefined
-            ? {}
-            : {
-                lodMeshes: lods.map((lod) => {
-                  const lower = assets?.lookup<Asset>(lod.mesh);
-                  return lower?.kind === 'mesh' ? lower : undefined;
-                }),
-              }),
-        });
+        const gpuDrivenDraws =
+          skinPose === undefined
+            ? buildGpuDrivenDraws({
+                mesh: gpuDrivenMesh,
+                materials: materialsArr,
+                fallbackMaterial: materialSnap,
+                baseSnapshot: baseRenderable,
+                ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
+                ...(lods === undefined
+                  ? {}
+                  : {
+                      lodMeshes: lods.map((lod) => {
+                        const lower = assets?.lookup<Asset>(lod.mesh);
+                        return lower?.kind === 'mesh' ? lower : undefined;
+                      }),
+                    }),
+              })
+            : [];
         for (const draw of gpuDrivenDraws) {
           if (draw.preparationError === undefined) continue;
           worldInternal._routeError(draw.preparationError, {

package/src/render-system-extract.ts

@@ -792,6 +792,8 @@ export interface RenderableSnapshot {
    * Absent (`undefined`) means the entity is not skinned.
    */
   readonly skin?: SkinPaletteReceipt;
+  /** Source pose waiting for the receiving Renderer to assign a palette. */
+  readonly skinPose?: import('./systems/skin-palette-types').SkinPose;
   /** Joint identities consumed by the retained scene dependency index. */
   readonly skinJointEntities?: readonly number[];
   /** Source pass ownership retained with the scene record across view changes. */

package/src/render-system-presentation.ts

@@ -1,4 +1,4 @@
-import type { World } from '@forgeax/engine-ecs';
+import type { RenderResourceScope } from './publication/resource-scope';
 import type { RenderSystemInternals } from './record/render-context';
 import type { FramePresentation } from './render-contract';
 import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
@@ -20,7 +20,7 @@ export function projectFramePresentation(input: {
   readonly hasEnvironment: boolean;
   readonly submissionRenderables: readonly RenderableSnapshot[];
   readonly submissionDispatch: readonly DispatchEntry[];
-  readonly preparedWorlds: readonly World[];
+  readonly preparedWorlds: readonly RenderResourceScope[];
   readonly internals: RenderSystemInternals;
 }): FramePresentationProjection {
   const displayRenderableIndices = new Set<number>();

package/src/render-system-projections.ts

@@ -6,6 +6,7 @@ import type {
   LodOcclusionInspectionRow,
   LodOcclusionWorldInspection,
 } from './inspection-types';
+import type { RenderResourceScope } from './publication/resource-scope';
 import { worldEntityKey } from './record/frame-snapshot';
 import type { CameraSnapshot, DrawOwnerOptions } from './render-contract';
 import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
@@ -52,7 +53,7 @@ interface LodInspectionQuerySummary {
 }
 
 export function createLodWorldInspections(
-  worlds: readonly World[],
+  worlds: readonly RenderResourceScope[],
   renderables: readonly RenderableSnapshot[],
   submittedRenderables: readonly RenderableSnapshot[],
   camera: CameraSnapshot,
@@ -164,7 +165,7 @@ export function createLodWorldInspections(
 /** Apply the configured stable sub-sort to transparent dispatch entries. */
 export function sortTransparentDispatch(
   dispatch: DispatchEntry[],
-  world: World,
+  world: RenderResourceScope,
   cameras: readonly CameraSnapshot[],
   renderables: readonly RenderableSnapshot[],
 ): DispatchEntry[] {

package/src/render-system-residency.ts

@@ -1,5 +1,4 @@
 import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
-import type { World } from '@forgeax/engine-ecs';
 import {
   deriveTextureLayout,
   type MaterialAsset,
@@ -11,6 +10,7 @@ import type {
   MeshMaterialBindingPreparationFailure,
   MeshMaterialBindingResidency,
 } from './mesh-material-bindings';
+import type { RenderResourceScope } from './publication/resource-scope';
 import type { RenderSystemInternals } from './record/render-context';
 import { materialSamplerHandles, materialTextureHandles } from './recovery/render-system-candidate';
 import type { MaterialSnapshot } from './render-system-extract';
@@ -49,7 +49,7 @@ function preparationFailureFrom(error: unknown): MeshMaterialBindingPreparationF
  * already resident resource remains last-known-good.
  */
 export function observeMaterialResidency(
-  world: World | undefined,
+  world: RenderResourceScope | undefined,
   material: MaterialSnapshot,
   internals: RenderSystemInternals,
 ): MeshMaterialBindingResidency {

package/src/render-system.ts

@@ -1,4 +1,9 @@
 import { projectCaptureScene } from './capture/scene-projection';
+import { renderMaterialContext } from './extract/material-context';
+import { RenderPublicationError } from './publication/contract';
+import { preparePublicationGeometry } from './publication/prepare-geometry';
+import type { PreparedRenderPublication } from './publication/receiver';
+import { type RenderResourceScope, renderTime } from './publication/resource-scope';
 import type { RenderSceneBounds } from './scene/render-scene-types';
 // @forgeax/engine-math is referenced through render-system-record.ts which builds
 // view/proj matrices and worldFromLocal via `mat4.compose / .multiply /
@@ -6,13 +11,13 @@ import type { RenderSceneBounds } from './scene/render-scene-types';
 // asserts `/@forgeax\/engine-math/` shows up in render-system.ts source).
 
 import { numMipLevels } from '@forgeax/engine-assets-runtime';
-import { Time, type World } from '@forgeax/engine-ecs';
+import type { World } from '@forgeax/engine-ecs';
 import type { RenderReadLease } from '@forgeax/engine-ecs/projection';
 import type { RecorderSession } from '@forgeax/engine-profiler';
 import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
 import type { BindGroupLayout, Buffer, RenderPipeline, RhiDevice } from '@forgeax/engine-rhi';
 import { err, ok, type Result, RhiError } from '@forgeax/engine-rhi';
-import { type RenderPipelineAsset, toShared } from '@forgeax/engine-types';
+import { type Handle, type RenderPipelineAsset, toShared } from '@forgeax/engine-types';
 import {
   type DirectionalShadowInspectionSource,
   directionalShadowProfileFromQuality,
@@ -363,6 +368,7 @@ export interface RenderSystem {
     opts: DrawOwnerOptions,
     renderReadLeases?: readonly RenderReadLease[],
     timingCapture?: GpuTimingCapture,
+    publication?: PreparedRenderPublication,
   ): boolean;
   /**
    * Return the asset binding consumed by the last successful record pass.
@@ -604,7 +610,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
   );
   let releaseProfilerCatalog =
     phaseCatalogRegistration?.ok === true ? phaseCatalogRegistration.value : undefined;
-  let preparedWorlds: readonly World[] = [];
+  let preparedWorlds: readonly RenderResourceScope[] = [];
   const resolveFeatureNoise = createFeatureNoiseResolver({
     scope: internals.deviceScope,
     getDevice: () => internals.device,
@@ -1497,7 +1503,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
   let orderedDispatchCache:
     | {
         readonly source: readonly DispatchEntry[];
-        readonly world: World;
+        readonly world: RenderResourceScope;
         readonly camera: readonly CameraSnapshot[];
         readonly renderables: readonly RenderableSnapshot[];
         readonly value: readonly DispatchEntry[];
@@ -1628,7 +1634,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
     (
       runtime: RenderSystemInternals,
       gpuWork: RenderFeatureGpuWorkOwner,
-      worlds: readonly World[],
+      worlds: readonly RenderResourceScope[],
       caches: PreparedResolverCaches,
     ) =>
     (input: RenderFeaturePreparedGraphicsResolverInput): PreparedGraphicsResolver => {
@@ -2198,9 +2204,12 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
       opts: DrawOwnerOptions,
       renderReadLeases?: readonly RenderReadLease[],
       timingCapture?: GpuTimingCapture,
+      publication?: PreparedRenderPublication,
     ): boolean {
       const composition = canonicalizeWorldComposition(worlds, opts, renderReadLeases);
-      const compositionWorlds = composition.worlds;
+      const sourceWorlds = composition.worlds;
+      const compositionWorlds: readonly RenderResourceScope[] =
+        publication === undefined ? sourceWorlds : [publication.resources];
       const compositionLeases = composition.leases;
       preparedWorlds = compositionWorlds;
       const profileSession = internals.profiler?.activeSession();
@@ -2240,21 +2249,45 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           // so a hot-swap cannot reuse passes compiled for the retired pipeline.
           resetRenderFeatureGraphState(internals);
           lastBuiltPipelineHandle = frameState.installedPipelineHandle;
-          persistentRenderScene.invalidate();
+          if (publication === undefined) persistentRenderScene.invalidate();
         }
         dispatchCounts.unlit = 0;
 
-        const resourceWorld = compositionWorlds[resourceOwner] as World;
+        const resourceWorld = compositionWorlds[resourceOwner] as RenderResourceScope;
         let frame: ReturnType<PersistentRenderScene['extractComposition']>;
         try {
           frame = runProfiledRenderPhase(profileSession, 'extract', () => {
+            if (publication !== undefined) {
+              for (const handle of [
+                ...publication.packet.invalidatedAssets,
+                ...publication.packet.retiredAssets,
+              ]) {
+                internals.gpuStore.invalidateMesh(handle, publication.resources);
+                internals.gpuStore.evictTexture(
+                  handle as Handle<'TextureAsset', 'shared'>,
+                  publication.resources,
+                );
+              }
+              return persistentRenderScene.consumePublication(
+                preparePublicationGeometry(
+                  publication,
+                  persistentRenderScene,
+                  internals.getPipelineState()?.skinPaletteAllocator,
+                  internals.assets,
+                  instanceCollections,
+                  internals.device.caps.storageBuffer
+                    ? internals.getMaterialShaderArtifact
+                    : undefined,
+                ),
+              );
+            }
             return persistentRenderScene.extractComposition(
-              compositionWorlds,
+              sourceWorlds,
               { cameraOwner, resourceOwner },
               internals.assets.catalogEpoch,
               (renderables) =>
                 extractFrames(
-                  compositionWorlds,
+                  sourceWorlds,
                   {
                     cameraOwner,
                     resourceOwner,
@@ -2264,25 +2297,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
                   internals.getPipelineState(),
                   persistentRenderScene.materialSnapshotCacheStore(),
                   {
-                    ...(internals.device.caps.backendKind === 'null'
-                      ? {}
-                      : {
-                          materialContext: {
-                            backend:
-                              internals.device.caps.backendKind === 'wgpu-webgl2'
-                                ? ('webgl2' as const)
-                                : internals.device.caps.backendKind,
-                            capability: internals.device.caps.storageBuffer
-                              ? ('storage-buffer' as const)
-                              : ('uniform-fallback' as const),
-                            pipeline: 'forward' as const,
-                            geometry: 'mesh' as const,
-                            pass: 'forward' as const,
-                            profile: 'forgeax-material-wgsl-v1' as const,
-                            toolchain: 'naga-oil' as const,
-                            instrumentation: 'none' as const,
-                          },
-                        }),
+                    ...renderMaterialContext(internals.device.caps),
                     cull: 'none',
                     retainHidden: true,
                     renderables,
@@ -2308,6 +2323,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         lastMotionBlurInvalidParams = undefined;
         const {
           cameras: extractedCameras,
+          auxiliaryCameras,
           cubeCameras,
           lights,
           environment,
@@ -2333,7 +2349,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           frameState,
           internals,
           cameras[0],
-          compositionWorlds[cameraOwner] as World,
+          compositionWorlds[cameraOwner] as RenderResourceScope,
         );
         if (!preparedOutput.ok) {
           internals.errorRegistry.fire(preparedOutput.error);
@@ -2814,7 +2830,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         const motionBlurParams = cameras[0]?.motionBlur;
         let motionBlurDelta = 0;
         try {
-          const delta = (compositionWorlds[cameraOwner] as World).getResource(Time).delta;
+          const delta = renderTime(compositionWorlds[cameraOwner] as RenderResourceScope).delta;
           motionBlurDelta = Number.isFinite(delta) ? Math.max(0, delta) : 0;
         } catch {
           motionBlurDelta = 0;
@@ -2856,9 +2872,29 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
                 .skylightResources;
         let featureGraphCandidate: RenderFeatureGraphCandidate | undefined;
         const preparedResourceBatches = runProfiledRenderPhase(profileSession, 'features', () => {
+          if (
+            publication?.packet.features.some(
+              (row) =>
+                !internals.featureHost?.features.some(
+                  (feature) => feature.identity === row.identity,
+                ),
+            )
+          )
+            throw new RenderPublicationError({
+              reason: 'shape',
+              subject: 'published feature has no receiver implementation',
+            });
           if (internals.featureHost === undefined) return [];
           const featureFrame = runRenderFeatureFrame(internals.featureHost, {
-            worlds: compositionWorlds,
+            worlds: sourceWorlds,
+            ...(publication === undefined
+              ? {}
+              : {
+                  publishedFeatures: publication.packet.features,
+                  ...(publication.onFeatureSourceSubmitted === undefined
+                    ? {}
+                    : { onFeatureSourceSubmitted: publication.onFeatureSourceSubmitted }),
+                }),
             owner: resourceOwner,
             frameNumber: frameState.frameNumber,
             ...(cameras[0] === undefined ? {} : { selectedCamera: cameras[0] }),
@@ -3053,8 +3089,8 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
           frameState.standardLutState.resident !== null ||
           frameState.pendingStandardLutState !== undefined;
         if (hasLiveFeatureState) {
-          const cameraWorld = compositionWorlds[cameraOwner] as World;
-          const deltaTime = cameraWorld.getResource(Time).delta;
+          const cameraWorld = compositionWorlds[cameraOwner] as RenderResourceScope;
+          const deltaTime = renderTime(cameraWorld).delta;
           stageLiveFeatureState(
             cameras[0],
             Number.isFinite(deltaTime) ? Math.max(0, deltaTime) : 0,
@@ -3071,16 +3107,15 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
         frameState.surfaceSubmissionObservation = surfaceSubmissionCandidate;
         const probeCaptureScene =
           shadowCasterProjection !== undefined &&
-          reflectionProbeRecord.graph.work.some((work) => work.rawCaptureFace !== undefined)
+          (auxiliaryCameras.length > 0 ||
+            cubeCameras.length > 0 ||
+            reflectionProbeRecord.graph.work.some((work) => work.rawCaptureFace !== undefined))
             ? projectCaptureScene(shadowCasterProjection, submissionRenderables, orderedDispatch)
             : undefined;
-        // This is a transient projection of the record owner's actual visible
-        // draws. It lets the presentation fact distinguish a clear/submit
-        // from a frame where geometry or its pipeline was skipped, without
-        // retaining a second readiness registry or per-asset counter.
+        // Track actual draws so a clear/submit cannot claim visible geometry was presented.
         const presentedRenderableKeys = new Set<number>();
         const presentedSubmeshKeys = new Set<string>();
-        const consumeDynamicGeometry = dynamicGeometryFrames.onRenderableDraw(compositionWorlds);
+        const consumeDynamicGeometry = dynamicGeometryFrames.onRenderableDraw(sourceWorlds);
         const markPresentedRenderable = (
           entry: Parameters<typeof consumeDynamicGeometry>[0],
           submeshIndex?: number,
@@ -3131,7 +3166,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
               },
               ...(occlusionProjection === undefined ? {} : { occlusion: occlusionProjection }),
               frameTime: (() => {
-                const elapsed = (compositionWorlds[cameraOwner] as World).getResource(Time).elapsed;
+                const elapsed = renderTime(
+                  compositionWorlds[cameraOwner] as RenderResourceScope,
+                ).elapsed;
                 return Number.isFinite(elapsed) ? elapsed : 0;
               })(),
               deviceGeneration: internals.deviceScope.generation,
@@ -3145,6 +3182,7 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             pointsLinesOwner,
             {
               snapshots: cubeCameras,
+              auxiliaryCameras,
               scheduler: cubeCaptureScheduler,
               state: cubeCaptureState,
               reflectionProbes: reflectionProbeRecord,
@@ -3329,7 +3367,9 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
             width: Math.max(1, internals.canvas.width),
             height: Math.max(1, internals.canvas.height),
             frameTime: (() => {
-              const elapsed = (compositionWorlds[cameraOwner] as World).getResource(Time).elapsed;
+              const elapsed = renderTime(
+                compositionWorlds[cameraOwner] as RenderResourceScope,
+              ).elapsed;
               return Number.isFinite(elapsed) ? elapsed : 0;
             })(),
             ...(surfaceDynamicInputFrame === undefined
@@ -4054,14 +4094,3 @@ export function createRenderSystem(internals: RenderSystemInternals): RenderSyst
 export function resolveInspectionBuild(internals: Pick<RenderSystemInternals, 'build'>): string {
   return internals.build ?? 'render-system';
 }
-
-// @forgeax/engine-render - built-in record context extension.
-//
-// The public RenderPipelineContext is canonical in render-contract.ts. This
-// owner adds only concrete assembly state for built-in record closures.
-
-/**
- * Package-private extension consumed by the built-in record closures only.
- * Custom pipeline authors see the leaf RenderPipelineContext contract and
- * never this surface.
- */