@waica/engine 0.30.1 → 0.31.0

package/dist/components/model.js

@@ -1,5 +1,7 @@
 import * as THREE from 'three/webgpu';
 import { Component } from '../component.js';
+import { reportRejection } from '../report-rejection.js';
+import { normalizeShadowBoolean } from '../scene-shadows.js';
 const SHAPES = ['box', 'sphere', 'plane'];
 /** One unit of the shape: a box of side 1, a sphere of diameter 1, a plane of side 1 lying flat on the ground (normal up). */
 function primitiveGeometry(shape) {
@@ -31,6 +33,8 @@ export class Model extends Component {
         shape: { label: 'Shape', options: [...SHAPES] },
         color: { label: 'Color', kind: 'color' },
         size: { label: 'Size', min: 0.01, step: 0.1 },
+        castShadows: { label: 'Cast shadows' },
+        receiveShadows: { label: 'Receive shadows' },
     };
     static transient = ['root', 'handle'];
     /** What this Model draws, under the entity's node; null until it is ready. The Pointer ray-casts against it. */
@@ -46,6 +50,8 @@ export class Model extends Component {
     _shape = 'box';
     _color = 0xffffff;
     _size = 1;
+    _castShadows = true;
+    _receiveShadows = true;
     _primitive = null;
     /** A `waica:` uri or project path to a `.glb` / `.gltf`; empty draws the primitive `shape`. */
     get src() {
@@ -78,6 +84,22 @@ export class Model extends Component {
         this._size = value;
         this._primitive?.mesh.scale.setScalar(value);
     }
+    /** Whether this Model's meshes cast shadows; only false opts out. */
+    get castShadows() {
+        return this._castShadows;
+    }
+    set castShadows(value) {
+        this._castShadows = normalizeShadowBoolean(value);
+        this.applyShadowFlags();
+    }
+    /** Whether this Model's meshes receive shadows; only false opts out. */
+    get receiveShadows() {
+        return this._receiveShadows;
+    }
+    set receiveShadows(value) {
+        this._receiveShadows = normalizeShadowBoolean(value);
+        this.applyShadowFlags();
+    }
     onReady() {
         // Draws only in a 3D scene, like Sun and PointLight: 2.5D is a later block, and a lit-less mesh would come out black.
         if (this.game.space !== '3d')
@@ -95,8 +117,19 @@ export class Model extends Component {
         if (!this.root)
             return;
         if (this._src) {
-            this.handle = this.game.assets.model(this._src);
-            this.root.add(this.handle.root);
+            const handle = this.game.assets.model(this._src);
+            this.handle = handle;
+            this.root.add(handle.root);
+            // A cache hit inserts its clone one microtask before settled reactions;
+            // apply on insertion so Assets Ready already exposes the latest flags.
+            const applyFlags = () => {
+                if (this.handle === handle)
+                    this.applyShadowFlags();
+            };
+            handle.root.addEventListener('childadded', applyFlags);
+            reportRejection(handle.settled.finally(() => {
+                handle.root.removeEventListener('childadded', applyFlags);
+            }), 'model shadows settle');
         }
         else {
             this.buildPrimitive(this.root);
@@ -106,6 +139,8 @@ export class Model extends Component {
         const material = new THREE.MeshStandardNodeMaterial({ color: this._color });
         const mesh = new THREE.Mesh(primitiveGeometry(this._shape), material);
         mesh.scale.setScalar(this._size);
+        mesh.castShadow = this.castShadows;
+        mesh.receiveShadow = this.receiveShadows;
         root.add(mesh);
         this._primitive = { mesh };
     }
@@ -115,8 +150,19 @@ export class Model extends Component {
         this.clear();
         this.build();
     }
-    /** Empties the root and disposes the primitive this Model created; a glTF's clone only leaves the graph. */
+    /** Participation belongs to this Model's meshes, never their shared glTF resources. */
+    applyShadowFlags() {
+        this.root?.traverse((object) => {
+            if (!(object instanceof THREE.Mesh))
+                return;
+            object.castShadow = this._castShadows;
+            object.receiveShadow = this._receiveShadows;
+        });
+    }
+    /** Retire clone-local render state; shared glTF geometry/materials stay cache-owned. */
     clear() {
+        for (const child of this.root?.children ?? [])
+            child.traverse((object) => object.dispose());
         this.root?.clear();
         this.handle = null;
         if (!this._primitive)

package/dist/components/point-light.d.ts

@@ -1,20 +1,55 @@
 import * as THREE from 'three/webgpu';
-import { Component, type ComponentSpace } from '../component.js';
+import type { ComponentSpace } from '../component.js';
+import { ShadowLight } from './shadow-light.js';
 /**
  * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
  * in every direction from the entity's position plus an offset (in the
  * entity's local frame: it turns and scales with the entity, so a lantern's
  * offset follows the object it hangs on), reaching
  * `distance` world units (0 = without limit) and fading with `decay` (2 is
- * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * physical). Not the 2D `Light`, which paints a light-map. Its shadows have an
+ * independent finite range without shortening illumination. In a
  * 2D scene it creates nothing; the three light lives under the entity's node
  * and leaves with it.
  */
-export declare class PointLight extends Component {
+export declare class PointLight extends ShadowLight {
     static componentName: string;
     static space: ComponentSpace;
     static displayName: string;
     static params: {
+        shadowMapSize: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowMaxDistance: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowNormalBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowRadius: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        castShadows: {
+            label: string;
+        };
         color: {
             label: string;
             kind: "color";

package/dist/components/point-light.js

@@ -1,16 +1,17 @@
 import * as THREE from 'three/webgpu';
-import { Component } from '../component.js';
+import { ShadowLight } from './shadow-light.js';
 /**
  * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
  * in every direction from the entity's position plus an offset (in the
  * entity's local frame: it turns and scales with the entity, so a lantern's
  * offset follows the object it hangs on), reaching
  * `distance` world units (0 = without limit) and fading with `decay` (2 is
- * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * physical). Not the 2D `Light`, which paints a light-map. Its shadows have an
+ * independent finite range without shortening illumination. In a
  * 2D scene it creates nothing; the three light lives under the entity's node
  * and leaves with it.
  */
-export class PointLight extends Component {
+export class PointLight extends ShadowLight {
     static componentName = 'PointLight';
     static space = '3d';
     static displayName = 'Point light (3D)';
@@ -22,6 +23,7 @@ export class PointLight extends Component {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
         offsetZ: { label: 'z offset' },
+        ...ShadowLight.params,
     };
     static transient = ['light'];
     /** The three light, null in a 2D scene or before the component is ready. */
@@ -94,6 +96,7 @@ export class PointLight extends Component {
         this.place();
     }
     onDestroy() {
+        this.game.shadows.remove(this);
         this.light?.removeFromParent();
     }
     place() {

package/dist/components/shadow-light.d.ts

@@ -0,0 +1,63 @@
+import { Component } from '../component.js';
+/** Shared, normalized authoring properties for the two 3D lights. */
+export declare abstract class ShadowLight extends Component {
+    static params: {
+        shadowMapSize: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowMaxDistance: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowNormalBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowRadius: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        castShadows: {
+            label: string;
+        };
+    };
+    private _castShadows;
+    private _shadowMapSize;
+    private _shadowMaxDistance;
+    private _shadowBias;
+    private _shadowNormalBias;
+    private _shadowRadius;
+    get castShadows(): boolean;
+    set castShadows(value: unknown);
+    /** Null inherits the scene's resolution for this kind of light. */
+    get shadowMapSize(): number | null;
+    set shadowMapSize(value: unknown);
+    /** Null inherits the scene's maximum shadow distance, in world units. */
+    get shadowMaxDistance(): number | null;
+    set shadowMaxDistance(value: unknown);
+    /** Null inherits the engine default shadow bias (SHADOW_DEFAULTS.bias). */
+    get shadowBias(): number | null;
+    set shadowBias(value: unknown);
+    /** Null inherits the engine default normal offset (SHADOW_DEFAULTS.normalBias). */
+    get shadowNormalBias(): number | null;
+    set shadowNormalBias(value: unknown);
+    /** Null inherits the engine default PCF radius (SHADOW_DEFAULTS.radius). */
+    get shadowRadius(): number | null;
+    set shadowRadius(value: unknown);
+    private validateChange;
+}

package/dist/components/shadow-light.js

@@ -0,0 +1,71 @@
+import { Component } from '../component.js';
+import { normalizeShadowBoolean, normalizeShadowOverride, SHADOW_OVERRIDE_PARAMS } from '../scene-shadows.js';
+/** Shared, normalized authoring properties for the two 3D lights. */
+export class ShadowLight extends Component {
+    static params = {
+        castShadows: { label: 'Cast shadows' },
+        ...SHADOW_OVERRIDE_PARAMS,
+    };
+    _castShadows = true;
+    _shadowMapSize = null;
+    _shadowMaxDistance = null;
+    _shadowBias = null;
+    _shadowNormalBias = null;
+    _shadowRadius = null;
+    get castShadows() {
+        return this._castShadows;
+    }
+    set castShadows(value) {
+        const normalized = normalizeShadowBoolean(value);
+        this.validateChange({ castShadows: normalized });
+        this._castShadows = normalized;
+    }
+    /** Null inherits the scene's resolution for this kind of light. */
+    get shadowMapSize() {
+        return this._shadowMapSize;
+    }
+    set shadowMapSize(value) {
+        const normalized = normalizeShadowOverride('shadowMapSize', value);
+        this.validateChange({ shadowMapSize: normalized });
+        this._shadowMapSize = normalized;
+    }
+    /** Null inherits the scene's maximum shadow distance, in world units. */
+    get shadowMaxDistance() {
+        return this._shadowMaxDistance;
+    }
+    set shadowMaxDistance(value) {
+        const normalized = normalizeShadowOverride('shadowMaxDistance', value);
+        this.validateChange({ shadowMaxDistance: normalized });
+        this._shadowMaxDistance = normalized;
+    }
+    /** Null inherits the engine default shadow bias (SHADOW_DEFAULTS.bias). */
+    get shadowBias() {
+        return this._shadowBias;
+    }
+    set shadowBias(value) {
+        const normalized = normalizeShadowOverride('shadowBias', value);
+        this.validateChange({ shadowBias: normalized });
+        this._shadowBias = normalized;
+    }
+    /** Null inherits the engine default normal offset (SHADOW_DEFAULTS.normalBias). */
+    get shadowNormalBias() {
+        return this._shadowNormalBias;
+    }
+    set shadowNormalBias(value) {
+        const normalized = normalizeShadowOverride('shadowNormalBias', value);
+        this.validateChange({ shadowNormalBias: normalized });
+        this._shadowNormalBias = normalized;
+    }
+    /** Null inherits the engine default PCF radius (SHADOW_DEFAULTS.radius). */
+    get shadowRadius() {
+        return this._shadowRadius;
+    }
+    set shadowRadius(value) {
+        const normalized = normalizeShadowOverride('shadowRadius', value);
+        this.validateChange({ shadowRadius: normalized });
+        this._shadowRadius = normalized;
+    }
+    validateChange(change) {
+        this.game?.shadows.validateChange(this, change);
+    }
+}

package/dist/components/sun.d.ts

@@ -1,17 +1,52 @@
 import * as THREE from 'three/webgpu';
-import { Component, type ComponentSpace } from '../component.js';
+import type { ComponentSpace } from '../component.js';
 import type { Vec3Json } from '../scene-camera-3d.js';
+import { ShadowLight } from './shadow-light.js';
 /**
  * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
  * that shines along `direction`, in world space — where its entity stands, or
- * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * how it is rotated, does not matter. Color is `0xrrggbb`; shadows follow the
+ * active view through the scene's shadow policy. A Sun
  * in a 2D scene creates nothing. The three light lives in the Game's scene,
  * moves with its props, and leaves with the entity.
  */
-export declare class Sun extends Component {
+export declare class Sun extends ShadowLight {
     static componentName: string;
     static space: ComponentSpace;
     static params: {
+        shadowMapSize: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowMaxDistance: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowNormalBias: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        shadowRadius: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        castShadows: {
+            label: string;
+        };
         direction: {
             label: string;
             kind: "vector3";

package/dist/components/sun.js

@@ -1,22 +1,24 @@
 import * as THREE from 'three/webgpu';
-import { Component } from '../component.js';
+import { ShadowLight } from './shadow-light.js';
 const DEFAULT_DIRECTION = [-1, -2, -1];
 /** Scene JSON is untyped at runtime: only an array of three finite numbers, not all zero, aims a light. */
 const finiteDirection = (value) => Array.isArray(value) && value.length === 3 && value.every(Number.isFinite) && value.some((component) => component !== 0);
 /**
  * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
  * that shines along `direction`, in world space — where its entity stands, or
- * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * how it is rotated, does not matter. Color is `0xrrggbb`; shadows follow the
+ * active view through the scene's shadow policy. A Sun
  * in a 2D scene creates nothing. The three light lives in the Game's scene,
  * moves with its props, and leaves with the entity.
  */
-export class Sun extends Component {
+export class Sun extends ShadowLight {
     static componentName = 'Sun';
     static space = '3d';
     static params = {
         direction: { label: 'Direction', kind: 'vector3' },
         color: { label: 'Color', kind: 'color' },
         intensity: { label: 'Intensity', min: 0, step: 0.1 },
+        ...ShadowLight.params,
     };
     static transient = ['light'];
     /** The three light, null in a 2D scene or before the component is ready. */
@@ -60,6 +62,7 @@ export class Sun extends Component {
         this.aim();
     }
     onDestroy() {
+        this.game.shadows.remove(this);
         this.light?.removeFromParent();
         this.light?.target.removeFromParent();
     }

package/dist/entity.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three/webgpu';
+import { ShadowLight } from './components/shadow-light.js';
 /**
  * A live scene node: a transform (three Group) + components.
  * Created with `game.spawn(name)`.
@@ -43,6 +44,8 @@ export class Entity {
         if (props)
             Object.assign(component, props);
         this.game.applyParamOverrides(this, component);
+        if (component instanceof ShadowLight)
+            this.game.shadows.validateAddition(component);
         this.components.push(component);
         component.onReady?.();
         return component;

package/dist/game-shadows.d.ts

@@ -0,0 +1,54 @@
+import * as THREE from 'three/webgpu';
+import { PointLight } from './components/point-light.js';
+import { Sun } from './components/sun.js';
+import type { ShadowLight } from './components/shadow-light.js';
+import type { Game } from './game.js';
+import { type LightShadowOverrides, type ResolvedLightShadow, type ResolvedSceneShadows, type ShadowQuality } from './scene-shadows.js';
+import { type SceneJson, type SceneRegistry } from './scene.js';
+/** The live scene's shadow policy; resolving settings never allocates a shadow map. */
+export declare class GameShadows {
+    private readonly game;
+    private state;
+    private renderer;
+    private readonly pointShadows;
+    private readonly composing;
+    private readonly lastValid;
+    private readonly capacityErrors;
+    private lastRendererFrame;
+    constructor(game: Game);
+    connect(renderer: THREE.WebGPURenderer): void;
+    get policy(): ResolvedSceneShadows;
+    get quality(): ShadowQuality;
+    set quality(value: unknown);
+    get maxDistance(): number;
+    set maxDistance(value: unknown);
+    loadScene(value: unknown): void;
+    unloadScene(): void;
+    /** Validate final composed props, before Entity.add publishes or readies a light. */
+    validateAddition(component: ShadowLight): void;
+    /** Check the ready device, even for authored 3D settings in a 2D preview. */
+    assertCapacity(settings: ResolvedLightShadow): void;
+    /** Persisted params are one composed request, not a sequence of active setters. */
+    applyParams(component: ShadowLight, props: Record<string, unknown>): void;
+    /** Check an incoming scene before unloadScene destroys the last valid one. */
+    validateScene(scene: SceneJson, registry: SceneRegistry): void;
+    /** A failing request leaves both the authored live value and its active map unchanged. */
+    validateChange(component: ShadowLight, change: LightShadowOverrides | Record<string, unknown>): void;
+    validate(): void;
+    resolve(light: Sun | PointLight): ResolvedLightShadow;
+    private requested;
+    private effectiveSettings;
+    /** Called at the render boundary, including paused and edit-mode frames. */
+    sync(renderer: THREE.WebGPURenderer): void;
+    private syncLight;
+    /** Prepare host overlays from the same current fit, without allocating or rendering. */
+    prepareSunCamera(component: Sun): THREE.OrthographicCamera | null;
+    private fitSun;
+    private syncPoint;
+    private withCoverage;
+    /** Notify Three's analytic light node as well as disposing the exposed target. */
+    remove(component: Sun | PointLight): void;
+    private adopt;
+    private validatePolicy;
+    private lights;
+}