@waica/engine 0.25.0 → 0.26.0

package/dist/components/rigid-body.d.ts

@@ -0,0 +1,114 @@
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+export type RigidBodyType = 'dynamic' | 'kinematic';
+export declare const RIGID_BODY_TYPES: readonly RigidBodyType[];
+/** A 3D vector as the body's public API reads and writes it. */
+export interface BodyVector {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Makes the entity's `Collider` a body that moves (ADR 0028). A `dynamic` body
+ * is Rapier's: it falls under the scene's gravity, bounces, stacks and rests,
+ * and after every Simulation Step the engine writes the entity's position and
+ * rotation from it. A `kinematic` body is moved by code. It needs a `Collider`
+ * on the same entity (`validate_project` reports a body without one, and at
+ * runtime none is created). `mass` is the collider's mass; `velocity` is the
+ * initial linear velocity. A `kinematic` body is a character: every step the
+ * engine moves it through Rapier's character controller by its
+ * `desiredVelocity` on x and z and its own vertical velocity under gravity,
+ * stopping at walls, climbing steps up to `stepHeight` and slopes up to
+ * `maxSlope`, sticking to the ground within `snapDistance`, and pushing
+ * dynamic bodies it walks into. A param outside its range (`type` unknown,
+ * `mass` under the minimum, a `velocity` that is not three numbers) creates
+ * no body and warns once; `validate_project` reports it as
+ * `invalid-rigid-body-param`. A RigidBody in a 2D scene creates nothing.
+ */
+export declare class RigidBody extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        type: {
+            label: string;
+            options: RigidBodyType[];
+        };
+        mass: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        gravityScale: {
+            label: string;
+            step: number;
+        };
+        linearDamping: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        angularDamping: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        lockRotations: {
+            label: string;
+        };
+        velocity: {
+            label: string;
+            kind: "vector3";
+        };
+        stepHeight: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        maxSlope: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        snapDistance: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    type: RigidBodyType;
+    mass: number;
+    gravityScale: number;
+    linearDamping: number;
+    angularDamping: number;
+    lockRotations: boolean;
+    /** The initial linear velocity `[x, y, z]`, applied when the body is created. */
+    velocity: Vec3Json;
+    /** Kinematic only: the tallest step it climbs without jumping. */
+    stepHeight: number;
+    /** Kinematic only: the steepest slope it climbs, in degrees. */
+    maxSlope: number;
+    /** Kinematic only: how far below its feet it still sticks to the ground (walking down steps and slopes). */
+    snapDistance: number;
+    /**
+     * Kinematic only: where it walks, in units per second on the world x and z
+     * axes. A motor sets it; the physics step reads it every Simulation Step and
+     * moves the body through the character controller. It stays until set again.
+     */
+    desiredVelocity: {
+        x: number;
+        z: number;
+    };
+    /** The body's linear velocity now, in units per second; zero before it exists. Assigning sets it. */
+    get linearVelocity(): BodyVector;
+    set linearVelocity(value: BodyVector);
+    /** Launches a kinematic body upward at `speed` (units per second), only while it stands on something; whether it did. */
+    jump(speed: number): boolean;
+    /** Whether the body stands on something; only a kinematic body moved by the character controller can. */
+    get grounded(): boolean;
+    /** Pushes a dynamic body with an instantaneous impulse (mass · velocity change); a no-op on any other body. */
+    applyImpulse(impulse: BodyVector): void;
+    onReady(): void;
+    onDestroy(): void;
+}

package/dist/components/rigid-body.js

@@ -0,0 +1,83 @@
+import { Component } from '../component.js';
+export const RIGID_BODY_TYPES = ['dynamic', 'kinematic'];
+const ZERO = { x: 0, y: 0, z: 0 };
+/**
+ * Makes the entity's `Collider` a body that moves (ADR 0028). A `dynamic` body
+ * is Rapier's: it falls under the scene's gravity, bounces, stacks and rests,
+ * and after every Simulation Step the engine writes the entity's position and
+ * rotation from it. A `kinematic` body is moved by code. It needs a `Collider`
+ * on the same entity (`validate_project` reports a body without one, and at
+ * runtime none is created). `mass` is the collider's mass; `velocity` is the
+ * initial linear velocity. A `kinematic` body is a character: every step the
+ * engine moves it through Rapier's character controller by its
+ * `desiredVelocity` on x and z and its own vertical velocity under gravity,
+ * stopping at walls, climbing steps up to `stepHeight` and slopes up to
+ * `maxSlope`, sticking to the ground within `snapDistance`, and pushing
+ * dynamic bodies it walks into. A param outside its range (`type` unknown,
+ * `mass` under the minimum, a `velocity` that is not three numbers) creates
+ * no body and warns once; `validate_project` reports it as
+ * `invalid-rigid-body-param`. A RigidBody in a 2D scene creates nothing.
+ */
+export class RigidBody extends Component {
+    static componentName = 'RigidBody';
+    static space = '3d';
+    static params = {
+        type: { label: 'Type', options: [...RIGID_BODY_TYPES] },
+        mass: { label: 'Mass', min: 0.001, step: 0.1 },
+        gravityScale: { label: 'Gravity scale', step: 0.1 },
+        linearDamping: { label: 'Linear damping', min: 0, step: 0.1 },
+        angularDamping: { label: 'Angular damping', min: 0, step: 0.1 },
+        lockRotations: { label: 'Lock rotations' },
+        velocity: { label: 'Initial velocity', kind: 'vector3' },
+        stepHeight: { label: 'Step height', min: 0, step: 0.05 },
+        maxSlope: { label: 'Max slope (degrees)', min: 0, max: 89, step: 1 },
+        snapDistance: { label: 'Snap to ground', min: 0, step: 0.05 },
+    };
+    // Live reads and writes of the body, not authorable defaults (they need a Game to answer).
+    static transient = ['linearVelocity', 'desiredVelocity'];
+    type = 'dynamic';
+    mass = 1;
+    gravityScale = 1;
+    linearDamping = 0;
+    angularDamping = 0;
+    lockRotations = false;
+    /** The initial linear velocity `[x, y, z]`, applied when the body is created. */
+    velocity = [0, 0, 0];
+    /** Kinematic only: the tallest step it climbs without jumping. */
+    stepHeight = 0.3;
+    /** Kinematic only: the steepest slope it climbs, in degrees. */
+    maxSlope = 45;
+    /** Kinematic only: how far below its feet it still sticks to the ground (walking down steps and slopes). */
+    snapDistance = 0.2;
+    /**
+     * Kinematic only: where it walks, in units per second on the world x and z
+     * axes. A motor sets it; the physics step reads it every Simulation Step and
+     * moves the body through the character controller. It stays until set again.
+     */
+    desiredVelocity = { x: 0, z: 0 };
+    /** The body's linear velocity now, in units per second; zero before it exists. Assigning sets it. */
+    get linearVelocity() {
+        return this.game.physics.velocityOf(this.entity) ?? { ...ZERO };
+    }
+    set linearVelocity(value) {
+        this.game.physics.setVelocityOf(this.entity, value);
+    }
+    /** Launches a kinematic body upward at `speed` (units per second), only while it stands on something; whether it did. */
+    jump(speed) {
+        return this.game.physics.jumpOf(this.entity, speed);
+    }
+    /** Whether the body stands on something; only a kinematic body moved by the character controller can. */
+    get grounded() {
+        return this.game.physics.groundedOf(this.entity);
+    }
+    /** Pushes a dynamic body with an instantaneous impulse (mass · velocity change); a no-op on any other body. */
+    applyImpulse(impulse) {
+        this.game.physics.applyImpulseTo(this.entity, impulse);
+    }
+    onReady() {
+        this.game.physics.attach(this.entity);
+    }
+    onDestroy() {
+        this.game.physics.detach(this.entity);
+    }
+}

package/dist/components/solid.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
 /**
  * Static collider. Character motors (e.g. PlatformerMotor) collide against
@@ -9,6 +9,7 @@ import { type CollisionPoint, type CollisionShape } from '../collision-shape.js'
  */
 export declare class Solid extends Component {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         offsetX: {
             label: string;

package/dist/components/solid.js

@@ -9,6 +9,7 @@ import { collisionBounds, resolveCollisionPoints, } from '../collision-shape.js'
  */
 export class Solid extends Component {
     static componentName = 'Solid';
+    static space = '2d';
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },

package/dist/components/sprite.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import type { YSortParticipant } from '../render-sort.js';
 export type SpriteShape = 'rectangle' | 'circle';
 /**
@@ -7,6 +7,7 @@ export type SpriteShape = 'rectangle' | 'circle';
  */
 export declare class Sprite extends Component implements YSortParticipant {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         offsetX: {
             label: string;

package/dist/components/sprite.js

@@ -11,6 +11,7 @@ const clampAnchor = (value) => Math.min(1, Math.max(0, value));
  */
 export class Sprite extends Component {
     static componentName = 'Sprite';
+    static space = '2d';
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },

package/dist/components/sun.d.ts

@@ -0,0 +1,46 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.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
+ * 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 {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        direction: {
+            label: string;
+            kind: "vector3";
+        };
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light: THREE.DirectionalLight | null;
+    private _direction;
+    private _color;
+    private _intensity;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction(): Vec3Json;
+    set direction(value: Vec3Json);
+    get color(): number;
+    set color(value: number);
+    get intensity(): number;
+    set intensity(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    private aim;
+}

package/dist/components/sun.js

@@ -0,0 +1,74 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.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
+ * 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 {
+    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 },
+    };
+    static transient = ['light'];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light = null;
+    _direction = [...DEFAULT_DIRECTION];
+    _color = 0xffffff;
+    _intensity = 1;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction() {
+        return [...this._direction];
+    }
+    set direction(value) {
+        // A zero or unreadable direction keeps the last good one: there is nothing to aim along.
+        if (!finiteDirection(value))
+            return;
+        this._direction = [...value];
+        this.aim();
+    }
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.light?.color.setHex(value);
+    }
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._intensity = value;
+        if (this.light)
+            this.light.intensity = value;
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        const light = new THREE.DirectionalLight(this._color, this._intensity);
+        this.light = light;
+        // The target joins the scene too, or three never updates its world matrix.
+        this.game.scene.add(light, light.target);
+        this.aim();
+    }
+    onDestroy() {
+        this.light?.removeFromParent();
+        this.light?.target.removeFromParent();
+    }
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    aim() {
+        if (!this.light)
+            return;
+        const [x, y, z] = this._direction;
+        this.light.position.set(-x, -y, -z).normalize();
+        this.light.target.position.set(0, 0, 0);
+    }
+}

package/dist/components/tilemap.d.ts

@@ -1,10 +1,11 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { SOLID_SOURCE_SYMBOL, type SolidSource } from '../scene-solids.js';
 import { type TilemapCell, type TilemapCellBounds } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export declare class Tilemap extends Component implements SolidSource {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         color: {
             label: string;

package/dist/components/tilemap.js

@@ -11,6 +11,7 @@ import { TRANSPARENT_TEXEL_ALPHA } from '../render-layers.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
+    static space = '2d';
     static params = {
         color: { label: 'color' },
         cols: { label: 'tileset columns', min: 1, step: 1 },

package/dist/entity-transform.d.ts

@@ -0,0 +1,18 @@
+import type { Entity } from './entity.js';
+/** A scene entity's position: `[x, y]` (z is 0) or `[x, y, z]`. */
+export type PositionJson = [number, number] | [number, number, number];
+/** The transform a scene or prefab entity declares, applied when it spawns. */
+export interface TransformJson {
+    /** `[x, y]` (z = 0) or `[x, y, z]`; in a 3D scene z is a world axis. */
+    position?: PositionJson;
+    /** Euler angles in degrees, order XYZ, applied to the entity's node (3D scenes). */
+    rotation?: [number, number, number];
+    /** Per-axis scale of the entity's node. */
+    scale?: [number, number, number];
+}
+/**
+ * Applies a declared transform to a freshly spawned entity. A two-number
+ * position behaves exactly as it always did (z = 0); `rotation` is converted
+ * from degrees and `scale` replaces the node's unit scale.
+ */
+export declare function applyTransformJson(entity: Entity, json: TransformJson): void;

package/dist/entity-transform.js

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+/**
+ * Applies a declared transform to a freshly spawned entity. A two-number
+ * position behaves exactly as it always did (z = 0); `rotation` is converted
+ * from degrees and `scale` replaces the node's unit scale.
+ */
+export function applyTransformJson(entity, json) {
+    const { position, rotation, scale } = json;
+    if (position)
+        entity.position.set(position[0], position[1], position[2] ?? 0);
+    if (rotation) {
+        const [x, y, z] = rotation;
+        entity.node.rotation.set(THREE.MathUtils.degToRad(x), THREE.MathUtils.degToRad(y), THREE.MathUtils.degToRad(z), 'XYZ');
+    }
+    if (scale)
+        entity.node.scale.set(scale[0], scale[1], scale[2]);
+}

package/dist/game.d.ts

@@ -1,19 +1,27 @@
 import * as THREE from 'three/webgpu';
 import { AssetLoader } from './assets/asset-loader.js';
+import type { ModelBackend } from './assets/model-backend.js';
 import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { type SceneCameraJson } from './camera.js';
+import type { SceneCameraJson } from './camera.js';
+import { type GameCamera, type WorldPoint } from './camera-projection.js';
+import { CameraRig } from './camera-rig.js';
 import { CameraEffects } from './camera-effects.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
+import type { PositionJson } from './entity-transform.js';
 import { Emitter } from './events.js';
 import { GameTime } from './game-time.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';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { type RenderBackend } from './render-readiness.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { type SceneSimulationJson } from './scene-simulation.js';
+import { type SceneSpace } from './scene-space.js';
 import { GameLighting } from './scene-lighting.js';
 import { type SpatialQuery } from './spatial-query.js';
 import { Stats, type StatValue } from './stats.js';
@@ -33,7 +41,7 @@ export interface GameOptions {
     /** Fixed resolution (from the project's game.json); absent = fill the canvas. */
     resolution?: GameResolution;
     /** Control overrides (action → key and `Gamepad:` codes) on top of the defaults. */
-    bindings?: InputBindings;
+    bindings?: Readonly<InputBindings>;
     /** Radial stick dead zone of `game.input`, in [0, 1); absent or invalid means 0.2 (ADR 0023). */
     gamepadDeadZone?: number;
     /** Initial stat values (points, lives…) from the project's stats.json. */
@@ -53,11 +61,20 @@ export interface GameOptions {
      * the real backend either way; `game.assets` always exists.
      */
     textures?: TextureBackend;
+    /** Replaces the real `GLTFLoader` implementation behind `game.assets.model` (the same seam, for glTF). */
+    models?: ModelBackend;
+    /**
+     * Where Rapier comes from for a 3D scene (ADR 0013's seam, applied to
+     * physics): resolves to the initialized module. Defaults to the real
+     * dynamic import, which only a 3D scene triggers; a project's own tests
+     * pass the module they initialized once, or a rejecting stub.
+     */
+    physics?: PhysicsBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
     name?: string;
-    position?: [number, number];
+    position?: PositionJson;
 }
 /** The Project's scenes by name (a file's stem), plus the registry shared by all of them. */
 export interface SceneCatalog {
@@ -72,7 +89,6 @@ export type ParamOverrides = Record<string, Record<string, Record<string, number
  */
 export declare class Game {
     readonly scene: THREE.Scene<THREE.Object3DEventMap>;
-    readonly camera: THREE.OrthographicCamera;
     readonly input: Input;
     readonly pointer: Pointer;
     readonly query: SpatialQuery;
@@ -100,6 +116,8 @@ export declare class Game {
     readonly lighting: GameLighting;
     /** 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. */
+    readonly physics: PhysicsHost;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -131,8 +149,17 @@ export declare class Game {
     private readonly baseViewHeight;
     private viewHeight;
     private sceneCamera;
+    /** The orthographic camera of 2D scenes and the perspective one of 3D scenes (ADR 0027); read by the Runtime Snapshot, not part of the game-facing API. */
+    readonly cameraRig: CameraRig;
+    private sceneSpace;
+    /** A 3D scene's stereo pan, reading the live camera at every call (built once, not per frame). */
+    private readonly screenPan;
+    /** What following an entity reads from the Game, built once rather than per Simulation Step. */
+    private readonly followHost;
     private renderSort;
     private sceneProjection;
+    /** The Ambient Light of a 3D scene, fed by `lighting.ambient` (ADR 0027). */
+    private readonly ambientLight3d;
     /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     private lastTime;
     /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
@@ -153,7 +180,9 @@ export declare class Game {
     constructor(options: GameOptions);
     /**
      * Resolves once the renderer can draw; rejects, naming both Render
-     * Backends, when neither initializes. Every call returns the same promise.
+     * Backends, when neither initializes. While the live scene is 3D it also
+     * waits for the physics module, and rejects naming its package if that
+     * fails to load (ADR 0028).
      * Frames before it simulate but draw nothing, so a host awaits it before
      * its first frame (ADR 0025).
      */
@@ -211,6 +240,8 @@ export declare class Game {
      * draw order stays layer-banded with spawn-order ties.
      */
     setSceneRender(json?: SceneRenderJson): void;
+    /** Adopts a scene's simulation block (gravity); called by loadScene beside setSceneRender. */
+    setSceneSimulation(json?: SceneSimulationJson): void;
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
@@ -222,7 +253,21 @@ export declare class Game {
     removeEntity(entity: Entity): void;
     /** The scene's render projection; null keeps logical and render space identical. */
     get projection(): 'isometric' | null;
-    /** Visible world height (2D camera zoom). */
+    /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
+    get space(): SceneSpace;
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    get camera(): GameCamera;
+    /**
+     * Where a logical point falls on the canvas, in CSS px from its top-left
+     * corner inside the letterbox; null when a perspective camera cannot see it
+     * (behind its near plane). The one projection Anchored Pieces, spatial
+     * audio and the editor share (CA-6).
+     */
+    worldToScreen(point: WorldPoint): {
+        x: number;
+        y: number;
+    } | null;
+    /** Visible world height (2D camera zoom); a perspective camera does not use it. */
     get view(): number;
     setViewHeight(value: number): void;
     /** Shuts the game down completely (loop, input, GPU). */
@@ -279,14 +324,5 @@ export declare class Game {
     private componentUpdateSchedule;
     private updateSceneCamera;
     private renderPoint;
-    /**
-     * The audio listener's position (CA-8) in logical coordinates. The camera
-     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
-     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
-     * inverse of `renderPoint` — without it, distance-based attenuation would
-     * measure render-space distance instead of real game distance.
-     */
-    private audioListenerPosition;
-    private dispatchCollisions;
     private resize;
 }