@waica/engine 0.30.0 → 0.31.0

package/dist/scene-shadows.d.ts

@@ -0,0 +1,82 @@
+import type { SceneFieldIssue } from './scene-camera-3d.js';
+import type { ShadowQuality } from './scene.js';
+export type { SceneShadowsJson, ShadowQuality } from './scene.js';
+export interface ResolvedSceneShadows {
+    quality: ShadowQuality;
+    maxDistance: number;
+}
+export declare const SHADOW_QUALITIES: readonly ShadowQuality[];
+export declare const SHADOW_MAP_SIZES: readonly number[];
+export type ShadowOverrideName = 'shadowMapSize' | 'shadowMaxDistance' | 'shadowBias' | 'shadowNormalBias' | 'shadowRadius';
+export interface LightShadowOverrides {
+    castShadows?: boolean;
+    shadowMapSize?: number | null;
+    shadowMaxDistance?: number | null;
+    shadowBias?: number | null;
+    shadowNormalBias?: number | null;
+    shadowRadius?: number | null;
+}
+export interface ResolvedLightShadow {
+    enabled: boolean;
+    mapSize: number;
+    maxDistance: number;
+    bias: number;
+    normalBias: number;
+    radius: number;
+}
+export declare const SHADOW_DEFAULTS: {
+    readonly quality: 'medium';
+    readonly maxDistance: 40;
+    readonly bias: -0.0005;
+    readonly normalBias: 0.02;
+    readonly radius: 1;
+};
+/** Nullable fields explicitly inherit the scene/preset rather than becoming zero. */
+export declare const SHADOW_OVERRIDE_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;
+    };
+};
+/** Shadow flags default on, including malformed authored values; only false opts out. */
+export declare function normalizeShadowBoolean(value: unknown): boolean;
+/** Runtime fallback/clamping only; validators still report invalid authored data. */
+export declare function normalizeShadowOverride(name: ShadowOverrideName, value: unknown): number | null;
+/** Resolves the shadows block itself, independently of lighting or GPU state. */
+export declare function resolveSceneShadows(value: unknown): ResolvedSceneShadows;
+/** Effective policy; a point light's existing distance bounds its independent shadow range. */
+export declare function resolveLightShadow(kind: 'sun' | 'point', scene: ResolvedSceneShadows, overrides: LightShadowOverrides & {
+    distance?: number;
+}): ResolvedLightShadow;
+/** Diagnoses authored values, not their runtime-normalized replacements. */
+export declare function sceneShadowIssues(render: unknown): SceneFieldIssue[];
+/** Component-local field paths let callers add their prefab/entity/override context. */
+export declare function shadowComponentIssues(type: string, props: unknown): SceneFieldIssue[];
+/** Check before allocating or replacing a map; Off never needs a supported texture size. */
+export declare function assertShadowMapCapacity(resolved: ResolvedLightShadow, maxTextureSize: number): void;

package/dist/scene-shadows.js

@@ -0,0 +1,151 @@
+import { resolveSceneSpace } from './scene-space.js';
+export const SHADOW_QUALITIES = ['off', 'low', 'medium', 'high'];
+export const SHADOW_MAP_SIZES = [256, 512, 1024, 2048, 4096];
+export const SHADOW_DEFAULTS = {
+    quality: 'medium', maxDistance: 40, bias: -0.0005, normalBias: 0.02, radius: 1,
+};
+const PROFILE_MAP_SIZES = {
+    sun: { low: 1024, medium: 2048, high: 4096 },
+    point: { low: 256, medium: 512, high: 1024 },
+};
+/** Nullable fields explicitly inherit the scene/preset rather than becoming zero. */
+export const SHADOW_OVERRIDE_PARAMS = {
+    shadowMapSize: { label: 'Shadow map size', min: 256, max: 4096, step: 256 },
+    shadowMaxDistance: { label: 'Shadow max distance', min: 0.01, max: 1000, step: 0.01 },
+    shadowBias: { label: 'Shadow bias', min: -0.1, max: 0.1, step: 0.0001 },
+    shadowNormalBias: { label: 'Shadow normal bias', min: 0, max: 1, step: 0.01 },
+    shadowRadius: { label: 'Shadow radius', min: 0, max: 8, step: 0.1 },
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isQuality(value) {
+    return SHADOW_QUALITIES.some((quality) => quality === value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Shadow flags default on, including malformed authored values; only false opts out. */
+export function normalizeShadowBoolean(value) {
+    return value !== false;
+}
+/** Runtime fallback/clamping only; validators still report invalid authored data. */
+export function normalizeShadowOverride(name, value) {
+    if (!isFiniteNumber(value))
+        return null;
+    if (name === 'shadowMapSize')
+        return SHADOW_MAP_SIZES.includes(value) ? value : null;
+    const { min, max } = SHADOW_OVERRIDE_PARAMS[name];
+    return clamp(value, min, max);
+}
+/** Resolves the shadows block itself, independently of lighting or GPU state. */
+export function resolveSceneShadows(value) {
+    const block = isRecord(value) ? value : {};
+    return {
+        quality: isQuality(block.quality) ? block.quality : SHADOW_DEFAULTS.quality,
+        maxDistance: normalizeShadowOverride('shadowMaxDistance', block.maxDistance) ?? SHADOW_DEFAULTS.maxDistance,
+    };
+}
+/** Effective policy; a point light's existing distance bounds its independent shadow range. */
+export function resolveLightShadow(kind, scene, overrides) {
+    const quality = scene.quality === 'off' ? 'medium' : scene.quality;
+    const maxDistance = normalizeShadowOverride('shadowMaxDistance', overrides.shadowMaxDistance) ?? scene.maxDistance;
+    return {
+        enabled: scene.quality !== 'off' && normalizeShadowBoolean(overrides.castShadows),
+        mapSize: normalizeShadowOverride('shadowMapSize', overrides.shadowMapSize) ?? PROFILE_MAP_SIZES[kind][quality],
+        maxDistance: kind === 'point' ? pointShadowDistance(maxDistance, overrides.distance) : maxDistance,
+        bias: normalizeShadowOverride('shadowBias', overrides.shadowBias) ?? SHADOW_DEFAULTS.bias,
+        normalBias: normalizeShadowOverride('shadowNormalBias', overrides.shadowNormalBias) ?? SHADOW_DEFAULTS.normalBias,
+        radius: normalizeShadowOverride('shadowRadius', overrides.shadowRadius) ?? SHADOW_DEFAULTS.radius,
+    };
+}
+/** A zero/unreadable luminous distance is unlimited, never a zero shadow range. */
+function pointShadowDistance(maxDistance, lightDistance) {
+    if (!isFiniteNumber(lightDistance) || lightDistance <= 0)
+        return maxDistance;
+    return Math.min(maxDistance, lightDistance);
+}
+function shown(value) {
+    if (typeof value === 'object' && value !== null) {
+        try {
+            return JSON.stringify(value) ?? '[unserializable object]';
+        }
+        catch {
+            return '[unserializable object]';
+        }
+    }
+    return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+function numericIssue(name, value, field) {
+    if (isFiniteNumber(value) && normalizeShadowOverride(name, value) === value)
+        return null;
+    const { min, max } = SHADOW_OVERRIDE_PARAMS[name];
+    const range = name === 'shadowMapSize' ? 'one of 256, 512, 1024, 2048, 4096' : `a finite number from ${min} to ${max}`;
+    return { field, message: `${field} must be ${range}; got ${shown(value)}.` };
+}
+/** Diagnoses authored values, not their runtime-normalized replacements. */
+export function sceneShadowIssues(render) {
+    if (!isRecord(render) || render.shadows === undefined)
+        return [];
+    const shadows = render.shadows;
+    const issues = [];
+    if (resolveSceneSpace(render) !== '3d') {
+        issues.push({ field: 'render.shadows', message: "render.shadows needs render.space '3d'; this scene is not 3d." });
+    }
+    if (!isRecord(shadows)) {
+        issues.push({ field: 'render.shadows', message: `render.shadows must be an object; got ${shown(shadows)}.` });
+        return issues;
+    }
+    if (shadows.quality !== undefined && !isQuality(shadows.quality)) {
+        issues.push({
+            field: 'render.shadows.quality',
+            message: `render.shadows.quality must be off, low, medium or high; got ${shown(shadows.quality)}.`,
+        });
+    }
+    if (shadows.maxDistance !== undefined) {
+        const issue = numericIssue('shadowMaxDistance', shadows.maxDistance, 'render.shadows.maxDistance');
+        if (issue)
+            issues.push(issue);
+    }
+    return issues;
+}
+function booleanIssue(field, value) {
+    if (value === undefined || typeof value === 'boolean')
+        return null;
+    return { field, message: `${field} must be a boolean; got ${shown(value)}.` };
+}
+/** Component-local field paths let callers add their prefab/entity/override context. */
+export function shadowComponentIssues(type, props) {
+    if (!isRecord(props) || !['Sun', 'PointLight', 'Model'].includes(type))
+        return [];
+    const issues = [];
+    const castIssue = booleanIssue('castShadows', props.castShadows);
+    if (castIssue)
+        issues.push(castIssue);
+    if (type === 'Model') {
+        const receiveIssue = booleanIssue('receiveShadows', props.receiveShadows);
+        if (receiveIssue)
+            issues.push(receiveIssue);
+        return issues;
+    }
+    for (const name of ['shadowMapSize', 'shadowMaxDistance', 'shadowBias', 'shadowNormalBias', 'shadowRadius']) {
+        const value = props[name];
+        if (value === undefined || value === null)
+            continue;
+        const issue = numericIssue(name, value, name);
+        if (issue)
+            issues.push(issue);
+    }
+    return issues;
+}
+/** Check before allocating or replacing a map; Off never needs a supported texture size. */
+export function assertShadowMapCapacity(resolved, maxTextureSize) {
+    if (!resolved.enabled)
+        return;
+    if (!isFiniteNumber(maxTextureSize) || resolved.mapSize > maxTextureSize) {
+        throw new RangeError(`Shadow map size ${resolved.mapSize} is unsupported by device capacity ${maxTextureSize}.`);
+    }
+}

package/dist/scene.d.ts

@@ -1,5 +1,5 @@
 import type { SceneCameraJson } from './camera.js';
-import type { ComponentClass } from './component.js';
+import type { Component, ComponentClass } from './component.js';
 import type { Entity } from './entity.js';
 import { type TransformJson } from './entity-transform.js';
 import type { Game } from './game.js';
@@ -55,6 +55,12 @@ export interface ScenePostJson {
         saturation?: number;
     };
 }
+export type ShadowQuality = 'off' | 'low' | 'medium' | 'high';
+/** Scene-wide 3D shadow policy; absent fields use Medium and 40 world units. */
+export interface SceneShadowsJson {
+    quality?: ShadowQuality;
+    maxDistance?: number;
+}
 /** Scene-wide render options (v3). */
 export interface SceneRenderJson {
     /**
@@ -65,6 +71,8 @@ export interface SceneRenderJson {
     space?: SceneSpace;
     /** Ambient Light; with it (or any Light) the scene is lit (ADR 0026). */
     lighting?: SceneLightingJson;
+    /** 3D shadow quality and coverage, independent of Ambient Light. */
+    shadows?: SceneShadowsJson;
     /** Vignette and color grade; with either on, the frame renders through a render target. */
     post?: ScenePostJson;
     /**
@@ -135,6 +143,8 @@ export declare function resolveProps(props: Record<string, unknown> | undefined,
  * are never mutated; merged components are fresh objects.
  */
 export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
+/** Scene JSON props with any Component member dropped and reported. */
+export declare function sceneProps(props: Record<string, unknown>, type: string, entityName: string): Partial<Component>;
 export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
 /**
  * Loads a full scene into the game, replacing whatever scene is already

package/dist/scene.js

@@ -83,7 +83,7 @@ function isComponentProps(props) {
     return Object.keys(props).every((key) => !Object.hasOwn(COMPONENT_MEMBERS, key));
 }
 /** Scene JSON props with any Component member dropped and reported. */
-function sceneProps(props, type, entityName) {
+export function sceneProps(props, type, entityName) {
     const dropped = Object.keys(props).filter((key) => Object.hasOwn(COMPONENT_MEMBERS, key));
     const kept = Object.fromEntries(Object.entries(props).filter(([key]) => !dropped.includes(key)));
     if (dropped.length > 0) {
@@ -119,6 +119,7 @@ export function spawnFromJson(game, json, registry) {
  * at a time.
  */
 export function loadScene(game, scene, registry) {
+    game.shadows.validateScene(scene, registry);
     if (game.registry) {
         game.unloadScene();
     }

package/dist/shadow-renderer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Three 0.186 has no public manual-frame pump. Keep this checked compatibility
+ * boundary isolated: its RAF frame must not cache shadows/skeletons across
+ * several fixed-frame renders. Native RAF updates must never be doubled.
+ */
+export declare function advanceRendererFrame(renderer: object, previous: number | null): number;
+/** Read the initialized backend, never infer device limits from its API name. */
+export declare function shadowTextureLimit(backend: object): number;

package/dist/shadow-renderer.js

@@ -0,0 +1,37 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isTextureLimitReader(value) {
+    return isRecord(value) && typeof value.MAX_TEXTURE_SIZE === 'number' && typeof value.getParameter === 'function';
+}
+function isRenderFrameClock(value) {
+    return isRecord(value) && typeof value.frameId === 'number' && Number.isFinite(value.frameId) && typeof value.update === 'function';
+}
+/**
+ * Three 0.186 has no public manual-frame pump. Keep this checked compatibility
+ * boundary isolated: its RAF frame must not cache shadows/skeletons across
+ * several fixed-frame renders. Native RAF updates must never be doubled.
+ */
+export function advanceRendererFrame(renderer, previous) {
+    const nodes = '_nodes' in renderer ? renderer._nodes : undefined;
+    const clock = isRecord(nodes) ? nodes.nodeFrame : undefined;
+    if (!isRenderFrameClock(clock))
+        throw new Error('3D renderer has no compatible NodeFrame clock (Three 0.186).');
+    if (clock.frameId === previous)
+        clock.update();
+    return clock.frameId;
+}
+function webgpuLimit(backend) {
+    const device = 'device' in backend ? backend.device : undefined;
+    const limits = isRecord(device) ? device.limits : undefined;
+    return isRecord(limits) ? limits.maxTextureDimension2D : undefined;
+}
+function webglLimit(backend) {
+    const gl = 'gl' in backend ? backend.gl : undefined;
+    return isTextureLimitReader(gl) ? gl.getParameter(gl.MAX_TEXTURE_SIZE) : undefined;
+}
+/** Read the initialized backend, never infer device limits from its API name. */
+export function shadowTextureLimit(backend) {
+    const limit = 'isWebGPUBackend' in backend && backend.isWebGPUBackend === true ? webgpuLimit(backend) : webglLimit(backend);
+    return typeof limit === 'number' && Number.isFinite(limit) && limit > 0 ? limit : 0;
+}

package/dist/sun-shadow-camera.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+import type { ResolvedLightShadow } from './scene-shadows.js';
+interface SunShadowFit {
+    readonly light: THREE.DirectionalLight;
+    readonly camera: THREE.PerspectiveCamera;
+    readonly settings: Readonly<ResolvedLightShadow>;
+    readonly direction: readonly [number, number, number];
+}
+/** The bounded receiver interval, shared by capacity checks and the camera fit. */
+export declare function sunCoverageDepth(camera: Pick<THREE.PerspectiveCamera, 'near' | 'far'>, maxDistance: number): number | null;
+/**
+ * Fits the active view's bounded receiver volume without changing its camera.
+ * The caller supplies current view matrices and owns shadow resources/passes.
+ * False leaves the previous fit intact; it must not be rendered as coverage.
+ */
+export declare function fitSunShadow({ light, camera, settings, direction }: SunShadowFit): boolean;
+export {};

package/dist/sun-shadow-camera.js

@@ -0,0 +1,67 @@
+import * as THREE from 'three/webgpu';
+function receiverSphere(camera, far) {
+    const points = [];
+    const nearNdc = camera.reversedDepth ? 1 : camera.coordinateSystem === THREE.WebGPUCoordinateSystem ? 0 : -1;
+    for (const x of [-1, 1]) {
+        for (const y of [-1, 1]) {
+            const nearPoint = new THREE.Vector3(x, y, nearNdc).applyMatrix4(camera.projectionMatrixInverse);
+            points.push(nearPoint, nearPoint.clone().multiplyScalar(far / -nearPoint.z));
+        }
+    }
+    const center = new THREE.Vector3();
+    for (const point of points)
+        center.add(point);
+    center.multiplyScalar(1 / points.length);
+    // Transform offsets, not world positions: translation cannot perturb extent.
+    // Unlike Sphere.applyMatrix4, this also bounds sheared camera hierarchies.
+    const linear = new THREE.Matrix3().setFromMatrix4(camera.matrixWorld);
+    const radius = Math.sqrt(Math.max(...points.map((point) => point.clone().sub(center).applyMatrix3(linear).lengthSq())));
+    return new THREE.Sphere(center.applyMatrix4(camera.matrixWorld), radius);
+}
+function snapCenter(sphere, orientation, texelSize) {
+    const center = sphere.center.clone().applyMatrix4(orientation.clone().invert());
+    center.x = Math.round(center.x / texelSize) * texelSize;
+    center.y = Math.round(center.y / texelSize) * texelSize;
+    sphere.center.copy(center.applyMatrix4(orientation));
+}
+function placeInWorld(object, position) {
+    object.position.copy(position);
+    object.parent?.updateWorldMatrix(true, false);
+    if (object.parent)
+        object.position.applyMatrix4(object.parent.matrixWorld.clone().invert());
+    object.updateMatrixWorld();
+}
+/** The bounded receiver interval, shared by capacity checks and the camera fit. */
+export function sunCoverageDepth(camera, maxDistance) {
+    const far = Math.min(camera.far, maxDistance);
+    return Number.isFinite(camera.near) && camera.near > 0 && far > camera.near ? far : null;
+}
+/**
+ * Fits the active view's bounded receiver volume without changing its camera.
+ * The caller supplies current view matrices and owns shadow resources/passes.
+ * False leaves the previous fit intact; it must not be rendered as coverage.
+ */
+export function fitSunShadow({ light, camera, settings, direction }) {
+    const far = sunCoverageDepth(camera, settings.maxDistance);
+    if (!settings.enabled || far === null)
+        return false;
+    light.shadow.mapSize.set(settings.mapSize, settings.mapSize);
+    const sphere = receiverSphere(camera, far);
+    // One full texel survives the worst-case half-texel center snap.
+    sphere.radius /= 1 - 3 / settings.mapSize;
+    const travel = new THREE.Vector3(...direction).normalize();
+    const shadowCamera = light.shadow.camera;
+    // Avoid three's parallel-up fallback, which perturbs the light direction.
+    shadowCamera.up.set(0, Math.abs(travel.y) > 0.99 ? 0 : 1, Math.abs(travel.y) > 0.99 ? 1 : 0);
+    const orientation = new THREE.Matrix4().lookAt(new THREE.Vector3(), travel, shadowCamera.up);
+    snapCenter(sphere, orientation, 2 * sphere.radius / settings.mapSize);
+    shadowCamera.left = shadowCamera.bottom = -sphere.radius;
+    shadowCamera.right = shadowCamera.top = sphere.radius;
+    shadowCamera.near = 0.1;
+    shadowCamera.far = 2 * sphere.radius + settings.maxDistance + shadowCamera.near;
+    placeInWorld(light.target, sphere.center);
+    placeInWorld(light, sphere.center.clone().addScaledVector(travel, -sphere.radius - settings.maxDistance - shadowCamera.near));
+    shadowCamera.updateProjectionMatrix();
+    light.shadow.updateMatrices(light);
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",