@waica/engine 0.24.0 → 0.26.0

package/dist/audio/audio-subsystem.d.ts

@@ -114,10 +114,15 @@ export declare class AudioSubsystem {
     updatePlacements(listener: {
         x: number;
         y: number;
+        z?: number;
     }, toRenderSpace: (x: number, y: number) => {
         x: number;
         y: number;
-    }): void;
+    }, panOf3d?: (source: {
+        x: number;
+        y: number;
+        z: number;
+    }) => number): void;
     /** Stops every live sound — including session-scoped ones — and closes the backend (CA-10). */
     dispose(): void;
     private ensureChannel;

package/dist/audio/audio-subsystem.js

@@ -1,12 +1,12 @@
 import { Entity } from '../entity.js';
-import { attenuationForDistance, panForOffset } from './spatial.js';
+import { placementMix, placementView } from './placement.js';
 import { WebAudioBackend } from './web-audio-backend.js';
 function resolvePlacement(at) {
     if (!at)
         return null;
     if (at instanceof Entity)
         return { kind: 'entity', entity: at };
-    return { kind: 'point', x: at.x, y: at.y };
+    return { kind: 'point', x: at.x, y: at.y, z: at.z ?? 0 };
 }
 const FACTORY_CHANNELS = ['music', 'sfx'];
 /**
@@ -180,23 +180,16 @@ export class AudioSubsystem {
      * reads to the right on screen pans right regardless of its logical
      * distance. A sound with no placement (a flat sound) is never touched.
      */
-    updatePlacements(listener, toRenderSpace) {
+    updatePlacements(listener, toRenderSpace, panOf3d) {
         if (this.live.size === 0)
             return;
-        let listenerRender = null;
+        const view = placementView(listener, toRenderSpace, panOf3d);
         for (const sound of this.live) {
-            if (sound.fading)
+            if (sound.fading || !sound.placement)
                 continue;
-            const placement = sound.placement;
-            if (!placement)
-                continue;
-            const source = placement.kind === 'entity'
-                ? { x: placement.entity.position.x, y: placement.entity.position.y }
-                : placement;
-            sound.attenuation = attenuationForDistance(Math.hypot(source.x - listener.x, source.y - listener.y));
-            listenerRender ??= toRenderSpace(listener.x, listener.y);
-            const sourceRender = toRenderSpace(source.x, source.y);
-            sound.pan = panForOffset(sourceRender.x - listenerRender.x);
+            const mix = placementMix(sound.placement, view);
+            sound.attenuation = mix.attenuation;
+            sound.pan = mix.pan;
             sound.backendHandle?.setVolume(sound.volume * sound.attenuation);
             sound.backendHandle?.setPan(sound.pan);
         }

package/dist/audio/placement.d.ts

@@ -0,0 +1,41 @@
+import type { Entity } from '../entity.js';
+/** Where a positional sound's placement comes from (CA-8): a tracked entity, or a fixed point. */
+export type SoundPlacement = {
+    kind: 'entity';
+    entity: Entity;
+} | {
+    kind: 'point';
+    x: number;
+    y: number;
+    z: number;
+};
+/** What one update pass places sounds against: the listener and how to pan. */
+interface PlacementView {
+    listener: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    /** The listener in render space, converted once per pass and only when a 2D sound needs it. */
+    listenerRender(): {
+        x: number;
+        y: number;
+    };
+    toRenderSpace(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /** A 3D scene's pan from where a point lands on screen; absent in a 2D scene. */
+    panOf3d?: (source: {
+        x: number;
+        y: number;
+        z: number;
+    }) => number;
+}
+export declare function placementView(listener: PlacementView['listener'], toRenderSpace: PlacementView['toRenderSpace'], panOf3d: PlacementView['panOf3d']): PlacementView;
+/** The attenuation and pan one placed sound has this frame. */
+export declare function placementMix(placement: SoundPlacement, view: PlacementView): {
+    attenuation: number;
+    pan: number;
+};
+export {};

package/dist/audio/placement.js

@@ -0,0 +1,21 @@
+import { attenuationForDistance, panForOffset } from './spatial.js';
+export function placementView(listener, toRenderSpace, panOf3d) {
+    let converted = null;
+    return {
+        listener,
+        toRenderSpace,
+        panOf3d,
+        listenerRender: () => (converted ??= toRenderSpace(listener.x, listener.y)),
+    };
+}
+/** The attenuation and pan one placed sound has this frame. */
+export function placementMix(placement, view) {
+    const source = placement.kind === 'entity' ? placement.entity.position : placement;
+    const { listener } = view;
+    // Only a listener with a z (a 3D scene's camera) measures depth.
+    const depth = listener.z === undefined ? 0 : source.z - listener.z;
+    const attenuation = attenuationForDistance(Math.hypot(source.x - listener.x, source.y - listener.y, depth));
+    if (view.panOf3d)
+        return { attenuation, pan: view.panOf3d(source) };
+    return { attenuation, pan: panForOffset(view.toRenderSpace(source.x, source.y).x - view.listenerRender().x) };
+}

package/dist/audio/spatial.d.ts

@@ -1,3 +1,5 @@
+import { type GameCamera, type ViewCamera, type WorldPoint } from '../camera-projection.js';
+import type { SceneSpace } from '../scene-space.js';
 /**
  * Engine constants for CA-8 positional audio. There are no public tuning
  * knobs (spec decision 20): the curve is picked once, in the spirit of
@@ -20,3 +22,21 @@ export declare const AUDIO_SPATIAL_DEFAULTS: {
 export declare function attenuationForDistance(distance: number): number;
 /** Maps a render-space horizontal offset (source minus listener) to a [-1, 1] stereo pan. */
 export declare function panForOffset(dx: number): number;
+/**
+ * The stereo pan of a world point in a 3D scene: where it lands across the
+ * live camera's view, -1 at the left edge to 1 at the right; 0 for a point
+ * the camera cannot see in front of it. The camera is read at every call.
+ */
+export declare function screenPanOf(camera: () => ViewCamera): (point: WorldPoint) => number;
+/**
+ * The audio listener's position (CA-8) in logical coordinates. The camera
+ * only ever holds render-space coordinates, so under `projection:
+ * 'isometric'` this is the exact inverse of the render projection — without
+ * it, distance-based attenuation would measure render-space distance instead
+ * of real game distance. A 3D scene's listener is its camera, in world space.
+ */
+export declare function listenerPosition(space: SceneSpace, camera: GameCamera, projection: 'isometric' | null): {
+    x: number;
+    y: number;
+    z?: number;
+};

package/dist/audio/spatial.js

@@ -1,3 +1,5 @@
+import { worldToNormalized } from '../camera-projection.js';
+import { unprojectIsometric } from '../projection.js';
 /**
  * Engine constants for CA-8 positional audio. There are no public tuning
  * knobs (spec decision 20): the curve is picked once, in the spirit of
@@ -30,3 +32,27 @@ export function panForOffset(dx) {
     const { panDistance } = AUDIO_SPATIAL_DEFAULTS;
     return Math.max(-1, Math.min(1, dx / panDistance));
 }
+/**
+ * The stereo pan of a world point in a 3D scene: where it lands across the
+ * live camera's view, -1 at the left edge to 1 at the right; 0 for a point
+ * the camera cannot see in front of it. The camera is read at every call.
+ */
+export function screenPanOf(camera) {
+    return (point) => {
+        const at = worldToNormalized(camera(), point);
+        return at ? Math.max(-1, Math.min(1, (at.nx - 0.5) * 2)) : 0;
+    };
+}
+/**
+ * The audio listener's position (CA-8) in logical coordinates. The camera
+ * only ever holds render-space coordinates, so under `projection:
+ * 'isometric'` this is the exact inverse of the render projection — without
+ * it, distance-based attenuation would measure render-space distance instead
+ * of real game distance. A 3D scene's listener is its camera, in world space.
+ */
+export function listenerPosition(space, camera, projection) {
+    const { x, y, z } = camera.position;
+    if (space === '3d')
+        return { x, y, z };
+    return projection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
+}

package/dist/audio/types.d.ts

@@ -17,11 +17,17 @@ export interface AudioPlayOptions {
      * from the distance to the listener (the camera) in logical coordinates;
      * panning is computed from both positions after `game.renderPoint()`, so
      * an isometric source that reads to the right on screen pans right even
-     * though its volume reflects real (logical) game distance.
+     * though its volume reflects real (logical) game distance. In a 3D scene
+     * the listener is the camera, attenuation uses the 3D distance (`z`
+     * included) and the pan follows where the source lands on screen. The
+     * 2D curve (full volume within 3 units, silent at 16) is reused, so a
+     * camera set back from the action plays what it frames quieter: from the
+     * default camera, a sound at the centre of the view is at about 37%.
      */
     at?: Entity | {
         x: number;
         y: number;
+        z?: number;
     };
 }
 export interface SoundHandle {

package/dist/camera-projection.d.ts

@@ -0,0 +1,38 @@
+import * as THREE from 'three/webgpu';
+import type { PointerCamera } from './pointer.js';
+/**
+ * What the Game's views read: the orthographic camera's frame (a duck-typed
+ * `THREE.OrthographicCamera`, which tests and the Pointer rely on) or the
+ * perspective camera of a 3D scene.
+ */
+export type ViewCamera = PointerCamera | THREE.PerspectiveCamera;
+/** The scene camera the Game draws with: one per loaded scene, by its space. */
+export type GameCamera = THREE.OrthographicCamera | THREE.PerspectiveCamera;
+/** A point in the scene's world; `z` only matters under a perspective camera. */
+export interface WorldPoint {
+    x: number;
+    y: number;
+    z?: number;
+}
+/** A position inside the game viewport: 0..1 across (left to right) and 0..1 down (top to bottom). */
+export interface NormalizedPoint {
+    nx: number;
+    ny: number;
+}
+export declare function isPerspectiveCamera(camera: ViewCamera): camera is THREE.PerspectiveCamera;
+/**
+ * The one world→view projection (CA-6): where `point` falls in the game
+ * viewport, as fractions of its width and height. Under the orthographic
+ * camera this is the formula the Pointer's screen→world mapping inverts,
+ * and `z` (draw order there) is ignored; under a perspective camera it is the
+ * camera's projection, `null` when the point is not in front of it.
+ */
+export declare function worldToNormalized(camera: ViewCamera, point: WorldPoint): NormalizedPoint | null;
+/**
+ * CSS px per world unit at the game viewport's height. Orthographic: the
+ * same everywhere. Perspective: at the depth of the world origin (the ground
+ * a scene is built around), where a unit of an Anchored Piece's CSS reads as
+ * a unit of world (its distance from the camera, front or back); nearer
+ * things look bigger, as the camera draws them.
+ */
+export declare function pixelsPerUnit(camera: ViewCamera, viewportHeight: number): number;

package/dist/camera-projection.js

@@ -0,0 +1,44 @@
+import * as THREE from 'three/webgpu';
+export function isPerspectiveCamera(camera) {
+    return 'isPerspectiveCamera' in camera && camera.isPerspectiveCamera === true;
+}
+const scratch = new THREE.Vector3();
+function projectPerspective(camera, point) {
+    camera.updateMatrixWorld();
+    scratch.set(point.x, point.y, point.z ?? 0).applyMatrix4(camera.matrixWorldInverse);
+    // The camera looks down its own -Z: at or past the near plane there is nothing to draw.
+    if (scratch.z >= -camera.near)
+        return null;
+    scratch.applyMatrix4(camera.projectionMatrix);
+    return { nx: (scratch.x + 1) / 2, ny: (1 - scratch.y) / 2 };
+}
+/**
+ * The one world→view projection (CA-6): where `point` falls in the game
+ * viewport, as fractions of its width and height. Under the orthographic
+ * camera this is the formula the Pointer's screen→world mapping inverts,
+ * and `z` (draw order there) is ignored; under a perspective camera it is the
+ * camera's projection, `null` when the point is not in front of it.
+ */
+export function worldToNormalized(camera, point) {
+    if (isPerspectiveCamera(camera))
+        return projectPerspective(camera, point);
+    return {
+        nx: (point.x - (camera.position.x + camera.left)) / (camera.right - camera.left),
+        ny: (camera.position.y + camera.top - point.y) / (camera.top - camera.bottom),
+    };
+}
+/**
+ * CSS px per world unit at the game viewport's height. Orthographic: the
+ * same everywhere. Perspective: at the depth of the world origin (the ground
+ * a scene is built around), where a unit of an Anchored Piece's CSS reads as
+ * a unit of world (its distance from the camera, front or back); nearer
+ * things look bigger, as the camera draws them.
+ */
+export function pixelsPerUnit(camera, viewportHeight) {
+    if (!isPerspectiveCamera(camera))
+        return viewportHeight / (camera.top - camera.bottom);
+    camera.updateMatrixWorld();
+    // Absolute: a camera aimed away from the origin still measures how far the ground is, not the near plane.
+    const depth = Math.max(camera.near, Math.abs(scratch.set(0, 0, 0).applyMatrix4(camera.matrixWorldInverse).z));
+    return viewportHeight / (2 * Math.tan(THREE.MathUtils.degToRad(camera.fov) / 2) * depth);
+}

package/dist/camera-rig.d.ts

@@ -0,0 +1,48 @@
+import * as THREE from 'three/webgpu';
+import { type ResolvedSceneCamera, type SceneCameraJson } from './camera.js';
+import type { GameCamera } from './camera-projection.js';
+import type { Entity } from './entity.js';
+import type { SceneSpace } from './scene-space.js';
+/** What following an entity needs from the Game: the scene's entities and its render projection. */
+export interface CameraFollowHost {
+    find(name: string): Entity | undefined;
+    /** A logical point in render space (the isometric projection, when the scene has one). */
+    renderPoint(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    /** The visible world height, i.e. the orthographic zoom, as it is when called. */
+    viewHeight(): number;
+}
+/**
+ * The Game's cameras. The orthographic one is built with the Game and frames
+ * every 2D scene; a 3D scene swaps in a perspective one (built on first use).
+ * `camera` is whichever the loaded scene uses (ADR 0027).
+ */
+export declare class CameraRig {
+    readonly orthographic: THREE.OrthographicCamera;
+    private perspective;
+    private current;
+    private aspect;
+    /** How far the perspective camera's declared target was from its declared position. */
+    private distance;
+    constructor();
+    get camera(): GameCamera;
+    /** The distance from the perspective camera to the point it was aimed at; a snapshot reports its target from it. */
+    get lookDistance(): number;
+    /**
+     * Adopts a scene's camera block for its space: a 3D scene gets the
+     * perspective camera (the block's, or the defaults), a 2D scene the
+     * orthographic one. Returns the orthographic block resolved, for follow
+     * and zoom; null when the host keeps control (no block, or a block of the
+     * wrong kind for the space, which `validate_project` reports).
+     */
+    adopt(json: SceneCameraJson | undefined, space: SceneSpace): ResolvedSceneCamera | null;
+    /** Back to the orthographic camera, as a Game with no scene has it. */
+    reset(): void;
+    /** Fits both cameras to the letterboxed view: the orthographic frame from `viewHeight`, the perspective aspect. */
+    fit(aspect: number, viewHeight: number): void;
+    /** One Simulation Step of the orthographic follow camera (deadzone, lookahead, smoothing, limits). */
+    follow(cam: ResolvedSceneCamera, host: CameraFollowHost, dt: number): void;
+    private useBlock;
+}

package/dist/camera-rig.js

@@ -0,0 +1,98 @@
+import * as THREE from 'three/webgpu';
+import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
+import { EMISSIVE_LAYER } from './render-layers.js';
+import { placePerspectiveCamera, resolvePerspectiveCamera } from './scene-camera-3d.js';
+/**
+ * The Game's cameras. The orthographic one is built with the Game and frames
+ * every 2D scene; a 3D scene swaps in a perspective one (built on first use).
+ * `camera` is whichever the loaded scene uses (ADR 0027).
+ */
+export class CameraRig {
+    orthographic = new THREE.OrthographicCamera();
+    perspective = null;
+    current = this.orthographic;
+    aspect = 1;
+    /** How far the perspective camera's declared target was from its declared position. */
+    distance = 1;
+    constructor() {
+        this.orthographic.position.z = 10;
+        // Emissive drawables sit on their own layer; an unlit frame draws it in place.
+        this.orthographic.layers.enable(EMISSIVE_LAYER);
+    }
+    get camera() {
+        return this.current;
+    }
+    /** The distance from the perspective camera to the point it was aimed at; a snapshot reports its target from it. */
+    get lookDistance() {
+        return this.distance;
+    }
+    /**
+     * Adopts a scene's camera block for its space: a 3D scene gets the
+     * perspective camera (the block's, or the defaults), a 2D scene the
+     * orthographic one. Returns the orthographic block resolved, for follow
+     * and zoom; null when the host keeps control (no block, or a block of the
+     * wrong kind for the space, which `validate_project` reports).
+     */
+    adopt(json, space) {
+        if (space === '3d') {
+            this.useBlock(json?.kind === 'perspective' ? json : undefined);
+            return null;
+        }
+        this.current = this.orthographic;
+        if (!json || json.kind === 'perspective')
+            return null;
+        return resolveSceneCamera(json);
+    }
+    /** Back to the orthographic camera, as a Game with no scene has it. */
+    reset() {
+        this.current = this.orthographic;
+    }
+    /** Fits both cameras to the letterboxed view: the orthographic frame from `viewHeight`, the perspective aspect. */
+    fit(aspect, viewHeight) {
+        this.aspect = aspect;
+        const halfH = viewHeight / 2;
+        const halfW = halfH * aspect;
+        const camera = this.orthographic;
+        camera.left = -halfW;
+        camera.right = halfW;
+        camera.top = halfH;
+        camera.bottom = -halfH;
+        camera.updateProjectionMatrix();
+        if (!this.perspective)
+            return;
+        this.perspective.aspect = aspect;
+        this.perspective.updateProjectionMatrix();
+    }
+    /** One Simulation Step of the orthographic follow camera (deadzone, lookahead, smoothing, limits). */
+    follow(cam, host, dt) {
+        const camera = this.orthographic;
+        const followed = cam.follow ? host.find(cam.follow) : undefined;
+        const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
+        const velocity = provider?.getCameraVelocity();
+        const target = followed ? host.renderPoint(followed.position.x, followed.position.y) : null;
+        const renderVelocity = velocity ? host.renderPoint(velocity.vx, velocity.vy) : { x: 0, y: 0 };
+        const next = stepSceneCamera(cam, {
+            x: camera.position.x,
+            y: camera.position.y,
+            halfW: (camera.right - camera.left) / 2,
+            halfH: host.viewHeight() / 2,
+            target,
+            vx: renderVelocity.x,
+            vy: renderVelocity.y,
+            dt,
+        });
+        camera.position.x = next.x;
+        camera.position.y = next.y;
+    }
+    useBlock(json) {
+        if (!this.perspective) {
+            this.perspective = new THREE.PerspectiveCamera();
+            // A 3D scene is never lit, so an Emissive drawable is drawn in place on the camera's own layers.
+            this.perspective.layers.enable(EMISSIVE_LAYER);
+        }
+        const resolved = resolvePerspectiveCamera(json);
+        placePerspectiveCamera(this.perspective, resolved, this.aspect);
+        this.distance = new THREE.Vector3(...resolved.position).distanceTo(new THREE.Vector3(...resolved.target)) || 1;
+        this.current = this.perspective;
+    }
+}

package/dist/camera.d.ts

@@ -1,3 +1,4 @@
+import { type PerspectiveSceneCameraJson, type ResolvedPerspectiveCamera } from './scene-camera-3d.js';
 /**
  * The scene camera: a built-in, singular part of every scene — not a
  * component you attach to an entity. The scene JSON carries its framing
@@ -11,7 +12,10 @@ export interface CameraLimitsJson {
     minY: number;
     maxY: number;
 }
-export interface SceneCameraJson {
+/** The 2D scene camera: an orthographic view of the XY plane. */
+export interface OrthographicSceneCameraJson {
+    /** The default; written only to be explicit. */
+    kind?: 'orthographic';
     /** Where the camera starts (and stays, without a follow target). */
     position?: [number, number];
     /** Visible world height in units — the camera's zoom. */
@@ -26,7 +30,15 @@ export interface SceneCameraJson {
     smoothing?: number;
     limits?: CameraLimitsJson;
 }
+/**
+ * A scene's camera block: orthographic (2D scenes) or perspective (scenes
+ * with `render.space: '3d'`), told apart by `kind`.
+ */
+export type SceneCameraJson = OrthographicSceneCameraJson | PerspectiveSceneCameraJson;
+export type { PerspectiveSceneCameraJson, ResolvedPerspectiveCamera };
+/** The orthographic camera block, filled in. It carries no `kind`: the shape 2D scenes always had. */
 export interface ResolvedSceneCamera {
+    kind?: 'orthographic';
     position: [number, number];
     zoom: number;
     follow: string;
@@ -47,8 +59,13 @@ export declare const CAMERA_DEFAULTS: {
     readonly lookaheadY: 0;
     readonly smoothing: 6;
 };
-/** Fills a scene's camera block with the engine defaults. */
-export declare function resolveSceneCamera(json?: SceneCameraJson): ResolvedSceneCamera;
+/**
+ * Fills a scene's camera block with the engine defaults: the orthographic
+ * block (or none) as it always was, a perspective block with the 3D defaults.
+ */
+export declare function resolveSceneCamera(json?: OrthographicSceneCameraJson): ResolvedSceneCamera;
+export declare function resolveSceneCamera(json: PerspectiveSceneCameraJson): ResolvedPerspectiveCamera;
+export declare function resolveSceneCamera(json?: SceneCameraJson): ResolvedSceneCamera | ResolvedPerspectiveCamera;
 /** Two-axis velocity a followed entity reports for camera lookahead. */
 export interface CameraVelocity {
     vx: number;

package/dist/camera.js

@@ -1,4 +1,5 @@
 import * as THREE from 'three/webgpu';
+import { resolvePerspectiveCamera, } from './scene-camera-3d.js';
 export const CAMERA_DEFAULTS = {
     position: [0, 0],
     zoom: 12,
@@ -9,8 +10,9 @@ export const CAMERA_DEFAULTS = {
     lookaheadY: 0,
     smoothing: 6,
 };
-/** Fills a scene's camera block with the engine defaults. */
 export function resolveSceneCamera(json) {
+    if (json?.kind === 'perspective')
+        return resolvePerspectiveCamera(json);
     return {
         position: json?.position ?? CAMERA_DEFAULTS.position,
         zoom: json?.zoom ?? CAMERA_DEFAULTS.zoom,

package/dist/component.d.ts

@@ -8,12 +8,21 @@ export interface ParamSpec {
     max?: number;
     step?: number;
     /** Specialized editor control for values that are otherwise plain JSON. */
-    kind?: 'string-list' | 'vector2' | 'color' | 'texture';
+    kind?: 'string-list' | 'vector2' | 'vector3' | 'color' | 'texture' | 'model';
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
     ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound' | 'ui';
 }
+/**
+ * The scene space a component belongs to (ADR 0027): `'2d'` components draw,
+ * collide or light the orthographic world, move or query over its x/y plane,
+ * or need a sibling that does; `'3d'` ones need a perspective camera;
+ * `'both'` run anywhere. A component that declares nothing is `'both'`.
+ */
+export type ComponentSpace = '2d' | '3d' | 'both';
+/** The values of `ComponentSpace`, for the checks that read a marker from data (the project component protocol, conformance). */
+export declare const COMPONENT_SPACES: readonly ComponentSpace[];
 export interface ComponentClass<T extends Component = Component> {
     new (): T;
     /**
@@ -27,6 +36,8 @@ export interface ComponentClass<T extends Component = Component> {
     params?: Record<string, ParamSpec>;
     /** Sibling component updates that must complete before this one when present. */
     updateAfter?: readonly string[];
+    /** The scene space this component belongs to; absent means both. */
+    space?: ComponentSpace;
     /**
      * Instance fields holding runtime state rather than authorable defaults.
      * Excluded from authoringDefaults(); a subclass that does not redeclare
@@ -47,6 +58,25 @@ export interface SolidContact {
     readonly axis: 'x' | 'y';
     readonly normal: ContactNormal;
 }
+/** A 3D contact between two entities' solid Colliders, read after the physics step. */
+export interface BodyContact {
+    /** The entity whose component receives the hook. */
+    readonly entity: Entity;
+    /** The entity it is in contact with. */
+    readonly other: Entity;
+    /** Unit normal in world space, pointing from `entity` to `other`. */
+    readonly normal: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    /** A world-space point on the contact. */
+    readonly point: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+}
 /**
  * A pluggable piece of an entity. User behaviors and engine ones are the
  * same thing: Component subclasses with public props.
@@ -56,6 +86,7 @@ export declare abstract class Component {
     static displayName?: string;
     static params?: Record<string, ParamSpec>;
     static updateAfter?: readonly string[];
+    static space?: ComponentSpace;
     static transient?: readonly string[];
     entity: Entity;
     game: Game;
@@ -67,8 +98,13 @@ export declare abstract class Component {
     onUpdate?(dt: number): void;
     /** Runs after the scene changes between identity and projected rendering. */
     onProjectionChange?(projection: 'isometric' | null): void;
-    /** Runs on overlap when this entity's Hitbox mask names the other's layer. */
+    /**
+     * Runs on overlap when this entity's Hitbox (2D) or sensor Collider (3D)
+     * mask names the other's layer.
+     */
     onCollide?(other: Entity): void;
+    /** Runs once per Simulation Step for each entity this entity's solid Collider is in contact with (3D, issue #159). */
+    onBodyContact?(contact: BodyContact): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;
     /**

package/dist/component.js

@@ -1,3 +1,5 @@
+/** The values of `ComponentSpace`, for the checks that read a marker from data (the project component protocol, conformance). */
+export const COMPONENT_SPACES = ['2d', '3d', 'both'];
 /**
  * A pluggable piece of an entity. User behaviors and engine ones are the
  * same thing: Component subclasses with public props.
@@ -7,6 +9,7 @@ export class Component {
     static displayName;
     static params;
     static updateAfter;
+    static space;
     static transient;
     entity;
     game;

package/dist/components/animated-sprite.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { type ClipDef } from '../animation/clip-player.js';
 import { type SheetCell, type SheetDef } from '../animation/sheet.js';
 import type { YSortParticipant } from '../render-sort.js';
@@ -14,6 +14,7 @@ import type { YSortParticipant } from '../render-sort.js';
  */
 export declare class AnimatedSprite extends Component implements YSortParticipant {
     static componentName: string;
+    static space: ComponentSpace;
     static updateAfter: readonly string[];
     static params: {
         offsetX: {
@@ -40,6 +41,9 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
             max: number;
             step: number;
         };
+        emissive: {
+            label: string;
+        };
     };
     static transient: string[];
     /** Spritesheet URL. */
@@ -85,6 +89,9 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     flipX: boolean;
     /** Mirrors the quad horizontally — directional clips reuse east art for west. */
     setFlipX(value: boolean): void;
+    private _emissive;
+    get emissive(): boolean;
+    set emissive(value: boolean);
     clips: Record<string, ClipDef>;
     initialClip?: string;
     /** Clip currently playing. */