@waica/engine 0.30.1 → 0.31.1

package/dist/game-shadows.js

@@ -0,0 +1,260 @@
+import * as THREE from 'three/webgpu';
+import { PointLight } from './components/point-light.js';
+import { Sun } from './components/sun.js';
+import { assertShadowMapCapacity, resolveLightShadow, resolveSceneShadows } from './scene-shadows.js';
+import { advanceRendererFrame, shadowTextureLimit } from './shadow-renderer.js';
+import { createRangedPointShadow } from './point-shadow.js';
+import { fitSunShadow, sunCoverageDepth } from './sun-shadow-camera.js';
+import { registryEntry, resolveEntityComponents, resolveProps, sceneProps } from './scene.js';
+import { resolvePerspectiveCamera } from './scene-camera-3d.js';
+function isShadowClass(Class) {
+    return Class !== undefined && (Class === Sun || Class === PointLight || Class.prototype instanceof Sun || Class.prototype instanceof PointLight);
+}
+function hasCoverage(light, camera, maxDistance) {
+    return !(light instanceof Sun) || (camera !== null && sunCoverageDepth(camera, maxDistance) !== null);
+}
+/** Detached lights compose normalized authored defaults/props/params without intermediate capacity checks. */
+function* sceneLights(scene, registry, params) {
+    for (const entity of scene.entities) {
+        for (const json of resolveEntityComponents(entity, registry.prefabs)) {
+            const Class = registryEntry(registry.components, json.type);
+            if (!isShadowClass(Class))
+                continue;
+            let light;
+            try {
+                light = new Class();
+                Object.assign(light, sceneProps(resolveProps(json.props, registry), json.type, entity.name), params[entity.name]?.[Class.componentName]);
+            }
+            catch {
+                // Preserve spawnFromJson's isolation of throwing project-owned components.
+                continue;
+            }
+            yield light;
+        }
+    }
+}
+/** The live scene's shadow policy; resolving settings never allocates a shadow map. */
+export class GameShadows {
+    game;
+    state = resolveSceneShadows(undefined);
+    renderer = null;
+    pointShadows = new Map();
+    composing = new WeakSet();
+    lastValid = new WeakMap();
+    capacityErrors = new WeakMap();
+    lastRendererFrame = null;
+    constructor(game) {
+        this.game = game;
+    }
+    connect(renderer) {
+        this.renderer = renderer;
+    }
+    get policy() {
+        return { ...this.state };
+    }
+    get quality() {
+        return this.state.quality;
+    }
+    set quality(value) {
+        this.adopt(resolveSceneShadows({ ...this.state, quality: value }));
+    }
+    get maxDistance() {
+        return this.state.maxDistance;
+    }
+    set maxDistance(value) {
+        this.adopt(resolveSceneShadows({ ...this.state, maxDistance: value }));
+    }
+    loadScene(value) {
+        this.adopt(resolveSceneShadows(value));
+        if (this.game.space !== '3d')
+            for (const light of this.lights())
+                this.remove(light);
+    }
+    unloadScene() {
+        this.state = resolveSceneShadows(undefined);
+        if (this.renderer)
+            this.renderer.shadowMap.enabled = false;
+    }
+    /** Validate final composed props, before Entity.add publishes or readies a light. */
+    validateAddition(component) {
+        if (component instanceof Sun || component instanceof PointLight)
+            this.assertCapacity(this.requested(component));
+    }
+    /** Check the ready device, even for authored 3D settings in a 2D preview. */
+    assertCapacity(settings) {
+        if (!this.renderer || !this.game.backend)
+            return;
+        assertShadowMapCapacity(settings, shadowTextureLimit(this.renderer.backend));
+    }
+    /** Persisted params are one composed request, not a sequence of active setters. */
+    applyParams(component, props) {
+        this.validateChange(component, props);
+        this.composing.add(component);
+        try {
+            Object.assign(component, props);
+        }
+        finally {
+            this.composing.delete(component);
+        }
+    }
+    /** Check an incoming scene before unloadScene destroys the last valid one. */
+    validateScene(scene, registry) {
+        if (scene.render?.space !== '3d' || !this.game.backend)
+            return;
+        const policy = resolveSceneShadows(scene.render.shadows);
+        const camera = this.game.cameraRig.viewCamera ?? resolvePerspectiveCamera(scene.camera?.kind === 'perspective' ? scene.camera : undefined);
+        for (const light of sceneLights(scene, registry, this.game.paramOverrides)) {
+            const settings = resolveLightShadow(light instanceof Sun ? 'sun' : 'point', policy, light);
+            settings.enabled = settings.enabled && hasCoverage(light, camera, settings.maxDistance);
+            this.assertCapacity(settings);
+        }
+    }
+    /** A failing request leaves both the authored live value and its active map unchanged. */
+    validateChange(component, change) {
+        if (this.composing.has(component))
+            return;
+        const light = this.lights().find((candidate) => candidate === component);
+        if (!light || !this.renderer || !this.game.backend || this.game.space !== '3d')
+            return;
+        const inputs = {
+            castShadows: light.castShadows, shadowMapSize: light.shadowMapSize,
+            shadowMaxDistance: light.shadowMaxDistance, shadowBias: light.shadowBias,
+            shadowNormalBias: light.shadowNormalBias, shadowRadius: light.shadowRadius,
+            distance: light instanceof PointLight ? light.distance : undefined,
+            ...change,
+        };
+        const settings = this.withCoverage(light, resolveLightShadow(light instanceof Sun ? 'sun' : 'point', this.state, inputs));
+        assertShadowMapCapacity(settings, shadowTextureLimit(this.renderer.backend));
+    }
+    validate() {
+        this.validatePolicy(this.state);
+    }
+    resolve(light) {
+        const settings = this.effectiveSettings(light, this.requested(light));
+        if (settings.enabled)
+            this.lastValid.set(light, settings);
+        return settings;
+    }
+    requested(light) {
+        const settings = resolveLightShadow(light instanceof Sun ? 'sun' : 'point', this.state, light);
+        return this.withCoverage(light, settings);
+    }
+    effectiveSettings(component, requested) {
+        try {
+            this.assertCapacity(requested);
+            this.capacityErrors.delete(component);
+            return requested;
+        }
+        catch (error) {
+            if (!(error instanceof RangeError))
+                throw error;
+            if (this.capacityErrors.get(component) !== error.message) {
+                console.error(`[waica] shadow request rejected for "${component.entity.name}": ${error.message} Keeping the last supported shadow configuration, or no map if none exists.`);
+                this.capacityErrors.set(component, error.message);
+            }
+            const previous = this.lastValid.get(component);
+            return previous && this.renderer && previous.mapSize <= shadowTextureLimit(this.renderer.backend)
+                ? this.withCoverage(component, previous)
+                : { ...requested, enabled: false };
+        }
+    }
+    /** Called at the render boundary, including paused and edit-mode frames. */
+    sync(renderer) {
+        if (this.game.space !== '3d') {
+            renderer.shadowMap.enabled = false;
+            return;
+        }
+        this.lastRendererFrame = advanceRendererFrame(renderer, this.lastRendererFrame);
+        this.game.scene.updateWorldMatrix(true, false);
+        this.game.camera.updateWorldMatrix(true, false);
+        renderer.shadowMap.enabled = this.game.space === '3d' && this.state.quality !== 'off';
+        renderer.shadowMap.type = THREE.PCFShadowMap;
+        const lights = this.lights();
+        for (const component of this.pointShadows.keys()) {
+            if (!lights.includes(component))
+                this.remove(component);
+        }
+        for (const component of lights)
+            this.syncLight(component);
+    }
+    syncLight(component) {
+        const light = component.light;
+        if (!light)
+            return;
+        const settings = this.resolve(component);
+        if ((light.castShadow || light.shadow.map) && !settings.enabled) {
+            this.remove(component);
+        }
+        light.castShadow = settings.enabled;
+        light.shadow.mapSize.set(settings.mapSize, settings.mapSize);
+        // setSize retires GPU storage while preserving nodes held by cached materials.
+        light.shadow.map?.setSize(settings.mapSize, settings.mapSize);
+        light.shadow.bias = settings.bias;
+        light.shadow.normalBias = settings.normalBias;
+        light.shadow.radius = settings.radius;
+        if (component instanceof Sun)
+            this.fitSun(component, settings);
+        if (component instanceof PointLight && settings.enabled)
+            this.syncPoint(component, settings);
+    }
+    /** Prepare host overlays from the same current fit, without allocating or rendering. */
+    prepareSunCamera(component) {
+        const light = component.light;
+        if (!light)
+            return null;
+        this.game.scene.updateWorldMatrix(true, false);
+        this.game.camera.updateWorldMatrix(true, false);
+        return this.fitSun(component, this.resolve(component)) ? light.shadow.camera : null;
+    }
+    fitSun(component, settings) {
+        const camera = this.game.camera;
+        if (!component.light || !(camera instanceof THREE.PerspectiveCamera))
+            return false;
+        return fitSunShadow({ light: component.light, camera, settings, direction: component.direction });
+    }
+    syncPoint(component, settings) {
+        if (!component.light)
+            return;
+        let adapter = this.pointShadows.get(component);
+        if (!adapter) {
+            adapter = createRangedPointShadow(component.light);
+            this.pointShadows.set(component, adapter);
+        }
+        adapter.sync(settings.maxDistance);
+    }
+    withCoverage(light, settings) {
+        const camera = this.game.camera;
+        const enabled = this.game.space === '3d' && settings.enabled
+            && hasCoverage(light, camera instanceof THREE.PerspectiveCamera ? camera : null, settings.maxDistance);
+        return { ...settings, enabled };
+    }
+    /** Notify Three's analytic light node as well as disposing the exposed target. */
+    remove(component) {
+        if (component instanceof PointLight) {
+            this.pointShadows.get(component)?.dispose();
+            this.pointShadows.delete(component);
+        }
+        const light = component.light;
+        if (!light)
+            return;
+        light.dispose();
+        light.shadow.map = null;
+        light.castShadow = false;
+    }
+    adopt(policy) {
+        this.validatePolicy(policy);
+        this.state = policy;
+    }
+    validatePolicy(policy) {
+        if (!this.renderer || !this.game.backend || this.game.space !== '3d')
+            return;
+        const limit = shadowTextureLimit(this.renderer.backend);
+        for (const light of this.lights()) {
+            const settings = resolveLightShadow(light instanceof Sun ? 'sun' : 'point', policy, light);
+            assertShadowMapCapacity(this.withCoverage(light, settings), limit);
+        }
+    }
+    lights() {
+        return this.game.entities.flatMap((entity) => entity.components.filter((component) => component instanceof Sun || component instanceof PointLight));
+    }
+}

package/dist/game.d.ts

@@ -13,6 +13,7 @@ import { Entity } from './entity.js';
 import type { PositionJson } from './entity-transform.js';
 import { Emitter } from './events.js';
 import { GameTime } from './game-time.js';
+import { GameShadows } from './game-shadows.js';
 import { Input, type InputBindings } from './input.js';
 import { PhysicsHost } from './physics-3d/physics-host.js';
 import type { PhysicsBackend } from './physics-3d/rapier-module.js';
@@ -122,6 +123,8 @@ export declare class Game {
     readonly time: GameTime;
     /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
     readonly lighting: GameLighting;
+    /** Scene-scoped 3D shadow policy, independent of Ambient Light. */
+    readonly shadows: GameShadows;
     /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
     readonly post: GamePost;
     /** The live 3D scene's Rapier world and bodies (ADR 0028); package-internal, read by the physics components and the Runtime Snapshot. */

package/dist/game.js

@@ -10,8 +10,10 @@ import { Entity } from './entity.js';
 import { EntityUpdateSchedules } from './entity-update-schedules.js';
 import { Emitter } from './events.js';
 import { RigidBody } from './components/rigid-body.js';
+import { ShadowLight } from './components/shadow-light.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
 import { advanceGameTime, GameTime } from './game-time.js';
+import { GameShadows } from './game-shadows.js';
 import { Input } from './input.js';
 import { PhysicsHost } from './physics-3d/physics-host.js';
 import { defaultPlatformBackend } from './platform/desktop-platform-backend.js';
@@ -67,6 +69,8 @@ export class Game {
     time = new GameTime();
     /** The live scene's Ambient Light and Lights (ADR 0026); it dies with its scene. */
     lighting = new GameLighting();
+    /** Scene-scoped 3D shadow policy, independent of Ambient Light. */
+    shadows = new GameShadows(this);
     /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
     post = new GamePost();
     /** The live 3D scene's Rapier world and bodies (ADR 0028); package-internal, read by the physics components and the Runtime Snapshot. */
@@ -178,6 +182,7 @@ export class Game {
             pixel: () => (this.resolution ? this.viewHeight / this.resolution.height : null),
         });
         this.renderer = new THREE.WebGPURenderer({ canvas, antialias: true });
+        this.shadows.connect(this.renderer);
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         // The model view on the CPU, as three's WebGL renderer computed it: a Sprite
         // Batch instance carries that same matrix (ADR 0024), so batched and
@@ -211,7 +216,8 @@ export class Game {
      * its first frame (ADR 0025).
      */
     ready() {
-        return this.physics.whenReady(this.readiness.promise);
+        const ready = this.physics.whenReady(this.readiness.promise);
+        return this.sceneSpace === '3d' ? ready.then(() => this.shadows.validate()) : ready;
     }
     /** The Render Backend the renderer settled on; null until ready() resolved. */
     get backend() {
@@ -285,6 +291,7 @@ export class Game {
         this.time.cancelSceneScoped();
         this.cameraEffects.unloadScene();
         this.lighting.unloadScene();
+        this.shadows.unloadScene();
         this.post.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
@@ -376,7 +383,11 @@ export class Game {
     applyParamOverrides(entity, component) {
         const Class = componentClassOf(component);
         const override = this.paramOverrides[entity.name]?.[Class.componentName];
-        if (override)
+        if (!override)
+            return;
+        if (component instanceof ShadowLight)
+            this.shadows.applyParams(component, override);
+        else
             Object.assign(component, override);
     }
     /**
@@ -399,6 +410,7 @@ export class Game {
         this.renderSort = sort;
         this.spriteBatches.enabled = json?.batch !== false;
         this.lighting.loadScene(json);
+        this.shadows.loadScene(json?.shadows);
         this.post.loadScene(json);
         this.physics.enterScene(space);
         if (projection === this.sceneProjection)
@@ -727,6 +739,7 @@ export class Game {
             // Before ready() the frame simulated, but three cannot draw yet.
             if (!this.readiness.isReady)
                 return;
+            this.shadows.sync(this.renderer);
             this.frame.draw();
         }
         finally {

package/dist/index.d.ts

@@ -62,7 +62,7 @@ export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_B
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeBridgeFailure, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export type { RenderBackend } from './render-readiness.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { RuntimeSnapshotLight, RuntimeSnapshotLighting, RuntimeSnapshotPointLight, RuntimeSnapshotSun, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.js';
+export type { RuntimeSnapshotLight, RuntimeSnapshotLightShadows, RuntimeSnapshotLighting, RuntimeSnapshotPointLight, RuntimeSnapshotSun, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotCamera, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, SceneArchetypeNeeds, } from './archetype.js';
 export { sceneArchetypeNeeds } from './archetype.js';
@@ -74,8 +74,8 @@ export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
 export { Model } from './components/model.js';
 export type { ModelShape } from './components/model.js';
-export { Animator } from './components/animator.js';
-export type { AnimatorClipOverride, AnimatorState } from './components/animator.js';
+export { Animator, DEFAULT_BLEND_SMOOTHING } from './components/animator.js';
+export type { AnimatorBlend, AnimatorBlendPoint, AnimatorClipOverride, AnimatorState } from './components/animator.js';
 export { poseHash } from './animation/pose-hash.js';
 export { Sun } from './components/sun.js';
 export { Collider, COLLIDER_SHAPES } from './components/collider.js';
@@ -88,12 +88,15 @@ export type { PhysicsBackend, RapierModule } from './physics-3d/rapier-module.js
 export type { RuntimeSnapshotBody, RuntimeSnapshotPhysics } from './runtime-physics-snapshot.js';
 export { PointLight } from './components/point-light.js';
 export { GameLighting } from './scene-lighting.js';
+export { GameShadows } from './game-shadows.js';
 export type { AmbientLightInput } from './scene-lighting.js';
 export { GamePost } from './post-effects.js';
 export { EMISSIVE_LAYER, setEmissive } from './render-layers.js';
 export { lightFalloff, lightMapValue, lightVisibility } from './light-field.js';
 export type { LightField, OccluderGrid, Rgb } from './light-field.js';
 export { sceneRenderIssues } from './scene-render-options.js';
+export { assertShadowMapCapacity, normalizeShadowBoolean, normalizeShadowOverride, resolveLightShadow, resolveSceneShadows, sceneShadowIssues, shadowComponentIssues, SHADOW_DEFAULTS, SHADOW_MAP_SIZES, SHADOW_OVERRIDE_PARAMS, SHADOW_QUALITIES, } from './scene-shadows.js';
+export type { LightShadowOverrides, ResolvedLightShadow, ResolvedSceneShadows, ShadowOverrideName, } from './scene-shadows.js';
 export type { AmbientLight, ColorGradeEffect, PostEffectsState, SceneRenderIssue, VignetteEffect, } from './scene-render-options.js';
 export { ParticleEmitter } from './components/particle-emitter.js';
 export type { ParticleBlend, ParticleDestroyMode, ParticleOverflow, ParticleSpace, ParticleVector, } from './components/particle-emitter.js';
@@ -115,7 +118,7 @@ export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit
 export type { Point3d, QueryColliders3d, QueryVolume3d, RayHit3d } from './spatial-query-3d.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
-export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, SceneLightingJson, ScenePostJson, PrefabJson, } from './scene.js';
+export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, SceneLightingJson, ScenePostJson, SceneShadowsJson, ShadowQuality, PrefabJson, } from './scene.js';
 export { ClipPlayer } from './animation/clip-player.js';
 export type { ClipDef } from './animation/clip-player.js';
 export { sheetCell, sheetFrameCount, locateFrame } from './animation/sheet.js';

package/dist/index.js

@@ -35,7 +35,7 @@ export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
 export { Model } from './components/model.js';
-export { Animator } from './components/animator.js';
+export { Animator, DEFAULT_BLEND_SMOOTHING } from './components/animator.js';
 export { poseHash } from './animation/pose-hash.js';
 export { Sun } from './components/sun.js';
 export { Collider, COLLIDER_SHAPES } from './components/collider.js';
@@ -43,10 +43,12 @@ export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';
 export { DEFAULT_GRAVITY, resolveSceneSimulation, sceneSimulationIssues } from './scene-simulation.js';
 export { PointLight } from './components/point-light.js';
 export { GameLighting } from './scene-lighting.js';
+export { GameShadows } from './game-shadows.js';
 export { GamePost } from './post-effects.js';
 export { EMISSIVE_LAYER, setEmissive } from './render-layers.js';
 export { lightFalloff, lightMapValue, lightVisibility } from './light-field.js';
 export { sceneRenderIssues } from './scene-render-options.js';
+export { assertShadowMapCapacity, normalizeShadowBoolean, normalizeShadowOverride, resolveLightShadow, resolveSceneShadows, sceneShadowIssues, shadowComponentIssues, SHADOW_DEFAULTS, SHADOW_MAP_SIZES, SHADOW_OVERRIDE_PARAMS, SHADOW_QUALITIES, } from './scene-shadows.js';
 export { ParticleEmitter } from './components/particle-emitter.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';

package/dist/point-shadow.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from 'three/webgpu';
+export interface RangedPointShadow {
+    /** Call before rendering, with the resolved finite, positive shadow range. */
+    sync(maxDistance: number): void;
+    /** The owner must also notify the renderer's light node with light.dispose(). */
+    dispose(): void;
+}
+/**
+ * Keeps the shadow camera independent of the real light's attenuation.
+ * The unparented proxy is never added to the scene and cannot illuminate it.
+ * Three's stock node still renders all six faces and its stock PCF does the
+ * filtering; the extra TSL gate clips receivers to an Euclidean world radius.
+ */
+export declare function createRangedPointShadow(light: THREE.PointLight): RangedPointShadow;

package/dist/point-shadow.js

@@ -0,0 +1,54 @@
+import * as THREE from 'three/webgpu';
+import { float, Fn, PointShadowFilter, positionWorld, uniform } from 'three/tsl';
+function installShadowHooks(shadow, node, filterNode) {
+    const previousNode = shadow.shadowNode;
+    const previousFilter = 'filterNode' in shadow ? shadow.filterNode : undefined;
+    // Public WebGPURenderer filterNode hook, missing in @types/three 0.186.
+    const hooks = Object.assign(shadow, { shadowNode: node, filterNode });
+    return () => {
+        if (hooks.shadowNode === node)
+            shadow.shadowNode = previousNode;
+        if (hooks.filterNode === filterNode)
+            Object.assign(hooks, { filterNode: previousFilter });
+    };
+}
+/**
+ * Keeps the shadow camera independent of the real light's attenuation.
+ * The unparented proxy is never added to the scene and cannot illuminate it.
+ * Three's stock node still renders all six faces and its stock PCF does the
+ * filtering; the extra TSL gate clips receivers to an Euclidean world radius.
+ */
+export function createRangedPointShadow(light) {
+    const shadow = light.shadow;
+    const proxy = new THREE.PointLight();
+    // lightShadowMatrix must use PointShadowNode's cubemap matrix, never LightShadow's target path.
+    proxy.castShadow = true;
+    proxy.shadow = shadow;
+    const node = new THREE.PointShadowNode(proxy, shadow);
+    const center = uniform(proxy.position);
+    const radius = uniform(0);
+    // Fn parameters are proxy arrays: nested functions need a fresh named-argument object.
+    const filterNode = Fn(({ depthTexture, bd3D, dp, shadow: filterShadow }) => positionWorld.sub(center).length().lessThanEqual(radius).select(PointShadowFilter({ depthTexture, bd3D, dp, shadow: filterShadow }), float(1)));
+    const unlinkHooks = installShadowHooks(shadow, node, filterNode);
+    let disposed = false;
+    return {
+        sync(maxDistance) {
+            if (disposed)
+                return;
+            const range = light.distance > 0 ? Math.min(light.distance, maxDistance) : maxDistance;
+            light.getWorldPosition(proxy.position);
+            proxy.updateMatrixWorld();
+            radius.value = range;
+            shadow.camera.near = Math.min(0.1, range / 100);
+            shadow.camera.far = range;
+            shadow.camera.updateProjectionMatrix();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            node.dispose();
+            unlinkHooks();
+        },
+    };
+}

package/dist/runtime-lighting-snapshot.d.ts

@@ -3,6 +3,7 @@ import type { Game } from './game.js';
 import type { ProjectionIssue } from './runtime-inspection.js';
 import type { Vec3Json } from './scene-camera-3d.js';
 import type { AmbientLight, PostEffectsState } from './scene-render-options.js';
+import type { LightShadowOverrides, ResolvedLightShadow, ResolvedSceneShadows } from './scene-shadows.js';
 /** One live Light as a Runtime Snapshot reports it: its entity's name, logical position and params. */
 export interface RuntimeSnapshotLight {
     /** The entity's name, as `ui.anchored[].entity` reports it. */
@@ -19,6 +20,10 @@ export interface RuntimeSnapshotLight {
     softness: number;
     castShadows: boolean;
 }
+/** Effective shadow configuration, independent of GPU allocation, with the light's nullable authoring overrides. */
+export interface RuntimeSnapshotLightShadows extends ResolvedLightShadow {
+    requested: Required<LightShadowOverrides>;
+}
 /** One live Sun in a 3D scene (issue #154 CA-16): its entity's name and id, the unit direction it shines along, color and intensity. */
 export interface RuntimeSnapshotSun {
     entity: string;
@@ -27,6 +32,7 @@ export interface RuntimeSnapshotSun {
     /** `#rrggbb`. */
     color: string;
     intensity: number;
+    shadows: RuntimeSnapshotLightShadows;
 }
 /** One live Point Light in a 3D scene (issue #154 CA-16): its world position and look; `distance` 0 is unlimited. */
 export interface RuntimeSnapshotPointLight {
@@ -37,17 +43,19 @@ export interface RuntimeSnapshotPointLight {
     color: string;
     intensity: number;
     distance: number;
+    shadows: RuntimeSnapshotLightShadows;
 }
 /**
  * `game.lighting` (issue #78 CA-12): the Ambient Light now and every live
  * Light, in logical coordinates. A 3D scene (issue #154 CA-16) adds its
- * Suns and Point Lights; a 2D scene's snapshot has neither key.
+ * Suns, Point Lights and shadow policy; a 2D scene's snapshot has none of these keys.
  */
 export interface RuntimeSnapshotLighting {
     ambient: AmbientLight;
     lights: RuntimeSnapshotLight[];
     sun?: RuntimeSnapshotSun[];
     pointLights?: RuntimeSnapshotPointLight[];
+    shadows?: ResolvedSceneShadows;
 }
 /** `game.post` (issue #78 CA-12): each Post Effect, null when off. */
 export type RuntimeSnapshotPost = PostEffectsState;

package/dist/runtime-lighting-snapshot.js

@@ -8,7 +8,20 @@ function unit(direction) {
     const [x, y, z] = new THREE.Vector3(...direction).normalize().toArray();
     return [rounded(x), rounded(y), rounded(z)];
 }
-/** The Suns and Point Lights of a 3D scene's entities, in spawn order. */
+function lightShadowsSnapshot(game, light) {
+    return {
+        ...game.shadows.resolve(light),
+        requested: {
+            castShadows: light.castShadows,
+            shadowMapSize: light.shadowMapSize,
+            shadowMaxDistance: light.shadowMaxDistance,
+            shadowBias: light.shadowBias,
+            shadowNormalBias: light.shadowNormalBias,
+            shadowRadius: light.shadowRadius,
+        },
+    };
+}
+/** The Suns and Point Lights of a 3D scene's entities, in spawn order, and its shadow policy. */
 function lights3dSnapshot(game, idFor) {
     const sun = [];
     const pointLights = [];
@@ -16,18 +29,25 @@ function lights3dSnapshot(game, idFor) {
         for (const component of entity.components) {
             if (component instanceof Sun) {
                 const { direction, color, intensity } = component;
-                sun.push({ entity: entity.name, id: idFor(entity), direction: unit(direction), color: hexOf(color), intensity });
+                sun.push({
+                    entity: entity.name, id: idFor(entity), direction: unit(direction), color: hexOf(color), intensity,
+                    shadows: lightShadowsSnapshot(game, component),
+                });
             }
             else if (component instanceof PointLight && component.light) {
                 const { color, intensity, distance, light } = component;
                 light.updateWorldMatrix(true, false);
                 const at = light.getWorldPosition(new THREE.Vector3());
                 const position = [rounded(at.x), rounded(at.y), rounded(at.z)];
-                pointLights.push({ entity: entity.name, id: idFor(entity), position, color: hexOf(color), intensity, distance });
+                pointLights.push({
+                    entity: entity.name, id: idFor(entity), position, color: hexOf(color), intensity, distance,
+                    shadows: lightShadowsSnapshot(game, component),
+                });
             }
         }
     }
-    return { sun, pointLights };
+    const { quality, maxDistance } = game.shadows.policy;
+    return { sun, pointLights, shadows: { quality, maxDistance } };
 }
 export function lightingSnapshot(game, idFor) {
     return {