@waica/engine 0.25.0 → 0.27.0

package/dist/scene-camera-3d.js

@@ -0,0 +1,117 @@
+export const PERSPECTIVE_DEFAULTS = {
+    position: [0, 5, 10],
+    target: [0, 0, 0],
+    fov: 60,
+    near: 0.1,
+    far: 1000,
+};
+/** True for a perspective camera block; everything else (or none) is the orthographic one. */
+export function isPerspectiveCameraJson(json) {
+    return json?.kind === 'perspective';
+}
+/** Fills a perspective camera block with the engine defaults. */
+export function resolvePerspectiveCamera(json = { kind: 'perspective' }) {
+    return {
+        kind: 'perspective',
+        position: json.position ?? PERSPECTIVE_DEFAULTS.position,
+        target: json.target ?? PERSPECTIVE_DEFAULTS.target,
+        fov: json.fov ?? PERSPECTIVE_DEFAULTS.fov,
+        near: json.near ?? PERSPECTIVE_DEFAULTS.near,
+        far: json.far ?? PERSPECTIVE_DEFAULTS.far,
+    };
+}
+/** Points `camera` as the resolved block says, at the given aspect ratio. */
+export function placePerspectiveCamera(camera, resolved, aspect) {
+    camera.fov = resolved.fov;
+    camera.near = resolved.near;
+    camera.far = resolved.far;
+    camera.aspect = aspect;
+    camera.position.set(...resolved.position);
+    camera.lookAt(...resolved.target);
+    camera.updateProjectionMatrix();
+    camera.updateMatrixWorld();
+}
+/** A JSON value as a message quotes it: strings in quotes, everything else as `String()` shows it. */
+export const shown = (value) => (typeof value === 'string' ? JSON.stringify(value) : String(value));
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function vectorIssue(field, value, issues) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber))
+        return;
+    issues.push({ field, message: `${field} must be three finite numbers [x, y, z]; got ${JSON.stringify(value)}.` });
+}
+function fovIssue(value, issues) {
+    if (value === undefined)
+        return;
+    if (isFiniteNumber(value) && value > 0 && value < 180)
+        return;
+    issues.push({ field: 'camera.fov', message: `camera.fov must be a number above 0 and below 180; got ${shown(value)}.` });
+}
+/** `position` and `target` as the camera would use them, when both are well-formed (declared or default). */
+function resolvedAim(block) {
+    const position = block.position ?? PERSPECTIVE_DEFAULTS.position;
+    const target = block.target ?? PERSPECTIVE_DEFAULTS.target;
+    const wellFormed = (value) => Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber);
+    return wellFormed(position) && wellFormed(target) ? { position, target } : null;
+}
+function aimIssue(block, issues) {
+    const aim = resolvedAim(block);
+    if (!aim || aim.position.some((value, axis) => value !== aim.target[axis]))
+        return;
+    issues.push({
+        field: 'camera.target',
+        message: `camera.target must differ from camera.position (${JSON.stringify(aim.position)}): a camera needs a direction to look in.`,
+    });
+}
+function planeIssues(near, far, issues) {
+    const nearIsValid = isFiniteNumber(near) && near > 0;
+    if (near !== undefined && !nearIsValid) {
+        issues.push({ field: 'camera.near', message: `camera.near must be a number above 0; got ${shown(near)}.` });
+    }
+    const nearValue = nearIsValid ? near : PERSPECTIVE_DEFAULTS.near;
+    if (far !== undefined && !(isFiniteNumber(far) && far > nearValue)) {
+        issues.push({ field: 'camera.far', message: `camera.far must be a number above near (${nearValue}); got ${shown(far)}.` });
+    }
+}
+/** The orthographic block's fields, which a perspective block does not accept. */
+const ORTHOGRAPHIC_ONLY_FIELDS = [
+    'follow',
+    'zoom',
+    'deadzoneWidth',
+    'deadzoneHeight',
+    'lookahead',
+    'lookaheadY',
+    'smoothing',
+    'limits',
+];
+function orthographicFieldIssues(block, issues) {
+    for (const field of ORTHOGRAPHIC_ONLY_FIELDS) {
+        if (block[field] === undefined)
+            continue;
+        issues.push({ field: `camera.${field}`, message: `camera.${field} belongs to an orthographic camera; a perspective camera does not accept it.` });
+    }
+}
+/**
+ * Every field of a perspective camera block outside its range: `fov` in
+ * (0, 180), `near` above 0, `far` above `near`, and `position` and `target`
+ * three finite numbers, and none of the orthographic block's fields. Anything
+ * that is not a perspective block reports none.
+ */
+export function perspectiveCameraIssues(camera) {
+    if (typeof camera !== 'object' || camera === null)
+        return [];
+    const block = { ...camera };
+    if (block.kind !== 'perspective')
+        return [];
+    const issues = [];
+    vectorIssue('camera.position', block.position, issues);
+    vectorIssue('camera.target', block.target, issues);
+    fovIssue(block.fov, issues);
+    aimIssue(block, issues);
+    planeIssues(block.near, block.far, issues);
+    orthographicFieldIssues(block, issues);
+    return issues;
+}

package/dist/scene-lights-3d.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three/webgpu';
+import type { SceneSpace } from './scene-space.js';
+import type { AmbientLight } from './scene-render-options.js';
+/**
+ * The Ambient Light of a 3D scene (ADR 0027): one `THREE.AmbientLight` the
+ * Game owns, fed by `game.lighting.ambient` (`render.lighting.ambient` and the
+ * runtime setter), color × intensity, full white when nothing says otherwise.
+ * It exists only while the live scene is 3D; a 2D scene lights through the
+ * light-map instead (ADR 0026).
+ */
+export declare class SceneAmbientLight3d {
+    private readonly scene;
+    private light;
+    constructor(scene: THREE.Scene);
+    /** Adds, updates or removes the light for the live scene's space; called once per frame before it is drawn. */
+    sync(space: SceneSpace, ambient: AmbientLight): void;
+}

package/dist/scene-lights-3d.js

@@ -0,0 +1,27 @@
+import * as THREE from 'three/webgpu';
+/**
+ * The Ambient Light of a 3D scene (ADR 0027): one `THREE.AmbientLight` the
+ * Game owns, fed by `game.lighting.ambient` (`render.lighting.ambient` and the
+ * runtime setter), color × intensity, full white when nothing says otherwise.
+ * It exists only while the live scene is 3D; a 2D scene lights through the
+ * light-map instead (ADR 0026).
+ */
+export class SceneAmbientLight3d {
+    scene;
+    light = null;
+    constructor(scene) {
+        this.scene = scene;
+    }
+    /** Adds, updates or removes the light for the live scene's space; called once per frame before it is drawn. */
+    sync(space, ambient) {
+        if (space !== '3d') {
+            this.light?.removeFromParent();
+            return;
+        }
+        this.light ??= new THREE.AmbientLight();
+        if (this.light.parent !== this.scene)
+            this.scene.add(this.light);
+        this.light.color.set(ambient.color);
+        this.light.intensity = ambient.intensity;
+    }
+}

package/dist/scene-simulation.d.ts

@@ -0,0 +1,22 @@
+import { type SceneFieldIssue, type Vec3Json } from './scene-camera-3d.js';
+import type { SceneSpace } from './scene-space.js';
+/**
+ * A 3D scene's `simulation` block (issue #159): the physics world's settings.
+ * Absent, or with `gravity` absent, the world pulls along -y at 9.81.
+ */
+export interface SceneSimulationJson {
+    /** The world's gravity vector in units per second squared. Default `[0, -9.81, 0]`. */
+    gravity?: Vec3Json;
+}
+export interface ResolvedSceneSimulation {
+    gravity: Vec3Json;
+}
+export declare const DEFAULT_GRAVITY: Readonly<Vec3Json>;
+/** The simulation a scene runs with: its `simulation` block, defaults filling the rest. A malformed gravity reads as the default (`validate_project` reports it). */
+export declare function resolveSceneSimulation(json: SceneSimulationJson | undefined): ResolvedSceneSimulation;
+/**
+ * Every invalid field of a scene's `simulation` block: a gravity that is not
+ * three finite numbers in a 3d scene, and any block at all in a 2d one, where
+ * nothing simulates.
+ */
+export declare function sceneSimulationIssues(simulation: unknown, space: SceneSpace): SceneFieldIssue[];

package/dist/scene-simulation.js

@@ -0,0 +1,29 @@
+import { isFiniteNumber } from './scene-camera-3d.js';
+export const DEFAULT_GRAVITY = [0, -9.81, 0];
+function isVec3(value) {
+    return Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber);
+}
+/** The simulation a scene runs with: its `simulation` block, defaults filling the rest. A malformed gravity reads as the default (`validate_project` reports it). */
+export function resolveSceneSimulation(json) {
+    const gravity = json?.gravity;
+    return { gravity: isVec3(gravity) ? [...gravity] : [...DEFAULT_GRAVITY] };
+}
+/**
+ * Every invalid field of a scene's `simulation` block: a gravity that is not
+ * three finite numbers in a 3d scene, and any block at all in a 2d one, where
+ * nothing simulates.
+ */
+export function sceneSimulationIssues(simulation, space) {
+    if (simulation === undefined)
+        return [];
+    if (space === '2d') {
+        return [{ field: 'simulation', message: `A simulation block needs render.space '3d'; this scene is 2d, where nothing simulates.` }];
+    }
+    if (typeof simulation !== 'object' || simulation === null || Array.isArray(simulation)) {
+        return [{ field: 'simulation', message: `simulation must be an object; got ${JSON.stringify(simulation)}.` }];
+    }
+    const gravity = Reflect.get(simulation, 'gravity');
+    if (gravity === undefined || isVec3(gravity))
+        return [];
+    return [{ field: 'simulation.gravity', message: `simulation.gravity must be three finite numbers [x, y, z]; got ${JSON.stringify(gravity)}.` }];
+}

package/dist/scene-space.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentClass, ComponentSpace } from './component.js';
+import { type SceneFieldIssue } from './scene-camera-3d.js';
+/**
+ * A scene's space (ADR 0027): `'2d'` is the engine's orthographic world,
+ * where `z` is draw order; `'3d'` makes `z` a world axis under a perspective
+ * camera and a real depth buffer. A scene declares it as `render.space`.
+ */
+export type SceneSpace = '2d' | '3d';
+export declare const SCENE_SPACES: readonly SceneSpace[];
+/** The scene's space: 3d only when `render.space` says exactly so. */
+export declare function resolveSceneSpace(render: unknown): SceneSpace;
+/**
+ * What a scene's render block makes of the draw-order options at runtime. A
+ * 3D scene has no y-sort and no isometric projection whatever the block
+ * says (`validate_project` reports them); a 2D scene reads them as always.
+ */
+export declare function resolveRenderPolicy(render: unknown): {
+    space: SceneSpace;
+    sort: 'y' | null;
+    projection: 'isometric' | null;
+};
+/**
+ * What a component class says about the space it belongs to: its `static
+ * space` marker, or nothing. Only that slice of `ComponentClass`, so the
+ * abstract `Component` and a class the caller builds by hand qualify too.
+ */
+export type SpaceMarked = Pick<ComponentClass, 'space'>;
+/** The space a component class belongs to; a class that declares none is `'both'`. */
+export declare function componentSpaceOf(Class: SpaceMarked): ComponentSpace;
+/**
+ * True when a component of this class does not belong in a scene of this
+ * space: a `'2d'` component in 3d, a `'3d'` one in 2d. Reads the class's
+ * `static space` marker, so engine, behavior and project-owned components
+ * answer the same way. A class the caller does not know (undefined) is
+ * space-neutral.
+ */
+export declare function componentSpaceMismatch(space: SceneSpace, Class: SpaceMarked | undefined): boolean;
+/**
+ * Every invalid field of a scene's `render.space`, its camera block and the
+ * render options a 3d scene cannot use: a space outside `'2d' | '3d'`, a
+ * camera that does not match the space, a perspective camera out of range
+ * and `render.sort`, `render.projection` or `render.batch` under 3d. Other
+ * render fields are `sceneRenderIssues`'s.
+ */
+export declare function sceneSpaceIssues(render: unknown, camera: unknown): SceneFieldIssue[];
+/**
+ * An entity's `position` (2 or 3 finite numbers), `rotation` (degrees) and
+ * `scale` (3 finite numbers each) that are anything else.
+ */
+export declare function entityTransformIssues(entity: unknown): SceneFieldIssue[];

package/dist/scene-space.js

@@ -0,0 +1,103 @@
+import { isFiniteNumber, perspectiveCameraIssues, shown } from './scene-camera-3d.js';
+export const SCENE_SPACES = ['2d', '3d'];
+/** The scene's space: 3d only when `render.space` says exactly so. */
+export function resolveSceneSpace(render) {
+    return recordOf(render).space === '3d' ? '3d' : '2d';
+}
+/**
+ * What a scene's render block makes of the draw-order options at runtime. A
+ * 3D scene has no y-sort and no isometric projection whatever the block
+ * says (`validate_project` reports them); a 2D scene reads them as always.
+ */
+export function resolveRenderPolicy(render) {
+    const block = recordOf(render);
+    const space = resolveSceneSpace(block);
+    const flat = space === '2d';
+    return {
+        space,
+        sort: flat && block.sort === 'y' ? 'y' : null,
+        projection: flat && block.projection === 'isometric' ? 'isometric' : null,
+    };
+}
+/** The space a component class belongs to; a class that declares none is `'both'`. */
+export function componentSpaceOf(Class) {
+    return Class.space ?? 'both';
+}
+/**
+ * True when a component of this class does not belong in a scene of this
+ * space: a `'2d'` component in 3d, a `'3d'` one in 2d. Reads the class's
+ * `static space` marker, so engine, behavior and project-owned components
+ * answer the same way. A class the caller does not know (undefined) is
+ * space-neutral.
+ */
+export function componentSpaceMismatch(space, Class) {
+    if (Class === undefined)
+        return false;
+    const own = componentSpaceOf(Class);
+    return own !== 'both' && own !== space;
+}
+function recordOf(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? { ...value } : {};
+}
+/** Fields of `render` that only mean something in a 2D scene. */
+const TWO_D_RENDER_FIELDS = ['sort', 'projection', 'batch'];
+function cameraKindIssue(space, camera, issues) {
+    if (camera === undefined || camera === null)
+        return;
+    const kind = recordOf(camera).kind;
+    if (kind !== undefined && kind !== 'orthographic' && kind !== 'perspective') {
+        issues.push({ field: 'camera.kind', message: `camera.kind must be 'orthographic' or 'perspective'; got ${shown(kind)}.` });
+        return;
+    }
+    if (space === '2d' && kind === 'perspective') {
+        issues.push({ field: 'camera.kind', message: `A perspective camera needs render.space '3d'; this scene is 2d.` });
+    }
+    if (space === '3d' && kind !== 'perspective') {
+        issues.push({ field: 'camera.kind', message: `A 3d scene needs a perspective camera (kind: 'perspective'); got an orthographic one.` });
+    }
+}
+/**
+ * Every invalid field of a scene's `render.space`, its camera block and the
+ * render options a 3d scene cannot use: a space outside `'2d' | '3d'`, a
+ * camera that does not match the space, a perspective camera out of range
+ * and `render.sort`, `render.projection` or `render.batch` under 3d. Other
+ * render fields are `sceneRenderIssues`'s.
+ */
+export function sceneSpaceIssues(render, camera) {
+    const block = recordOf(render);
+    const issues = [];
+    if (block.space !== undefined && block.space !== '2d' && block.space !== '3d') {
+        issues.push({ field: 'render.space', message: `render.space must be '2d' or '3d'; got ${shown(block.space)}.` });
+    }
+    const space = resolveSceneSpace(block);
+    cameraKindIssue(space, camera, issues);
+    issues.push(...perspectiveCameraIssues(camera));
+    if (space === '3d') {
+        for (const field of TWO_D_RENDER_FIELDS) {
+            if (block[field] === undefined)
+                continue;
+            issues.push({ field: `render.${field}`, message: `render.${field} is a 2D option and has no meaning in a 3d scene.` });
+        }
+    }
+    return issues;
+}
+function tupleIssue(issues, { field, lengths }, value) {
+    if (value === undefined)
+        return;
+    if (Array.isArray(value) && lengths.includes(value.length) && value.every(isFiniteNumber))
+        return;
+    const need = lengths.join(' or ');
+    issues.push({ field, message: `${field} must be ${need} finite numbers; got ${JSON.stringify(value)}.` });
+}
+/**
+ * An entity's `position` (2 or 3 finite numbers), `rotation` (degrees) and
+ * `scale` (3 finite numbers each) that are anything else.
+ */
+export function entityTransformIssues(entity) {
+    const json = recordOf(entity);
+    const issues = [];
+    tupleIssue(issues, { field: 'position', lengths: [2, 3] }, json.position);
+    tupleIssue(issues, { field: 'rotation', lengths: [3] }, json.rotation);
+    tupleIssue(issues, { field: 'scale', lengths: [3] }, json.scale);
+    return issues;
+}

package/dist/scene.d.ts

@@ -1,7 +1,10 @@
 import type { SceneCameraJson } from './camera.js';
 import type { ComponentClass } from './component.js';
 import type { Entity } from './entity.js';
+import { type TransformJson } from './entity-transform.js';
 import type { Game } from './game.js';
+import type { SceneSimulationJson } from './scene-simulation.js';
+import type { SceneSpace } from './scene-space.js';
 /**
  * Waica's scene format: declarative, git-friendly data, editable by the
  * visual editor. The scene is the source of truth; the Game is its live
@@ -11,9 +14,8 @@ export interface SceneComponentJson {
     type: string;
     props?: Record<string, unknown>;
 }
-export interface SceneEntityJson {
+export interface SceneEntityJson extends TransformJson {
     name: string;
-    position?: [number, number];
     /** Prefab ref like "characters/slime", resolved against SceneRegistry.prefabs. */
     prefab?: string;
     /** Per-component prop overrides on top of the prefab: componentType -> propName -> value. */
@@ -55,6 +57,12 @@ export interface ScenePostJson {
 }
 /** Scene-wide render options (v3). */
 export interface SceneRenderJson {
+    /**
+     * `'2d'` (the default) or `'3d'` (ADR 0027). A 3D scene makes `z` a world
+     * axis under a perspective camera with a depth buffer; there is no layer
+     * band, y-sort, isometric projection, sprite batch or light-map in it.
+     */
+    space?: SceneSpace;
     /** Ambient Light; with it (or any Light) the scene is lit (ADR 0026). */
     lighting?: SceneLightingJson;
     /** Vignette and color grade; with either on, the frame renders through a render target. */
@@ -83,6 +91,8 @@ export interface SceneJson {
     camera?: SceneCameraJson;
     /** Draw-order policy (v3); absent = layer bands with spawn-order ties. */
     render?: SceneRenderJson;
+    /** The physics world's settings (v3, 3D scenes only): gravity. Absent = earth gravity. */
+    simulation?: SceneSimulationJson;
     entities: SceneEntityJson[];
     /** UI pieces (src/ui/*.html) mounted visible when the scene loads. */
     ui?: string[];

package/dist/scene.js

@@ -1,3 +1,4 @@
+import { applyTransformJson } from './entity-transform.js';
 /**
  * Own-property lookup. Scene JSON is data — a component or prefab named
  * "constructor" or "toString" must read as missing, not as whatever sits
@@ -69,6 +70,7 @@ const COMPONENT_MEMBERS = {
     onProjectionChange: true,
     onCollide: true,
     onContact: true,
+    onBodyContact: true,
     onInteract: true,
     onDestroy: true,
 };
@@ -91,8 +93,7 @@ function sceneProps(props, type, entityName) {
 }
 export function spawnFromJson(game, json, registry) {
     const entity = game.spawn(json.name);
-    if (json.position)
-        entity.position.set(json.position[0], json.position[1], 0);
+    applyTransformJson(entity, json);
     for (const comp of resolveEntityComponents(json, registry.prefabs)) {
         const Class = registryEntry(registry.components, comp.type);
         if (!Class) {
@@ -131,10 +132,16 @@ export function loadScene(game, scene, registry) {
     }
     game.registry = registry;
     game.setSceneRender(scene.render);
+    game.setSceneSimulation(scene.simulation);
+    // A perspective camera has no follow target to wait for: components see it from their first onReady.
+    const adoptsBeforeSpawns = game.space === '3d';
+    if (adoptsBeforeSpawns)
+        game.setSceneCamera(scene.camera);
     for (const entityJson of scene.entities)
         spawnFromJson(game, entityJson, registry);
-    // After the spawns: with a follow target, the camera starts centered on it.
-    game.setSceneCamera(scene.camera);
+    // After the spawns: with a follow target, the orthographic camera starts centered on it.
+    if (!adoptsBeforeSpawns)
+        game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);
     // Scene-scoped: Game.unloadScene() unmounts these along with the entities.

package/dist/simulation-phases.d.ts

@@ -0,0 +1,9 @@
+import type { Game } from './game.js';
+/**
+ * What a Simulation Step does after every component's `onUpdate` (issue #159
+ * CA-10), in this order: the 3D physics step (one `world.step()` of the live
+ * scene's Rapier world, a no-op in a 2D scene or while the module loads), the
+ * solid contacts it produced, the 2D Hitbox triggers, and the 3D sensor
+ * triggers. Kept out of `game.ts`, which is at the file-size tier.
+ */
+export declare function runSimulationPhases(game: Game): void;

package/dist/simulation-phases.js

@@ -0,0 +1,19 @@
+import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
+import { dispatchBodyContacts } from './physics-3d/body-contacts.js';
+import { dispatchSensorCollisions } from './physics-3d/sensor-dispatch.js';
+/**
+ * What a Simulation Step does after every component's `onUpdate` (issue #159
+ * CA-10), in this order: the 3D physics step (one `world.step()` of the live
+ * scene's Rapier world, a no-op in a 2D scene or while the module loads), the
+ * solid contacts it produced, the 2D Hitbox triggers, and the 3D sensor
+ * triggers. Kept out of `game.ts`, which is at the file-size tier.
+ */
+export function runSimulationPhases(game) {
+    const world = game.physics.world;
+    world?.step();
+    if (world)
+        dispatchBodyContacts(game, world);
+    dispatchHitboxCollisions(game);
+    if (world && game.physics.world === world)
+        dispatchSensorCollisions(game, world);
+}

package/dist/spatial-query-3d.d.ts

@@ -0,0 +1,48 @@
+import type { Collider } from './components/collider.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import { type Point3d, type QueryVolume3d } from './physics-3d/world-queries.js';
+import type { ComponentClasses, NearestSpatialQueryFilter, SpatialQueryFilter } from './spatial-query.js';
+export type { Point3d, QueryVolume3d } from './physics-3d/world-queries.js';
+/** The first solid collider a 3D ray reached, with its entity and the crossing (issue #159 CA-21). */
+export interface RayHit3d<T extends Entity = Entity> {
+    readonly entity: T;
+    readonly collider: Collider;
+    readonly distance: number;
+    readonly point: Readonly<Point3d>;
+    readonly normal: Readonly<Point3d>;
+}
+type Filter = SpatialQueryFilter<ComponentClasses> | undefined;
+type NearestFilter = NearestSpatialQueryFilter<ComponentClasses> | undefined;
+/** The structural part of the entity filter the 2D forms use (`with`, `without`, `exclude`), shared with the 3D ones (`spatial-query.ts` owns it). */
+export interface EntityRules {
+    matchesCommon(entity: Entity, filter: NearestFilter): boolean;
+}
+/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors, `nearest` reads transforms. */
+export declare class SpatialQuery3d {
+    private readonly game;
+    private readonly rules;
+    constructor(game: Game, rules: EntityRules);
+    /** `direction` need not be a unit vector; `maxDistance` is in world units. */
+    ray(aim: {
+        origin: Point3d;
+        direction: Point3d;
+    }, maxDistance: number, filter?: Filter): RayHit3d | null;
+    area(volume: QueryVolume3d, filter?: Filter): Entity[];
+    point(at: Point3d, filter?: Filter): Entity[];
+    nearest(at: Point3d, filter?: NearestFilter): Entity | null;
+    /** How far the entity is from the search, when it is alive, passes the filter and lies within range. */
+    private distanceIfEligible;
+    /** The live world with its query structure current, or null while there is none. */
+    private worldNow;
+    /**
+     * A live entity's collider the query domain reads (solids for a ray, sensors
+     * for area and point) that passes the structural filter. Runs inside
+     * Rapier's callback, so it reads the record and nothing else.
+     */
+    private eligible;
+    /** The user's `where`, run after Rapier has answered: it may throw, spawn or destroy without the world mid-query. */
+    private wanted;
+    /** The entities of the records that pass `where`, once each, in the order they were spawned. */
+    private inEntityOrder;
+}

package/dist/spatial-query-3d.js

@@ -0,0 +1,96 @@
+import { recordsAtPoint, recordsInVolume, worldRayHits } from './physics-3d/world-queries.js';
+const isPoint3d = (value) => typeof value === 'object' && value !== null && ['x', 'y', 'z'].every((axis) => Number.isFinite(Reflect.get(value, axis)));
+const isExtent = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0;
+/** A finite box or sphere with a place: anything else is a volume Rapier cannot test. */
+function isVolume3d(value) {
+    if (typeof value !== 'object' || value === null || !isPoint3d(Reflect.get(value, 'center')))
+        return false;
+    const shape = Reflect.get(value, 'shape');
+    if (shape === 'sphere')
+        return isExtent(Reflect.get(value, 'radius'));
+    const size = Reflect.get(value, 'size');
+    return shape === 'box' && typeof size === 'object' && size !== null && ['x', 'y', 'z'].every((axis) => isExtent(Reflect.get(size, axis)));
+}
+/** The farthest a nearest query looks: its `maxDistance`, or no limit. */
+const rangeOf = (filter) => filter?.maxDistance ?? Infinity;
+/** The 3D forms of `game.query` (ADR 0015's domains kept): `ray` reads solids, `area` and `point` read sensors, `nearest` reads transforms. */
+export class SpatialQuery3d {
+    game;
+    rules;
+    constructor(game, rules) {
+        this.game = game;
+        this.rules = rules;
+    }
+    /** `direction` need not be a unit vector; `maxDistance` is in world units. */
+    ray(aim, maxDistance, filter) {
+        const { origin, direction } = aim;
+        const world = this.worldNow();
+        const length = isPoint3d(direction) ? Math.hypot(direction.x, direction.y, direction.z) : 0;
+        if (!world || !isPoint3d(origin) || length === 0 || !(maxDistance >= 0) || !Number.isFinite(maxDistance))
+            return null;
+        const unit = { x: direction.x / length, y: direction.y / length, z: direction.z / length };
+        const hits = worldRayHits(world, { origin, direction: unit, maxDistance }, (record) => this.eligible(record, filter, false));
+        // The user's `where` runs here, outside Rapier's borrow of the world: the first hit it keeps wins.
+        const hit = hits.find(({ record }) => this.wanted(record, filter));
+        if (!hit)
+            return null;
+        return { entity: hit.record.entity, collider: hit.record.collider, distance: hit.distance, point: hit.point, normal: hit.normal };
+    }
+    area(volume, filter) {
+        const world = this.worldNow();
+        if (!world || !isVolume3d(volume))
+            return [];
+        return this.inEntityOrder(recordsInVolume(world, volume, (record) => this.eligible(record, filter, true)), filter);
+    }
+    point(at, filter) {
+        const world = this.worldNow();
+        if (!world || !isPoint3d(at))
+            return [];
+        return this.inEntityOrder(recordsAtPoint(world, at, (record) => this.eligible(record, filter, true)), filter);
+    }
+    nearest(at, filter) {
+        const maxDistance = rangeOf(filter);
+        if (!isPoint3d(at) || !(maxDistance >= 0))
+            return null;
+        let best = null;
+        for (const entity of this.game.entities) {
+            const distance = this.distanceIfEligible(entity, { at, filter, maxDistance });
+            if (distance !== null && (best === null || distance < best.distance))
+                best = { entity, distance };
+        }
+        return best?.entity ?? null;
+    }
+    /** How far the entity is from the search, when it is alive, passes the filter and lies within range. */
+    distanceIfEligible(entity, { at, filter, maxDistance }) {
+        if (!entity.alive || !this.rules.matchesCommon(entity, filter))
+            return null;
+        const { x, y, z } = entity.position;
+        const distance = Math.hypot(x - at.x, y - at.y, z - at.z);
+        if (Number.isNaN(distance) || distance > maxDistance)
+            return null;
+        return filter?.where && !filter.where(entity, { distance }) ? null : distance;
+    }
+    /** The live world with its query structure current, or null while there is none. */
+    worldNow() {
+        const world = this.game.physics.world;
+        world?.refreshQueries();
+        return world;
+    }
+    /**
+     * A live entity's collider the query domain reads (solids for a ray, sensors
+     * for area and point) that passes the structural filter. Runs inside
+     * Rapier's callback, so it reads the record and nothing else.
+     */
+    eligible(record, filter, sensors) {
+        return record.sensor === sensors && record.entity.alive && this.rules.matchesCommon(record.entity, filter);
+    }
+    /** The user's `where`, run after Rapier has answered: it may throw, spawn or destroy without the world mid-query. */
+    wanted(record, filter) {
+        return record.entity.alive && (!filter?.where || filter.where(record.entity));
+    }
+    /** The entities of the records that pass `where`, once each, in the order they were spawned. */
+    inEntityOrder(records, filter) {
+        const found = new Set(records.filter((record) => this.wanted(record, filter)).map((record) => record.entity));
+        return this.game.entities.filter((entity) => found.has(entity));
+    }
+}