@forgeax/engine-render 0.1.7 → 0.1.20

package/src/render-system-extract.ts

@@ -102,7 +102,7 @@ import {
   resolveAssetHandle,
   walkMaterialPassesOverSharedRefs,
 } from '@forgeax/engine-assets-runtime';
-import type { Component, ComponentSchema, EntityHandle, World } from '@forgeax/engine-ecs';
+import type { Component, ComponentSchema, EntityHandle, Query, World } from '@forgeax/engine-ecs';
 import {
   InstanceTransformsStrideMismatchError,
   readRenderArrayView,
@@ -142,6 +142,7 @@ import type {
   ParamSchemaEntry,
   PrimitiveTopology,
   SkeletonAsset,
+  TextureAsset,
 } from '@forgeax/engine-types';
 import {
   ASSET_ERROR_HINTS,
@@ -152,11 +153,9 @@ import {
   toShared,
 } from '@forgeax/engine-types';
 import {
-  antialiasFromF32,
-  bloomEnabledFromF32,
-  Camera,
-  cameraProjectionFromF32,
+  Atmosphere,
   DirectionalLight,
+  Fog,
   Instances,
   Layer,
   Lines,
@@ -173,16 +172,23 @@ import {
   SpotLight,
   SpriteInstances,
   SpriteRegionOverride,
-  tonemapFromF32,
   tonemapToU32,
 } from './components';
 import { GlyphText } from './components/glyph-text';
 import { computeInvRangeSquared, degToCos } from './components/light-helpers';
+import { selectEnvironment } from './environment/frame';
 import {
   MaterialSkinAttrMissingError,
   ShadowInvalidConfigError,
   SkinMaterialMismatchError,
 } from './errors/render';
+import { extractCameraSnapshots } from './extract/camera';
+import type {
+  EnvironmentCandidate,
+  EnvironmentFrame,
+  FogCandidate,
+  FogFrame,
+} from './extract/environment';
 import { resolveVisibility, type VisibilitySnapshot } from './extract/visibility';
 import type {
   RenderFeatureHiddenEntityReport,
@@ -197,11 +203,22 @@ import {
 import { isStandardPbrMaterialShader } from './pbr-pipeline';
 import { expandPointsLinesBounds } from './points-lines/bounds';
 import type { PointsLinesRetainedSnapshot, PointsLinesStyle } from './points-lines/snapshot';
-import { type CameraSnapshot, STANDARD_TONEMAP_FEATURE_ID } from './render-contract';
-import { getActiveCamera, selectActiveCameraIndex } from './systems/active-camera';
+import { type CameraSnapshot, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from './render-contract';
 import { selectPasses } from './systems/pass-selector';
+
+export { extractCameraSnapshots } from './extract/camera';
+
 import type { SkinPaletteAllocator } from './systems/skin-palette-allocator';
 import type { SkinPaletteSlice } from './systems/skin-palette-types';
+import { resolveSelectedVolumetricLight } from './volume/capability';
+import {
+  type ValidatedVolumetricFog,
+  type VolumeDensityBinding,
+  VolumetricFog,
+  type VolumetricFogAuthoring,
+} from './volume/component';
+import { extractVolumetricFog } from './volume/extract';
+import type { VolumeProjectorTuple } from './volume/temporal';
 
 /**
  * DirectionalLightSnapshot — sun-like infinite light variant of the
@@ -214,6 +231,7 @@ import type { SkinPaletteSlice } from './systems/skin-palette-types';
  */
 export interface DirectionalLightSnapshot {
   readonly kind: 'directional';
+  readonly entity?: EntityHandle;
   readonly direction: Vec3;
   readonly color: Vec3;
   readonly intensity: number;
@@ -227,6 +245,7 @@ export interface DirectionalLightSnapshot {
  */
 export interface PointLightSnapshot {
   readonly kind: 'point';
+  readonly entity?: EntityHandle | number;
   readonly position: Vec3;
   readonly color: Vec3;
   readonly intensity: number;
@@ -310,10 +329,15 @@ export interface PointShadowSnapshot {
  * is false, dir degenerates, or the light is clipped). shadowAtlasTile
  * (i32 sentinel -1) is the allocated tile index 0..3 or -1 for unassigned
  * (plan-strategy D-4). mapSize / nearPlane / farPlane are the source
- * component shadow parameters carried through to the record stage.
+ * component shadow parameters carried through to the record stage. The
+ * author-facing `shadowIntensity` remains in [0,1] and is copied unchanged;
+ * shader consumers apply it only to shadow visibility, never to candela
+ * radiance.
  */
 export interface SpotLightSnapshot {
   readonly kind: 'spot';
+  /** Entity identity is branded in extracted frames; numeric fixtures remain compatible. */
+  readonly entity?: EntityHandle | number;
   readonly position: Vec3;
   readonly direction: Vec3;
   readonly color: Vec3;
@@ -328,6 +352,17 @@ export interface SpotLightSnapshot {
   readonly nearPlane: number;
   readonly farPlane: number;
   readonly shadowAtlasTile: number;
+  /** Fraction of sampled shadow visibility to retain; 1 = fully opaque shadow. */
+  readonly shadowIntensity?: number;
+  readonly depthBias?: number;
+  readonly normalBias?: number;
+  readonly pcfKernelSize?: number;
+  /** Authoritative TextureAsset projector resolved from the SpotLight handle. */
+  readonly projectorHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly projectorAsset?: TextureAsset;
+  readonly projectorGuid?: string;
+  readonly projectorGeneration?: number;
+  readonly projectorRevision?: number;
 }
 
 /**
@@ -498,6 +533,37 @@ export interface SkyboxSnapshot {
   readonly entityHandle: number;
 }
 
+/**
+ * Resource-owner projection for the single ECS VolumetricFog singleton.
+ *
+ * The renderer carries the validated authoring facts and the source POD all
+ * the way to the record stage.  No profile flag or source/catalog byte is
+ * allowed to enable the graph: `status: 'available'` is produced only after
+ * the ECS component, its shared TextureAsset, and the volume validator all
+ * agree on one linear 3D density owner.
+ */
+export interface ExtractedVolumetricFog {
+  readonly status: 'off' | 'available' | 'degraded';
+  readonly fog?: ValidatedVolumetricFog;
+  readonly densityHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly densityAsset?: TextureAsset;
+  readonly guid?: string;
+  readonly generation?: number;
+  readonly digest?: string;
+  readonly worldId?: number;
+  /** Required same-World light selected by the authoring component. */
+  readonly lightEntity?: EntityHandle;
+  readonly lightKind?: 'directional' | 'point' | 'spot';
+  /** Optional Point+Spot pair identities consumed by the volume integrator. */
+  readonly pointLightEntity?: EntityHandle;
+  readonly spotLightEntity?: EntityHandle;
+  /** Accepted projector tuple shared by surface and volume when authored. */
+  readonly projector?: VolumeProjectorTuple;
+  /** The resolved projector payload shared with the surface light snapshot. */
+  readonly projectorHandle?: Handle<'TextureAsset', 'shared'>;
+  readonly projectorAsset?: TextureAsset;
+}
+
 export interface RenderableSnapshot {
   readonly assetHandle: number;
   readonly transform: TransformSnapshot;
@@ -604,10 +670,32 @@ export interface RenderableSnapshot {
    * deltas and the record stage only receives this frozen POD snapshot.
    */
   readonly morph?: MorphSnapshot;
+  /** Renderer-owned previous-frame facts attached during temporal projection. */
+  readonly temporal?: RenderableTemporalSnapshot;
   /** Detached M2 authoring facts for the optional Points/Lines projection. */
   readonly pointsLines?: PointsLinesRetainedSnapshot;
 }
 
+export type RenderablePreviousSource = 'last-submitted' | 'current-seed';
+export type RenderableReactiveReason =
+  | 'new-slot'
+  | 'generation-reuse'
+  | 'reentered'
+  | 'geometry-revision'
+  | 'material-revision'
+  | 'skinning-deformation'
+  | 'morph-deformation';
+export interface RenderableTemporalSnapshot {
+  readonly previousEpoch: number | undefined;
+  readonly previousSource: RenderablePreviousSource;
+  readonly reactive: boolean;
+  readonly reactiveReasons: readonly RenderableReactiveReason[];
+  readonly previousTransform: TransformSnapshot;
+  readonly previousInstances: InstancesSnapshot | undefined;
+  readonly previousSkin: SkinPaletteSlice | undefined;
+  readonly previousMorphWeights: Float32Array | undefined;
+}
+
 export interface MorphSnapshot {
   readonly weights: Float32Array;
   readonly targetCount: number;
@@ -758,9 +846,9 @@ export interface MaterialSnapshot {
    *
    * Populated by iterating `textureFieldNames`; absent keys mean the
    * paramValue was missing / mis-typed (record falls back to default white).
-   * `emissiveTexture` / `occlusionTexture` are NOT here — they live in the
-   * engine-injection lightmap region (their named fields below feed
-   * `appendInjection('lightmap')`, not the user-region).
+   * `emissiveTexture` / `occlusionTexture` are included here as ordinary
+   * Standard user-region fields; the production layout does not duplicate
+   * them in a lightmap injection region.
    */
   readonly textureHandles?: ReadonlyMap<string, Handle<'TextureAsset', 'shared'>> | undefined;
   /**
@@ -973,6 +1061,12 @@ function appendMaterialDispatchEntries(
 export interface ExtractedFrame {
   readonly cameras: CameraSnapshot[];
   readonly lights: ExtractedLights;
+  /** Resource-owner environment facts selected once at the extract boundary. */
+  readonly environment: EnvironmentFrame | undefined;
+  /** False when the resource-owner world failed environment/fog selection. */
+  readonly environmentReady: boolean;
+  /** One resource-owner volume projection; absent means no authored fog. */
+  readonly volumetricFog?: ExtractedVolumetricFog;
   readonly renderables: RenderableSnapshot[];
   /**
    * Single dispatch list sorted by queue value (ascending, stable sort).
@@ -984,6 +1078,8 @@ export interface ExtractedFrame {
   readonly skylightCount: number;
   readonly skybox: SkyboxSnapshot | undefined;
   readonly skyboxCount: number;
+  /** Resource-owner Fog facts selected once at the frame boundary. */
+  readonly fog: FogFrame | undefined;
   /**
    * feat-20260528-frustum-culling M3 / w11: frustum culling statistics
    * collected during the extract phase. `total` is the count of entities
@@ -1062,6 +1158,10 @@ const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
   'metallicRoughnessTexture',
   'normalTexture',
   'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
 ];
 const BUILTIN_USER_REGION_TEXTURE_FIELD_SET = new Set(BUILTIN_USER_REGION_TEXTURE_FIELDS);
 const BUILTIN_BASE_COLOR_TEXTURE_FIELD_SET = new Set(['baseColorTexture']);
@@ -1350,11 +1450,11 @@ function collectMaterialTextureSamplers(
  * `AssetRegistry.materialShaderTextureFieldNames`). Each declared texture
  * field whose paramValue resolves to a handle lands in the returned map keyed
  * by field name; this is the single path through which an arbitrary number of user-region
- * textures (4 standard or 5+ custom, e.g. parallax `heightTexture`) flow.
+ * textures (8 Standard or 9+ custom, e.g. parallax `heightTexture`) flow.
  *
- * When the shader is not registered the built-in 4-field set is used so
- * standard materials still resolve. `emissiveTexture` / `occlusionTexture`
- * are engine-injection (lightmap) textures and are NOT part of this set.
+ * When the shader is not registered the built-in Standard field set is used
+ * so standard materials still resolve. Emissive and occlusion are ordinary
+ * schema-driven user-region textures in that set.
  *
  * feat-20260623-world-space-video-asset M4 / w14 (D-5): a field whose paramValue
  * catalogues to a VideoAsset is routed into `videoOut` (a VideoAsset-branded
@@ -1665,8 +1765,7 @@ export function resolveMaterialSnapshot(
   // feat-20260621-learn-render-5-5-parallax M2 / w7 (D-3): iterate the
   // shader's derive(paramSchema).textureFieldNames SSOT instead of a hardcoded
   // user-region field list, so an Nth texture (e.g. parallax heightTexture)
-  // resolves through the same path. emissive/occlusion are engine-injection
-  // (lightmap) textures, NOT in textureFieldNames, so they keep named reads.
+  // resolves through the same path, including emissive/occlusion fields.
   const videoTextureFields = new Map<string, Handle<'VideoAsset', 'shared'>>();
   const textureHandles = collectUserRegionTextureHandles(
     pv,
@@ -2192,59 +2291,15 @@ export interface PreparedExtractContext {
   readonly assets: AssetRegistry | null | undefined;
   readonly pipelineState: ExtractPipelineSurface | null | undefined;
   readonly materialSnapshotCache: MaterialSnapshotCache | undefined;
+  /** `undefined` keeps direct extractFrame's local Fog semantics; `null` means
+   * the frame owner already selected that no Fog is present for this world. */
+  readonly resourceOwnerFog: FogFrame | null | undefined;
   readonly cull: 'self' | 'none' | 'external';
   readonly cullCameras: readonly CameraSnapshot[] | undefined;
   readonly hierarchy: SceneHierarchySnapshot;
   readonly visibility: VisibilitySnapshot;
 }
 
-export function extractCameraSnapshots(world: World): CameraSnapshot[] {
-  const worldInternal = createWorldInternalView(world);
-  const cameras: CameraSnapshot[] = [];
-  const cameraEntities: number[] = [];
-  const cameraQuery = world.query({ read: [Camera], with: [Transform] }).unwrap();
-  for (const row of cameraQuery) {
-    const cam = row.get(Camera);
-    const entity = row.entity;
-    const view = worldInternal._getArrayView(entity, Transform, 'world');
-    if (view === undefined) continue;
-    const worldMat = new Float32Array(view);
-    cameras.push({
-      entityKey: entity as number,
-      position: mat4.getTranslation(vec3.create(), worldMat),
-      world: worldMat,
-      fov: cam.fov,
-      aspect: cam.aspect,
-      near: cam.near,
-      far: cam.far,
-      projection: cameraProjectionFromF32(cam.projection),
-      orthoLeft: cam.left,
-      orthoRight: cam.right,
-      orthoBottom: cam.bottom,
-      orthoTop: cam.top,
-      tonemap: tonemapFromF32(cam.tonemap),
-      exposure: cam.exposure,
-      whitePoint: cam.whitePoint,
-      antialias: antialiasFromF32(cam.antialias),
-      bloom: bloomEnabledFromF32(cam.bloom),
-      bloomThreshold: cam.bloomThreshold,
-      bloomIntensity: cam.bloomIntensity,
-      bloomBlurRadius: cam.bloomBlurRadius,
-      clearColor: [
-        cam.clearColor[0] ?? 0,
-        cam.clearColor[1] ?? 0,
-        cam.clearColor[2] ?? 0,
-        cam.clearColor[3] ?? 1,
-      ],
-    });
-    cameraEntities.push(entity as number);
-  }
-  const activeCameraIndex = selectActiveCameraIndex(cameraEntities, getActiveCamera(world)?.entity);
-  if (activeCameraIndex < 0) return cameras;
-  const selected = cameras[activeCameraIndex];
-  return selected === undefined ? cameras : [selected];
-}
-
 function tonemapParams(camera: CameraSnapshot): Uint8Array {
   const bytes = new ArrayBuffer(16);
   const floats = new Float32Array(bytes);
@@ -2261,6 +2316,7 @@ export function prepareExtractContext(
     readonly assets?: AssetRegistry | null;
     readonly pipelineState?: ExtractPipelineSurface | null;
     readonly materialSnapshotCache?: MaterialSnapshotCache;
+    readonly resourceOwnerFog?: FogFrame | null;
     readonly cull?: 'self' | 'none' | 'external';
     readonly cullCameras?: readonly CameraSnapshot[];
   } = {},
@@ -2270,6 +2326,7 @@ export function prepareExtractContext(
     assets: options.assets,
     pipelineState: options.pipelineState,
     materialSnapshotCache: options.materialSnapshotCache,
+    resourceOwnerFog: options.resourceOwnerFog,
     cull: options.cull ?? 'self',
     cullCameras: options.cullCameras,
     hierarchy,
@@ -2277,6 +2334,213 @@ export function prepareExtractContext(
   };
 }
 
+const fogQueries = new WeakMap<World, Query<readonly [typeof Fog]>>();
+
+function selectFogFrame(world: World): FogFrame | undefined {
+  // Query compilation is owned once per World; Query refreshes its matched
+  // tables when the ECS structure changes, while iteration reads current Fog
+  // values. This keeps the frame boundary free of repeated descriptor work.
+  const fogCandidates: FogCandidate[] = [];
+  let fogQuery = fogQueries.get(world);
+  if (fogQuery === undefined) {
+    fogQuery = world.query({ read: [Fog] }).unwrap();
+    fogQueries.set(world, fogQuery);
+  }
+  for (const row of fogQuery) {
+    const value = row.get(Fog);
+    fogCandidates.push({
+      entityKey: row.entity,
+      color: [value.color[0] ?? 0, value.color[1] ?? 0, value.color[2] ?? 0],
+      density: value.density,
+      heightFalloff: value.heightFalloff,
+      maxOpacity: value.maxOpacity,
+    });
+  }
+  const fogSelection = selectEnvironment({
+    environments: [],
+    fogs: fogCandidates,
+    suns: [],
+    lane: 'direct',
+  });
+  if (fogSelection.ok) return fogSelection.value.fog;
+  routeWorldError(world, fogSelection.error, {
+    systemName: 'RenderSystem.extract (fog-selection)',
+  });
+  throw fogSelection.error;
+}
+
+function textureDigest(texture: TextureAsset): string {
+  // The render inspection needs a stable identity token, not a second byte
+  // store.  FNV-1a is deterministic, synchronous, and deliberately labelled
+  // as a non-cryptographic digest so it cannot be mistaken for Catalog proof.
+  let hash = 2166136261;
+  for (const byte of texture.data) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+  return `fnv1a:${hash.toString(16).padStart(8, '0')}`;
+}
+
+function extractVolumeSnapshot(
+  world: World,
+  assets: AssetRegistry | null | undefined,
+  worldInternal: WorldInternalView,
+): ExtractedVolumetricFog | undefined {
+  const query = world.query({ read: [VolumetricFog] }).unwrap();
+  const authorings: VolumetricFogAuthoring[] = [];
+  let selectedLight:
+    | {
+        readonly entity: EntityHandle;
+        readonly kind: 'directional' | 'point' | 'spot';
+        readonly pointLightEntity?: EntityHandle;
+        readonly spotLightEntity?: EntityHandle;
+      }
+    | undefined;
+  let first:
+    | {
+        readonly densityHandle: Handle<'TextureAsset', 'shared'>;
+        readonly densityAsset: TextureAsset;
+        readonly guid: string;
+      }
+    | undefined;
+
+  for (const row of query) {
+    const source = row.get(VolumetricFog);
+    if (source.light === null) continue;
+    const selected = resolveSelectedVolumetricLight(world, source.light);
+    if (selected.status === 'available') {
+      const pairSpot = source.spotLight === null ? undefined : source.spotLight;
+      selectedLight ??= {
+        entity: selected.entity,
+        kind: selected.kind,
+        ...(selected.kind === 'point' ? { pointLightEntity: selected.entity } : {}),
+        ...(pairSpot === undefined ? {} : { spotLightEntity: pairSpot }),
+      };
+    }
+    const densityHandle = toShared<'TextureAsset'>(Math.round(Number(source.density)));
+    const resolved = resolveAssetHandle<TextureAsset>(world, densityHandle);
+    if (!resolved.ok || resolved.value.kind !== 'texture') {
+      worldInternal._routeError(
+        resolved.ok
+          ? new RhiError({
+              code: 'asset-not-registered',
+              expected: 'VolumetricFog.density resolves to a TextureAsset',
+              hint: 'load a TextureAsset before assigning it to VolumetricFog.density',
+              detail: { assetHandle: Number(densityHandle) },
+            })
+          : resolved.error,
+        { severity: Severity.Error, systemName: 'RenderSystem.extract (volumetric-density)' },
+      );
+      return { status: 'degraded' };
+    }
+    const densityAsset = resolved.value;
+    const guid = assets?.guidOf(densityAsset) ?? `handle:${Number(densityHandle)}`;
+    const shape = densityAsset.shape;
+    const density: VolumeDensityBinding =
+      shape.viewDimension === '3d'
+        ? {
+            guid,
+            generation: 1,
+            shape: {
+              viewDimension: '3d',
+              extent: {
+                width: shape.extent.width,
+                height: shape.extent.height,
+                depth: shape.extent.depth,
+              },
+            },
+            format: densityAsset.format,
+            colorSpace: densityAsset.colorSpace,
+          }
+        : {
+            guid,
+            generation: 1,
+            shape: {
+              viewDimension: shape.viewDimension,
+              extent:
+                shape.viewDimension === '2d-array'
+                  ? {
+                      width: shape.extent.width,
+                      height: shape.extent.height,
+                      layers: shape.extent.layers,
+                    }
+                  : { width: shape.extent.width, height: shape.extent.height },
+            },
+            format: densityAsset.format,
+            colorSpace: densityAsset.colorSpace,
+          };
+    const authoring: VolumetricFogAuthoring = {
+      light: source.light,
+      density,
+      bounds: {
+        min: [source.boundsMin[0] ?? 0, source.boundsMin[1] ?? 0, source.boundsMin[2] ?? 0],
+        max: [source.boundsMax[0] ?? 0, source.boundsMax[1] ?? 0, source.boundsMax[2] ?? 0],
+      },
+      extinction: [source.extinction[0] ?? 0, source.extinction[1] ?? 0, source.extinction[2] ?? 0],
+      albedo: [source.albedo[0] ?? 0, source.albedo[1] ?? 0, source.albedo[2] ?? 0],
+      emission: [source.emission[0] ?? 0, source.emission[1] ?? 0, source.emission[2] ?? 0],
+      anisotropy: source.anisotropy,
+      maxDistance: source.maxDistance,
+    };
+    authorings.push(authoring);
+    first ??= { densityHandle, densityAsset, guid };
+  }
+
+  if (authorings.length === 0) return undefined;
+  const extracted = extractVolumetricFog(authorings);
+  if (!extracted.ok) {
+    worldInternal._routeError(extracted.error, {
+      severity: Severity.Error,
+      systemName: 'RenderSystem.extract (volumetric-fog)',
+    });
+    return {
+      status: 'degraded',
+      ...(first === undefined
+        ? {}
+        : {
+            densityHandle: first.densityHandle,
+            densityAsset: first.densityAsset,
+            guid: first.guid,
+            generation: 1,
+            digest: textureDigest(first.densityAsset),
+            ...(selectedLight === undefined
+              ? {}
+              : {
+                  lightEntity: selectedLight.entity,
+                  lightKind: selectedLight.kind,
+                  ...(selectedLight.pointLightEntity === undefined
+                    ? {}
+                    : { pointLightEntity: selectedLight.pointLightEntity }),
+                  ...(selectedLight.spotLightEntity === undefined
+                    ? {}
+                    : { spotLightEntity: selectedLight.spotLightEntity }),
+                }),
+          }),
+    };
+  }
+  if (extracted.value.status === 'off' || first === undefined) return { status: 'off' };
+  const selectedLightFields =
+    selectedLight === undefined
+      ? {}
+      : {
+          lightEntity: selectedLight.entity,
+          lightKind: selectedLight.kind,
+          ...(selectedLight.pointLightEntity === undefined
+            ? {}
+            : { pointLightEntity: selectedLight.pointLightEntity }),
+          ...(selectedLight.spotLightEntity === undefined
+            ? {}
+            : { spotLightEntity: selectedLight.spotLightEntity }),
+        };
+  return {
+    status: 'available',
+    fog: extracted.value.fog,
+    densityHandle: first.densityHandle,
+    densityAsset: first.densityAsset,
+    guid: first.guid,
+    generation: 1,
+    digest: textureDigest(first.densityAsset),
+    ...selectedLightFields,
+  };
+}
+
 export function extractFrames(
   worlds: readonly World[],
   owner: number | ExtractFramesOwner,
@@ -2304,6 +2568,12 @@ export function extractFrames(
   }
 
   const failedWorlds = new Set<World>();
+  // Resource-owner selection is a frame-level concern. Select Fog once before
+  // per-world extraction so non-owner worlds do not scan their ECS tables for
+  // a value that the merge layer will discard.
+  const resourceOwnerWorld = worlds[resourceOwner];
+  const resourceOwnerFog =
+    resourceOwnerWorld === undefined ? null : (selectFogFrame(resourceOwnerWorld) ?? null);
   // ── D-2: per-world extract with error isolation ────────────────────────
   //
   // Each world runs extractFrame over the final state published by
@@ -2334,6 +2604,7 @@ export function extractFrames(
       const prepared = prepareExtractContext(world, {
         ...(assets !== undefined ? { assets } : {}),
         ...(pipelineState !== undefined ? { pipelineState } : {}),
+        resourceOwnerFog: wi === resourceOwner ? resourceOwnerFog : null,
         ...(materialSnapshotCachesByWorld === undefined
           ? {}
           : {
@@ -2527,10 +2798,13 @@ export function extractFrames(
     directionalCsmConfig,
     directionalCsmDirection,
   };
+  const volumetricFog = resourceOwnerFrame?.volumetricFog;
   const skylight = resourceOwnerFrame?.skylight;
   const skylightCount = resourceOwnerFrame?.skylightCount ?? 0;
   const skybox = resourceOwnerFrame?.skybox;
   const skyboxCount = resourceOwnerFrame?.skyboxCount ?? 0;
+  const fog = resourceOwnerFrame?.fog;
+  const environment = resourceOwnerFrame?.environment;
   // User-authored PostProcessParams entities are singleton scene resources, so
   // they come from the resourceOwner world (holistic snapshot selection).
   const postProcessParams = new Map(resourceOwnerFrame?.postProcessParams);
@@ -2549,16 +2823,16 @@ export function extractFrames(
   // cameraOwner === resourceOwner this is a no-op (identical entry). The 'na'
   // Standard tonemap identity mirrors the engine provider key set at the
   // bottom of extractFrame (SSOT: same identity, same 16B layout).
-  const TONEMAP_PARAM_KEY = STANDARD_TONEMAP_FEATURE_ID;
-  const cameraTonemapParam = cameraOwnerFrame?.postProcessParams.get(TONEMAP_PARAM_KEY);
+  const OUTPUT_TRANSFORM_PARAM_KEY = STANDARD_OUTPUT_TRANSFORM_FEATURE_ID;
+  const cameraTonemapParam = cameraOwnerFrame?.postProcessParams.get(OUTPUT_TRANSFORM_PARAM_KEY);
   if (cameraTonemapParam !== undefined) {
-    postProcessParams.set(TONEMAP_PARAM_KEY, cameraTonemapParam);
+    postProcessParams.set(OUTPUT_TRANSFORM_PARAM_KEY, cameraTonemapParam);
   } else {
     // The camera-owner world produced no tonemap param (no Camera surfaced
     // there this frame); do not leave a stale resource-owner entry that would
     // apply a foreign camera's exposure. Removing it lets the tonemap pass fall
     // back to its param-less zero path only when genuinely no camera exists.
-    postProcessParams.delete(TONEMAP_PARAM_KEY);
+    postProcessParams.delete(OUTPUT_TRANSFORM_PARAM_KEY);
   }
 
   // D-3: frustumStats — culled/total summed across worlds.
@@ -2573,12 +2847,18 @@ export function extractFrames(
   return {
     cameras,
     lights,
+    ...(volumetricFog === undefined
+      ? {}
+      : { volumetricFog: { ...volumetricFog, worldId: resourceOwner } }),
     renderables,
     dispatch: dispatchEntries,
     skylight,
     skylightCount,
     skybox,
     skyboxCount,
+    fog,
+    environment,
+    environmentReady: resourceOwnerFrame !== undefined && environment !== undefined,
     frustumStats,
     visibilityStats,
     postProcessParams,
@@ -2666,7 +2946,12 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     pipelineState,
     materialSnapshotCache: persistentMaterialSnapshotCache,
     cull: cullMode,
+    resourceOwnerFog,
   } = context;
+  // Environment reads are owned by the retained resource projection and are
+  // established at the frame boundary; record never revisits World state.
+  const fog =
+    resourceOwnerFog === undefined ? selectFogFrame(world) : (resourceOwnerFog ?? undefined);
   const visibility = context.visibility.hasAnyHiddenIntent ? context.visibility : undefined;
   const skinPaletteAllocator = pipelineState?.skinPaletteAllocator ?? null;
 
@@ -2684,6 +2969,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // `row.get(X) !== undefined`); K-3 invariant preserved (`_getArrayView`
   // calls survive untouched, only the entity source changes).
   const worldInternal = createWorldInternalView(world);
+  let volumetricFog = extractVolumeSnapshot(world, assets, worldInternal);
 
   const cameras = extractCameraSnapshots(world);
 
@@ -2715,6 +3001,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     const intensity = l.intensity;
     const snapshot: DirectionalLightSnapshot = {
       kind: 'directional',
+      entity: row.entity,
       direction: vec3.create(l.direction[0] ?? 0, l.direction[1] ?? -1, l.direction[2] ?? 0),
       color: vec3.create(
         (l.color[0] ?? 1) * intensity,
@@ -2770,6 +3057,7 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       worldMat !== undefined ? mat4.getTranslation(vec3.create(), worldMat) : vec3.create(0, 0, 0);
     pointSnapshots.push({
       kind: 'point',
+      entity: entityId,
       position,
       color: vec3.create(
         (p.color[0] ?? 1) * intensity,
@@ -2841,11 +3129,20 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     const sMapSize = s.mapSize;
     const sNearPlane = s.nearPlane;
     const sFarPlane = s.farPlane;
+    const shadowIntensity = s.shadowIntensity;
+    // `shared<T>` columns are u32-backed and zero-filled when the optional
+    // field is absent. Treat only a positive handle as an authored projector;
+    // checking nullish values alone would turn the zero sentinel into a
+    // phantom projector matrix and an avoidable asset-not-found diagnostic.
+    const hasProjector = Number(s.projector) > 0;
 
     let lightViewProj: Float32Array | undefined;
     let shadowAtlasTile = -1;
 
-    if (castShadow && hasValidDirection) {
+    // A projector needs the same perspective transform even when its SpotLight
+    // has no shadow atlas tile. The matrix remains a derived light fact; the
+    // shadow tile stays -1 so shadow visibility is still independently gated.
+    if ((castShadow || hasProjector) && hasValidDirection) {
       const target = vec3.create(
         (position[0] ?? 0) + (dirN[0] ?? 0),
         (position[1] ?? 0) + (dirN[1] ?? 0),
@@ -2864,14 +3161,40 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       mat4.multiply(lightViewProj as Mat4, proj, view);
 
       // D-4: allocate tile 0..3; 5th+ = -1 sentinel.
-      if (spotTileNext < 4) {
+      if (castShadow && spotTileNext < 4) {
         shadowAtlasTile = spotTileNext;
         spotTileNext += 1;
       }
     }
 
+    let projectorHandle: Handle<'TextureAsset', 'shared'> | undefined;
+    let projectorAsset: TextureAsset | undefined;
+    let projectorGuid: string | undefined;
+    if (hasProjector) {
+      const candidate = toShared<'TextureAsset'>(Math.round(Number(s.projector)));
+      const resolvedProjector = resolveAssetHandle<TextureAsset>(world, candidate);
+      if (!resolvedProjector.ok || resolvedProjector.value.kind !== 'texture') {
+        worldInternal._routeError(
+          resolvedProjector.ok
+            ? new RhiError({
+                code: 'asset-not-registered',
+                expected: 'SpotLight.projector resolves to a TextureAsset',
+                hint: 'load the authored projector TextureAsset before assigning SpotLight.projector',
+                detail: { assetHandle: Number(candidate) },
+              })
+            : resolvedProjector.error,
+          { severity: Severity.Error, systemName: 'RenderSystem.extract (spot-projector)' },
+        );
+      } else {
+        projectorHandle = candidate;
+        projectorAsset = resolvedProjector.value;
+        projectorGuid = assets?.guidOf(projectorAsset) ?? `handle:${Number(candidate)}`;
+      }
+    }
+
     spotSnapshots.push({
       kind: 'spot',
+      entity: row.entity,
       // D-6: position reflects world transform; direction stays sourced
       // from SpotLight.direction (NOT rotated by the parent).
       position,
@@ -2892,9 +3215,59 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
       nearPlane: sNearPlane,
       farPlane: sFarPlane,
       shadowAtlasTile,
+      shadowIntensity,
+      depthBias: s.depthBias,
+      normalBias: s.normalBias,
+      pcfKernelSize: s.pcfKernelSize,
+      ...(projectorHandle === undefined ||
+      projectorAsset === undefined ||
+      projectorGuid === undefined
+        ? {}
+        : {
+            projectorHandle,
+            projectorAsset,
+            projectorGuid,
+            projectorGeneration: 1,
+            projectorRevision: 1,
+          }),
     });
   }
 
+  // The SpotLight is the sole projector owner. Once all light snapshots have
+  // been extracted, publish its accepted TextureAsset tuple on the volume
+  // snapshot so surface and volume consume the same identity and revision.
+  let volumeSpot: SpotLightSnapshot | undefined;
+  const extractedFog = volumetricFog;
+  if (extractedFog !== undefined) {
+    if (extractedFog.spotLightEntity !== undefined) {
+      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.spotLightEntity);
+    } else if (extractedFog.lightKind === 'spot') {
+      volumeSpot = spotSnapshots.find((light) => light.entity === extractedFog.lightEntity);
+    }
+  }
+  if (
+    volumetricFog !== undefined &&
+    volumetricFog.status === 'available' &&
+    volumeSpot?.projectorAsset !== undefined &&
+    volumeSpot.projectorHandle !== undefined
+  ) {
+    const projectorHandle = volumeSpot.projectorHandle;
+    const projectorAsset = volumeSpot.projectorAsset;
+    volumetricFog = {
+      ...volumetricFog,
+      projector: {
+        guid: volumeSpot.projectorGuid ?? `handle:${Number(volumeSpot.projectorHandle)}`,
+        generation: volumeSpot.projectorGeneration ?? 1,
+        view: '2d',
+        sampler: 'linear-clamp-to-edge',
+        projection: 'spot-projection',
+        revision: volumeSpot.projectorRevision ?? 1,
+      },
+      projectorHandle,
+      projectorAsset,
+    };
+  }
+
   // bug-20260710-editor-cross-world-shadow: CSM matrices are computed by the
   // shared pure {@link computeDirectionalCsm}, called here per-world with THIS
   // world's own `cameras[0]`. In a single-world app the light and camera share
@@ -3144,6 +3517,79 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
     }
   }
 
+  const environmentCandidates: EnvironmentCandidate[] = [];
+  const imageEnvironment =
+    skylight?.equirectHandle !== undefined && skylight.equirectHandle > 0
+      ? skylight
+      : skybox?.equirectHandle !== undefined && skybox.equirectHandle > 0
+        ? skybox
+        : undefined;
+  if (imageEnvironment !== undefined) {
+    environmentCandidates.push({
+      kind: 'image',
+      entityKey: imageEnvironment.entityHandle,
+      sourceKey: `equirect:${imageEnvironment.equirectHandle}`,
+    });
+  }
+  const atmosphereQuery = world.query({ read: [Atmosphere] }).unwrap();
+  for (const row of atmosphereQuery) {
+    const value = row.get(Atmosphere);
+    const atmosphere = {
+      turbidity: value.turbidity,
+      rayleigh: value.rayleigh,
+      mieCoefficient: value.mieCoefficient,
+      mieDirectionalG: value.mieDirectionalG,
+      sunAngularRadius: value.sunAngularRadius,
+    } as const;
+    environmentCandidates.push({
+      kind: 'atmosphere',
+      entityKey: row.entity,
+      sourceKey: `atmosphere:${row.entity}`,
+      atmosphere,
+    });
+  }
+  const directionalDirection = directional?.direction;
+  const directionalLength =
+    directionalDirection === undefined
+      ? 0
+      : Math.hypot(
+          directionalDirection[0] ?? 0,
+          directionalDirection[1] ?? 0,
+          directionalDirection[2] ?? 0,
+        );
+  const sun =
+    directional === undefined || directionalLength <= 1e-6
+      ? []
+      : [
+          {
+            entityKey: 0,
+            direction: [
+              -(directionalDirection?.[0] ?? 0) / directionalLength,
+              -(directionalDirection?.[1] ?? 0) / directionalLength,
+              -(directionalDirection?.[2] ?? 0) / directionalLength,
+            ] as [number, number, number],
+            color: [
+              directional.color[0] ?? 0,
+              directional.color[1] ?? 0,
+              directional.color[2] ?? 0,
+            ] as [number, number, number],
+            intensity: directional.intensity,
+          },
+        ];
+  const environmentSelection = selectEnvironment({
+    environments: environmentCandidates,
+    fogs: fog === undefined ? [] : [fog],
+    suns: sun,
+    lane: 'direct',
+  });
+  if (!environmentSelection.ok) {
+    routeWorldError(world, environmentSelection.error, {
+      systemName: 'RenderSystem.extract (environment-selection)',
+    });
+    throw environmentSelection.error;
+  }
+  const environment: EnvironmentFrame = environmentSelection.value;
+
   // feat-20260528-frustum-culling M3 / w10: precompute per-camera frustum
   // planes so entities can be tested against all cameras in the inner loop.
   // Cameras with degenerate projection parameters (e.g. zero fov, zero aspect)
@@ -4541,18 +4987,22 @@ export function extractFrame(world: World, context: PreparedExtractContext): Ext
   // recordFrame's `activeCameras[0]` selection.
   const tonemapCamera = cameras[0];
   if (tonemapCamera !== undefined) {
-    postProcessParams.set(STANDARD_TONEMAP_FEATURE_ID, tonemapParams(tonemapCamera));
+    postProcessParams.set(STANDARD_OUTPUT_TRANSFORM_FEATURE_ID, tonemapParams(tonemapCamera));
   }
 
   return {
     cameras,
     lights,
+    environment,
+    environmentReady: true,
+    ...(volumetricFog === undefined ? {} : { volumetricFog }),
     renderables,
     dispatch,
     skylight,
     skylightCount,
     skybox,
     skyboxCount,
+    fog,
     frustumStats: { culled: frustumCulled, total: frustumTotal },
     visibilityStats: { explicitlyHidden: explicitlyHidden.size },
     postProcessParams,