@forgeax/engine-render 0.1.32 → 0.1.34

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

@@ -37,11 +37,11 @@ import {
   ASSET_ERROR_HINTS,
   AssetError,
   derive,
-  err,
   handleSlot,
   materialValuesToLinearRuntime,
   toShared,
 } from '@forgeax/engine-types';
+import { type ExtractedCloudLayer, extractCloudLayer } from './cloud/extract';
 import {
   Atmosphere,
   DirectionalLight,
@@ -86,16 +86,13 @@ import {
   gpuDrivenSourceDrawItemIndex,
 } from './extract/gpu-driven';
 import type { VisibilitySnapshot } from './extract/visibility';
+import { MotionBlurValidationError } from './features/motion-blur/motion-blur-params';
 import type {
   RenderFeatureHiddenEntityReport,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
 import { ensureGlyphMeshMaterialSlots } from './glyph-text-layout-system';
-import {
-  InstanceCollectionError,
-  type InstanceCollectionId,
-  type InstanceCollectionStore,
-} from './instances';
+import { type InstanceProjectionStore, validateInstanceTransforms } from './instances';
 import { deriveInstancesUnionBounds } from './instances-derived-bounds';
 import {
   type MeshMaterialBindingDiagnostic,
@@ -233,11 +230,12 @@ export function extractFrames(
       request?: {
         readonly vertexColorAvailable?: boolean;
         readonly deformation?: 'rigid' | 'skin';
+        readonly variantSet?: string;
         readonly pass?: 'forward' | 'shadow' | 'depth';
         readonly address?: 'direct' | 'scene-index';
       },
     ) => MaterialShaderArtifact | undefined;
-    readonly instanceCollections?: InstanceCollectionStore;
+    readonly instanceCollections?: InstanceProjectionStore;
   } = {},
 ): ExtractedFrame {
   // w4: normalize the owner argument. A bare number is the legacy single-owner
@@ -350,6 +348,11 @@ export function extractFrames(
 
       framesByWorld.set(wi, frame);
     } catch (err) {
+      // Camera effect parameters are part of the public render contract. Keep
+      // their typed validation error on the renderer path so draw() can return
+      // a RenderError and publish the invalid inspection state; ordinary
+      // per-world extraction failures retain the existing world-local route.
+      if (err instanceof MotionBlurValidationError) throw err;
       // Per-world failure: route to world's own error handler, skip contribution.
       try {
         createWorldInternalView(world)._routeError(err, {
@@ -563,6 +566,7 @@ export function extractFrames(
   };
 
   const volumetricFog = resourceOwnerFrame?.volumetricFog;
+  const cloudLayer = resourceOwnerFrame?.cloudLayer;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
@@ -645,6 +649,7 @@ export function extractFrames(
     ...(volumetricFog === undefined
       ? {}
       : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch: dispatchEntries,
     shadowCasterEntityKeys,
@@ -789,6 +794,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // calls survive untouched, only the entity source changes).
   const worldInternal = createWorldInternalView(world);
   let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
+  let cloudLayer: ExtractedCloudLayer | undefined;
+  const extractedCloudLayer = extractCloudLayer(world);
+  if (extractedCloudLayer.ok) {
+    cloudLayer = extractedCloudLayer.value;
+  } else {
+    worldInternal._routeError(extractedCloudLayer.error, {
+      severity: Severity.Error,
+      systemName: 'RenderSystem.extract (cloud-layer)',
+    });
+  }
 
   const cameraRoles = selectCameraRoles(world, context.cameraEntityKey);
   const cameras = [...cameraRoles.display];
@@ -1571,6 +1586,8 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       mieCoefficient: value.mieCoefficient,
       mieDirectionalG: value.mieDirectionalG,
       sunAngularRadius: value.sunAngularRadius,
+      circumsolarStrength: value.circumsolarStrength,
+      circumsolarWidth: value.circumsolarWidth,
     } as const;
     environmentCandidates.push({
       kind: 'atmosphere',
@@ -1700,13 +1717,6 @@ 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();
-  // A collection can be associated with more than one entity. Snapshot its
-  // renderer-owned bytes once per extracted frame so culling and every
-  // submission lane consume the same detached revision without repeat copies.
-  const instanceSnapshotCache = new Map<
-    InstanceCollectionId,
-    ReturnType<InstanceCollectionStore['snapshot']>
-  >();
   const skinnedMaterialSnapshotCache: MaterialSnapshotCache = new Map();
   // tweak-20260611 M1: MeshRenderer renderable archetype walk routes
   // through one World-owned Query. K-2 sniffing scheme B
@@ -1771,22 +1781,25 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   const flushPendingDispatch = (pending: readonly DispatchEntry[]): void => {
     for (const entry of pending) dispatch.push(entry);
   };
-  for (const row of meshRendererQuery) {
-    if (
-      context.renderables === 'full' &&
-      renderableEntities !== undefined &&
-      !renderableEntities.has(row.entity)
-    ) {
-      continue;
-    }
+  const requestedRows =
+    renderableEntities === undefined
+      ? meshRendererQuery
+      : {
+          *[Symbol.iterator]() {
+            for (const entity of renderableEntities) {
+              const row = meshRendererQuery.at(entity as EntityHandle);
+              if (row !== undefined) yield row;
+            }
+          },
+        };
+  for (const row of requestedRows) {
     // 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
     // are not materialised merely to answer a boolean question.
     const hasTransform = row.has(Transform);
     const meshFilter = row.get(MeshFilter);
-    const instancesData = row.get(Instances);
-    const hasInstances = instancesData !== undefined;
+    const hasInstances = row.has(Instances);
     const skin = row.get(Skin);
     const morphWeightsView = worldInternal._getArrayView(row.entity, MorphWeights, 'weights');
     const hasMeshFilter = meshFilter !== undefined;
@@ -1881,6 +1894,13 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       if (!authorVisible && !retainHidden) {
         continue;
       }
+      // A scalar shared<T> field uses slot 0 as the schema-level unbound
+      // sentinel. An entity carrying an unbound MeshFilter is not a
+      // renderable yet; keep it out of frame validation. Non-zero handles
+      // still follow the normal resolve/error path below.
+      if (isRenderable && fAssetHandle === 0) {
+        continue;
+      }
       const layerVal = fLayerValue ?? 0;
       // bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu M2.5
       // (carries PR #598 feat-20260703 D-7): dispatch entries for this entity
@@ -2559,6 +2579,16 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
               baseColor,
               metallic: metallicPv,
               roughness: roughnessPv,
+              ...(resolved.surface?.model === undefined
+                ? {}
+                : { surfaceModel: resolved.surface.model }),
+              deferredPass: allPasses.some(
+                (pass) =>
+                  String(
+                    (pass.renderState?.tags as Record<string, unknown> | undefined)?.LightMode ??
+                      pass.name,
+                  ) === 'Deferred',
+              ),
               ...(specularColorPv !== undefined && {
                 specularColor: [
                   specularColorPv[0] ?? 1,
@@ -3058,48 +3088,29 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
         // make the cull and draw disagree within one frame).
         let instancesSnap: InstancesSnapshot | undefined;
         if (hasInstances) {
-          const collectionId = instancesData?.collectionId as InstanceCollectionId | undefined;
-          let collectionResult =
-            collectionId !== undefined ? instanceSnapshotCache.get(collectionId) : undefined;
-          if (collectionResult === undefined) {
-            collectionResult =
-              collectionId !== undefined && collectionId > 0 && instanceCollections !== undefined
-                ? instanceCollections.snapshot(collectionId)
-                : err(
-                    new InstanceCollectionError(
-                      'instance-collection-invalid',
-                      'Instances.collectionId references a live renderer-owned collection',
-                      'create the collection through renderer.instances before attaching Instances',
-                      {
-                        operation: 'inspect',
-                        expected: 'a positive collectionId with a live renderer owner',
-                        actual: Number(collectionId ?? 0),
-                        ...(collectionId === undefined ? {} : { collectionId }),
-                      },
-                    ),
-                  );
-            if (collectionId !== undefined)
-              instanceSnapshotCache.set(collectionId, collectionResult);
-          }
-          if (collectionResult === undefined) continue;
-          if (!collectionResult.ok) {
-            worldInternal._routeError(collectionResult.error, {
+          const transforms =
+            worldInternal._getArrayView(entity, Instances, 'transforms') ?? new Float32Array();
+          const invalid = validateInstanceTransforms(transforms);
+          if (invalid !== undefined) {
+            worldInternal._routeError(invalid, {
               severity: Severity.Error,
-              systemName: 'RenderSystem.extract (Instances collection)',
+              systemName: 'RenderSystem.extract (Instances transforms)',
             });
             continue;
           }
+          const projected = instanceCollections?.project(world, entity, transforms);
           instancesSnap = {
-            transforms: collectionResult.value.transforms,
-            instanceCount: collectionResult.value.count,
-            collectionId: collectionResult.value.collectionId,
-            revision: collectionResult.value.revision,
-            capacity: collectionResult.value.capacity,
-            dirtyRanges: collectionResult.value.dirtyRanges,
+            transforms: projected?.transforms ?? new Float32Array(transforms),
+            instanceCount: transforms.length / 16,
             cacheKey: entity,
-            // Explicit collection revisions supersede ECS archetype content
-            // hashes; retain zero as the legacy sprite-only field value.
-            archVersion: 0,
+            archVersion: projected === undefined ? archVersion : 0,
+            ...(projected === undefined
+              ? {}
+              : {
+                  collectionId: projected.collectionId,
+                  revision: projected.revision,
+                  generations: projected.generations,
+                }),
           };
         }
 
@@ -3375,6 +3386,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     environment,
     environmentReady: true,
     ...(volumetricFog === undefined ? {} : { volumetricFog }),
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     renderables,
     dispatch,
     shadowCasterEntityKeys,