@waica/engine 0.25.0 → 0.27.0

package/dist/physics-3d/physics-host.d.ts

@@ -0,0 +1,86 @@
+import type { Entity } from '../entity.js';
+import type { Game } from '../game.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+import { type ResolvedSceneSimulation } from '../scene-simulation.js';
+import type { SceneSpace } from '../scene-space.js';
+import { type BodyRecord } from './body-sync.js';
+import { type PhysicsBackend } from './rapier-module.js';
+import { PhysicsWorld } from './physics-world.js';
+/** `loading` until the Rapier module arrives, `ready` once the live 3D scene has its world, `failed` for good if the load failed. */
+export type PhysicsState = 'loading' | 'ready' | 'failed';
+/**
+ * The Game's physics (ADR 0028): loads Rapier the first time a 3D scene loads
+ * and counts that load as a pending asset, so Assets Ready, `game.ready()` and
+ * the Run Session's wait all cover it; keeps one `PhysicsWorld` per live 3D
+ * scene; and answers the components' questions by entity. A 2D scene never
+ * triggers the load.
+ */
+export declare class PhysicsHost {
+    private readonly game;
+    private readonly backend?;
+    private module;
+    private loading;
+    private failure;
+    private gravity;
+    private live;
+    private disposed;
+    constructor(game: Game, backend?: PhysicsBackend | undefined);
+    /** The live 3D scene's world; null for a 2D scene, while the module loads and after it failed. */
+    get world(): PhysicsWorld | null;
+    /** The state a 3D scene reports; for a 2D scene it is meaningless and callers do not ask. */
+    get state(): PhysicsState;
+    /** The gravity the live scene runs with: its world's, or the declared one while the world does not exist yet. */
+    get sceneGravity(): Vec3Json;
+    /**
+     * Adopts a scene's space (called by `setSceneRender`): a 3D scene starts the
+     * load, gets its world at once when the module is here, or hears about the
+     * load that already failed.
+     */
+    enterScene(space: SceneSpace): void;
+    /** Adopts a scene's gravity (called by `setSceneSimulation`). */
+    setSimulation(simulation: ResolvedSceneSimulation): void;
+    /** Frees the world after the scene's entities are destroyed; the module stays. */
+    unloadScene(): void;
+    dispose(): void;
+    /**
+     * `game.ready()`: the renderer's promise, and for a Game whose live scene is
+     * 3D also the Rapier load (which rejects, naming the package, when it fails).
+     */
+    whenReady(rendering: Promise<void>): Promise<void>;
+    /** One Simulation Step of the world, when there is one. */
+    step(): void;
+    attach(entity: Entity): void;
+    detach(entity: Entity): void;
+    recordOf(entity: Entity): BodyRecord | undefined;
+    velocityOf(entity: Entity): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /** Sets a dynamic body's velocity; for a kinematic one, x and z become its desired velocity and y its vertical velocity. */
+    setVelocityOf(entity: Entity, velocity: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    groundedOf(entity: Entity): boolean;
+    /** Launches a kinematic body upward when it stands on something; whether it did. */
+    jumpOf(entity: Entity, speed: number): boolean;
+    applyImpulseTo(entity: Entity, impulse: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    private begin;
+    private arrive;
+    private fail;
+    /** Tells the Runtime Bridge the scene it is driving cannot simulate (the mirror of `render-backend-failed`). */
+    private report;
+    /**
+     * The world of the live 3D scene, with a body for every Collider already
+     * spawned (a load that finished late). A body that cannot be built costs
+     * that entity its body, never the rest of the scene or the load itself
+     * (spawnFromJson's rule for a throwing component).
+     */
+    private createWorld;
+}

package/dist/physics-3d/physics-host.js

@@ -0,0 +1,174 @@
+import { activeRuntimeBridgeHook } from '../runtime-bridge.js';
+import { DEFAULT_GRAVITY } from '../scene-simulation.js';
+import { bodyVelocity } from './body-sync.js';
+import { loadRapier, RAPIER_PACKAGE } from './rapier-module.js';
+import { PhysicsWorld } from './physics-world.js';
+/**
+ * The Game's physics (ADR 0028): loads Rapier the first time a 3D scene loads
+ * and counts that load as a pending asset, so Assets Ready, `game.ready()` and
+ * the Run Session's wait all cover it; keeps one `PhysicsWorld` per live 3D
+ * scene; and answers the components' questions by entity. A 2D scene never
+ * triggers the load.
+ */
+export class PhysicsHost {
+    game;
+    backend;
+    module = null;
+    loading = null;
+    failure = null;
+    gravity = [...DEFAULT_GRAVITY];
+    live = null;
+    disposed = false;
+    constructor(game, backend) {
+        this.game = game;
+        this.backend = backend;
+    }
+    /** The live 3D scene's world; null for a 2D scene, while the module loads and after it failed. */
+    get world() {
+        return this.live;
+    }
+    /** The state a 3D scene reports; for a 2D scene it is meaningless and callers do not ask. */
+    get state() {
+        if (this.failure)
+            return 'failed';
+        return this.live ? 'ready' : 'loading';
+    }
+    /** The gravity the live scene runs with: its world's, or the declared one while the world does not exist yet. */
+    get sceneGravity() {
+        return this.live ? this.live.gravity : [...this.gravity];
+    }
+    /**
+     * Adopts a scene's space (called by `setSceneRender`): a 3D scene starts the
+     * load, gets its world at once when the module is here, or hears about the
+     * load that already failed.
+     */
+    enterScene(space) {
+        if (space !== '3d' || this.disposed)
+            return;
+        if (this.failure)
+            this.report(this.failure);
+        else if (this.module)
+            this.createWorld(this.module);
+        else
+            this.begin();
+    }
+    /** Adopts a scene's gravity (called by `setSceneSimulation`). */
+    setSimulation(simulation) {
+        this.gravity = simulation.gravity;
+        if (this.live)
+            this.live.gravity = simulation.gravity;
+    }
+    /** Frees the world after the scene's entities are destroyed; the module stays. */
+    unloadScene() {
+        this.live?.free();
+        this.live = null;
+        this.gravity = [...DEFAULT_GRAVITY];
+    }
+    dispose() {
+        this.disposed = true;
+        this.unloadScene();
+    }
+    /**
+     * `game.ready()`: the renderer's promise, and for a Game whose live scene is
+     * 3D also the Rapier load (which rejects, naming the package, when it fails).
+     */
+    whenReady(rendering) {
+        const loading = this.game.space === '3d' ? this.loading : null;
+        return loading ? Promise.all([rendering, loading]).then(() => undefined) : rendering;
+    }
+    /** One Simulation Step of the world, when there is one. */
+    step() {
+        this.live?.step();
+    }
+    attach(entity) {
+        this.live?.attach(entity);
+    }
+    detach(entity) {
+        this.live?.detach(entity);
+    }
+    recordOf(entity) {
+        return this.live?.recordOf(entity);
+    }
+    velocityOf(entity) {
+        const record = this.recordOf(entity);
+        return record ? bodyVelocity(record) : null;
+    }
+    /** Sets a dynamic body's velocity; for a kinematic one, x and z become its desired velocity and y its vertical velocity. */
+    setVelocityOf(entity, velocity) {
+        const record = this.recordOf(entity);
+        if (record?.kind === 'dynamic')
+            record.body.setLinvel(velocity, true);
+        if (record?.kind === 'kinematic' && record.rigid) {
+            record.rigid.desiredVelocity = { x: velocity.x, z: velocity.z };
+            record.vy = velocity.y;
+        }
+    }
+    groundedOf(entity) {
+        return this.recordOf(entity)?.grounded ?? false;
+    }
+    /** Launches a kinematic body upward when it stands on something; whether it did. */
+    jumpOf(entity, speed) {
+        const record = this.recordOf(entity);
+        if (record?.kind !== 'kinematic' || !record.grounded)
+            return false;
+        record.vy = speed;
+        return true;
+    }
+    applyImpulseTo(entity, impulse) {
+        const record = this.recordOf(entity);
+        if (record?.kind === 'dynamic')
+            record.body.applyImpulse(impulse, true);
+    }
+    begin() {
+        if (this.loading)
+            return;
+        const work = (this.backend ?? loadRapier)().then((module) => this.arrive(module), (cause) => this.fail(cause));
+        this.loading = work;
+        // The asset loader counts it: pending now, loaded or failed when it settles, and Assets Ready waits for it.
+        this.game.assets.track(work, RAPIER_PACKAGE);
+        // Observed here: `whenReady` hands every caller its own derived promise.
+        work.catch(() => undefined);
+    }
+    arrive(module) {
+        this.module = module;
+        if (this.disposed || this.game.space !== '3d')
+            return;
+        this.createWorld(module);
+    }
+    fail(cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        const error = new Error(`Physics failed to load: could not import ${RAPIER_PACKAGE} (${reason})`, { cause });
+        this.failure = error;
+        // A Game whose live scene is 2D by now needs no physics: the failure waits for the next 3D scene.
+        if (this.game.space === '3d')
+            this.report(error);
+        throw error;
+    }
+    /** Tells the Runtime Bridge the scene it is driving cannot simulate (the mirror of `render-backend-failed`). */
+    report(error) {
+        if (this.disposed)
+            return;
+        activeRuntimeBridgeHook()?.fail?.({ code: 'physics-backend-failed', message: error.message });
+    }
+    /**
+     * The world of the live 3D scene, with a body for every Collider already
+     * spawned (a load that finished late). A body that cannot be built costs
+     * that entity its body, never the rest of the scene or the load itself
+     * (spawnFromJson's rule for a throwing component).
+     */
+    createWorld(module) {
+        if (this.live || this.disposed)
+            return;
+        const world = new PhysicsWorld(module, this.gravity);
+        this.live = world;
+        for (const entity of this.game.entities) {
+            try {
+                world.attach(entity);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[waica] "${entity.name}": no physics body was created (${message})`);
+            }
+        }
+    }
+}

package/dist/physics-3d/physics-world.d.ts

@@ -0,0 +1,65 @@
+import type { Entity } from '../entity.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+import { type BodyRecord } from './body-sync.js';
+import type { RapierModule, RapierWorld } from './rapier-module.js';
+/**
+ * One Rapier world and the bodies of the live 3D scene (ADR 0028): created
+ * with the scene, stepped once per Simulation Step, freed with the scene. It
+ * owns every Rapier handle; components only hold plain params and ask the
+ * Game's `physics` for velocity, impulses and the like by entity.
+ */
+export declare class PhysicsWorld {
+    /** The Rapier module the world was made with, for the shapes and rays its queries build. */
+    readonly R: RapierModule;
+    /** The Rapier world itself, for the modules that query it; nothing outside `physics-3d/` and its tests should touch it. */
+    readonly raw: RapierWorld;
+    private readonly records;
+    private readonly byCollider;
+    /** Entities with a RigidBody and, so far, no Collider: warned about at the first step if it stays so. */
+    private readonly orphans;
+    /** The last warning each entity got, so the same problem seen from both of its components is said once. */
+    private readonly warned;
+    private sensors;
+    /** Bodies came or went since Rapier last updated the structure its queries read. */
+    private queriesStale;
+    private readonly characters;
+    constructor(
+    /** The Rapier module the world was made with, for the shapes and rays its queries build. */
+    R: RapierModule, gravity: Vec3Json);
+    /** Whether any body has a sensor Collider, so the sensor dispatch can be skipped when none does. */
+    get hasSensors(): boolean;
+    get gravity(): Vec3Json;
+    set gravity(value: Vec3Json);
+    /** The record of an entity's body, if it has one. */
+    recordOf(entity: Entity): BodyRecord | undefined;
+    /** The record that owns a Rapier collider handle. */
+    recordOfCollider(handle: number): BodyRecord | undefined;
+    /** The bodies of the given entities, in their order. */
+    bodiesOf(entities: readonly Entity[]): BodyRecord[];
+    /**
+     * Builds (or rebuilds) the entity's body from the Collider and RigidBody it
+     * has now. Called from each component's `onReady`, so either order of the
+     * two works: the later one replaces the earlier one's body.
+     */
+    attach(entity: Entity): void;
+    /** Removes the entity's body and collider; a no-op for an entity without one. */
+    detach(entity: Entity): void;
+    /**
+     * One Simulation Step of physics: every kinematic body is moved through the
+     * character controller, Rapier steps, then moving bodies write their pose to
+     * their entities.
+     */
+    step(): void;
+    /**
+     * Makes ray casts, shape queries and the character controller see the bodies
+     * created or removed since the last step: Rapier only updates the structure
+     * they read inside `step()`, so a body spawned this frame would be invisible
+     * (a character would fall through a floor spawned with it). A step of zero
+     * seconds updates it and moves nothing.
+     */
+    refreshQueries(): void;
+    /** Frees the Rapier world and forgets every body. The entities are destroyed (and detached) before this. */
+    free(): void;
+    private warnOrphans;
+    private warnOnce;
+}

package/dist/physics-3d/physics-world.js

@@ -0,0 +1,158 @@
+import { Collider } from '../components/collider.js';
+import { RigidBody } from '../components/rigid-body.js';
+import { SIMULATION_STEP } from '../fixed-step.js';
+import { colliderProblem, createBody, rigidBodyProblem, syncBodyPose } from './body-sync.js';
+import { CharacterMotion } from './character-controller.js';
+/**
+ * One Rapier world and the bodies of the live 3D scene (ADR 0028): created
+ * with the scene, stepped once per Simulation Step, freed with the scene. It
+ * owns every Rapier handle; components only hold plain params and ask the
+ * Game's `physics` for velocity, impulses and the like by entity.
+ */
+export class PhysicsWorld {
+    R;
+    /** The Rapier world itself, for the modules that query it; nothing outside `physics-3d/` and its tests should touch it. */
+    raw;
+    records = new Map();
+    byCollider = new Map();
+    /** Entities with a RigidBody and, so far, no Collider: warned about at the first step if it stays so. */
+    orphans = new Set();
+    /** The last warning each entity got, so the same problem seen from both of its components is said once. */
+    warned = new WeakMap();
+    sensors = 0;
+    /** Bodies came or went since Rapier last updated the structure its queries read. */
+    queriesStale = false;
+    characters;
+    constructor(
+    /** The Rapier module the world was made with, for the shapes and rays its queries build. */
+    R, gravity) {
+        this.R = R;
+        this.raw = new R.World({ x: gravity[0], y: gravity[1], z: gravity[2] });
+        this.raw.timestep = SIMULATION_STEP;
+        this.characters = new CharacterMotion(R, this.raw);
+    }
+    /** Whether any body has a sensor Collider, so the sensor dispatch can be skipped when none does. */
+    get hasSensors() {
+        return this.sensors > 0;
+    }
+    get gravity() {
+        const { x, y, z } = this.raw.gravity;
+        return [x, y, z];
+    }
+    set gravity(value) {
+        this.raw.gravity = { x: value[0], y: value[1], z: value[2] };
+    }
+    /** The record of an entity's body, if it has one. */
+    recordOf(entity) {
+        return this.records.get(entity);
+    }
+    /** The record that owns a Rapier collider handle. */
+    recordOfCollider(handle) {
+        return this.byCollider.get(handle);
+    }
+    /** The bodies of the given entities, in their order. */
+    bodiesOf(entities) {
+        return entities.flatMap((entity) => {
+            const record = this.records.get(entity);
+            return record ? [record] : [];
+        });
+    }
+    /**
+     * Builds (or rebuilds) the entity's body from the Collider and RigidBody it
+     * has now. Called from each component's `onReady`, so either order of the
+     * two works: the later one replaces the earlier one's body.
+     */
+    attach(entity) {
+        const collider = entity.get(Collider);
+        const rigid = entity.get(RigidBody) ?? null;
+        if (!collider) {
+            if (rigid)
+                this.orphans.add(entity);
+            return;
+        }
+        this.detach(entity);
+        const problem = colliderProblem(collider);
+        const bodyProblem = problem === null && rigid ? rigidBodyProblem(rigid) : null;
+        if (problem !== null)
+            return this.warnOnce(entity, `Collider on "${entity.name}" creates no body: ${problem}.`);
+        if (bodyProblem !== null)
+            return this.warnOnce(entity, `RigidBody on "${entity.name}" creates no body: ${bodyProblem}.`);
+        const record = createBody(this.R, this.raw, { entity, collider, rigid });
+        this.records.set(entity, record);
+        this.queriesStale = true;
+        this.byCollider.set(record.shape.handle, record);
+        if (record.sensor)
+            this.sensors += 1;
+    }
+    /** Removes the entity's body and collider; a no-op for an entity without one. */
+    detach(entity) {
+        this.orphans.delete(entity);
+        const record = this.records.get(entity);
+        if (!record)
+            return;
+        this.records.delete(entity);
+        this.byCollider.delete(record.shape.handle);
+        if (record.sensor)
+            this.sensors -= 1;
+        this.raw.removeRigidBody(record.body);
+        this.queriesStale = true;
+    }
+    /**
+     * One Simulation Step of physics: every kinematic body is moved through the
+     * character controller, Rapier steps, then moving bodies write their pose to
+     * their entities.
+     */
+    step() {
+        this.warnOrphans();
+        this.characters.follow(this.records.values());
+        for (const record of this.records.values()) {
+            if (record.kind !== 'kinematic')
+                continue;
+            this.refreshQueries();
+            this.characters.move(record);
+        }
+        this.raw.step();
+        this.queriesStale = false;
+        for (const record of this.records.values())
+            syncBodyPose(record);
+    }
+    /**
+     * Makes ray casts, shape queries and the character controller see the bodies
+     * created or removed since the last step: Rapier only updates the structure
+     * they read inside `step()`, so a body spawned this frame would be invisible
+     * (a character would fall through a floor spawned with it). A step of zero
+     * seconds updates it and moves nothing.
+     */
+    refreshQueries() {
+        if (!this.queriesStale)
+            return;
+        this.queriesStale = false;
+        const timestep = this.raw.timestep;
+        this.raw.timestep = 0;
+        this.raw.step();
+        this.raw.timestep = timestep;
+    }
+    /** Frees the Rapier world and forgets every body. The entities are destroyed (and detached) before this. */
+    free() {
+        this.records.clear();
+        this.byCollider.clear();
+        this.orphans.clear();
+        this.sensors = 0;
+        this.characters.free();
+        this.raw.free();
+    }
+    warnOrphans() {
+        for (const entity of this.orphans) {
+            this.orphans.delete(entity);
+            if (!entity.alive || entity.has(Collider))
+                continue;
+            this.warnOnce(entity, `RigidBody on "${entity.name}" needs a Collider on the same entity; no body was created.`);
+        }
+    }
+    warnOnce(entity, message) {
+        if (this.warned.get(entity) === message)
+            return;
+        this.warned.set(entity, message);
+        console.warn(`[waica] ${message}`);
+    }
+}

package/dist/physics-3d/rapier-module.d.ts

@@ -0,0 +1,17 @@
+import type * as Rapier from '@dimforge/rapier3d-deterministic-compat';
+/** The initialized Rapier module: the `RAPIER` namespace the package documents. */
+export type RapierModule = typeof Rapier;
+export type { Collider as RapierCollider, ColliderDesc as RapierColliderDesc, KinematicCharacterController as RapierCharacterController, RigidBody as RapierBody, TempContactManifold as RapierManifold, World as RapierWorld, } from '@dimforge/rapier3d-deterministic-compat';
+/** The package name, for the messages that name it. */
+export declare const RAPIER_PACKAGE = "@dimforge/rapier3d-deterministic-compat";
+/**
+ * Where a Game gets Rapier (ADR 0013's seam, applied to physics): resolves to
+ * the initialized module. Defaults to `loadRapier`; a project's own tests pass
+ * the real module they initialized once, or a rejecting stub for the failure path.
+ */
+export type PhysicsBackend = () => Promise<RapierModule>;
+/**
+ * Imports and initializes Rapier, once per page: every Game that asks shares
+ * the same module. A failed load is forgotten, so a later Game may retry.
+ */
+export declare function loadRapier(): Promise<RapierModule>;

package/dist/physics-3d/rapier-module.js

@@ -0,0 +1,19 @@
+/** The package name, for the messages that name it. */
+export const RAPIER_PACKAGE = '@dimforge/rapier3d-deterministic-compat';
+let shared = null;
+/**
+ * Imports and initializes Rapier, once per page: every Game that asks shares
+ * the same module. A failed load is forgotten, so a later Game may retry.
+ */
+export function loadRapier() {
+    shared ??= import('@dimforge/rapier3d-deterministic-compat')
+        .then(async (module) => {
+        await module.init();
+        return module;
+    })
+        .catch((error) => {
+        shared = null;
+        throw error;
+    });
+    return shared;
+}

package/dist/physics-3d/sensor-dispatch.d.ts

@@ -0,0 +1,10 @@
+import type { Game } from '../game.js';
+import type { PhysicsWorld } from './physics-world.js';
+/**
+ * The 3D counterpart of the Hitbox trigger dispatch (CA-16): after the physics
+ * step, every overlap involving a sensor Collider fires `onCollide(other)` on
+ * the components of each side whose interest names the other's layer, every
+ * step while they overlap. Pairs are frozen first and each is re-checked live,
+ * like the 2D dispatch.
+ */
+export declare function dispatchSensorCollisions(game: Game, world: PhysicsWorld): void;

package/dist/physics-3d/sensor-dispatch.js

@@ -0,0 +1,77 @@
+import { collisionMaskTargets } from '../collision-category.js';
+import { Collider } from '../components/collider.js';
+/** The mask a Collider has when nothing was declared: every layer. */
+function isDefaultMask(mask) {
+    return mask.length === 1 && mask[0] === '*';
+}
+/**
+ * Whether `self` is notified about `target` (ADR 0016's directional
+ * interest). A sensor always has an interest, its `collidesWith` (default
+ * every layer), except that the default mask leaves out the level's fixed
+ * solids: a 2D Hitbox never sees a Solid, so a pickup resting on the floor is
+ * not told about the floor every step; naming their layer still works. A
+ * solid collider has no interest until it declares a mask of its own
+ * (inference 14, issue #159): the default `['*']` on a solid means "no
+ * interest", so a wall or a character is not woken by every trigger it touches.
+ */
+function interestedIn(self, target) {
+    const { collider } = self;
+    const defaultMask = isDefaultMask(collider.collidesWith);
+    if (!self.sensor && defaultMask)
+        return false;
+    if (defaultMask && !target.sensor && target.kind === 'fixed')
+        return false;
+    return collisionMaskTargets(collider.collidesWith, target.collider.layer);
+}
+/** Every sensor overlap of the world as a frozen snapshot: each pair once, the earlier-spawned sensor first. */
+function sensorPairs(game, world) {
+    const records = world.bodiesOf(game.entities);
+    const spawnIndex = new Map(records.map((record, index) => [record, index]));
+    const spawnedBefore = (a, b) => (spawnIndex.get(a) ?? 0) < (spawnIndex.get(b) ?? 0);
+    const pairs = [];
+    for (const sensor of records.filter((record) => record.sensor)) {
+        world.raw.intersectionPairsWith(sensor.shape, (shape) => {
+            const other = world.recordOfCollider(shape.handle);
+            if (!other || other === sensor)
+                return;
+            // Two sensors see each other: the earlier one reports the pair.
+            if (other.sensor && spawnedBefore(other, sensor))
+                return;
+            pairs.push([sensor, other]);
+        });
+    }
+    return pairs;
+}
+/** Both entities of a snapshotted pair are alive and still carry the Collider it was taken from. */
+function stillOverlapping([first, second]) {
+    return (first.entity.alive &&
+        second.entity.alive &&
+        first.entity.get(Collider) === first.collider &&
+        second.entity.get(Collider) === second.collider);
+}
+/** `onCollide(other)` on every component of `self`'s entity, when its interest names `other`'s layer. */
+function notify(self, other) {
+    if (!interestedIn(self, other))
+        return;
+    for (const component of [...self.entity.components])
+        component.onCollide?.(other.entity);
+}
+/**
+ * The 3D counterpart of the Hitbox trigger dispatch (CA-16): after the physics
+ * step, every overlap involving a sensor Collider fires `onCollide(other)` on
+ * the components of each side whose interest names the other's layer, every
+ * step while they overlap. Pairs are frozen first and each is re-checked live,
+ * like the 2D dispatch.
+ */
+export function dispatchSensorCollisions(game, world) {
+    if (!world.hasSensors)
+        return;
+    for (const pair of sensorPairs(game, world)) {
+        if (!stillOverlapping(pair))
+            continue;
+        const [first, second] = pair;
+        notify(first, second);
+        if (stillOverlapping(pair))
+            notify(second, first);
+    }
+}

package/dist/physics-3d/world-queries.d.ts

@@ -0,0 +1,39 @@
+import type { BodyRecord } from './body-sync.js';
+import type { PhysicsWorld } from './physics-world.js';
+/** A point or a direction in world space, as `game.query` takes and returns it. */
+export interface Point3d {
+    x: number;
+    y: number;
+    z: number;
+}
+/** A volume `game.query.area` tests sensor colliders against. */
+export type QueryVolume3d = {
+    shape: 'box';
+    center: Point3d;
+    size: Point3d;
+} | {
+    shape: 'sphere';
+    center: Point3d;
+    radius: number;
+};
+/** One collider a ray reaches: whose it is, how far, where and which way its surface faces. */
+export interface WorldRayHit {
+    record: BodyRecord;
+    distance: number;
+    point: Point3d;
+    normal: Point3d;
+}
+/**
+ * Every collider along a ray whose record `accepts`, nearest first.
+ * `direction` is a unit vector, so the distance is in world units; an origin
+ * inside a collider hits it at distance 0.
+ */
+export declare function worldRayHits(world: PhysicsWorld, ray: {
+    origin: Point3d;
+    direction: Point3d;
+    maxDistance: number;
+}, accepts: (record: BodyRecord) => boolean): WorldRayHit[];
+/** Every record whose collider `accepts` and that intersects the volume. */
+export declare function recordsInVolume(world: PhysicsWorld, volume: QueryVolume3d, accepts: (record: BodyRecord) => boolean): BodyRecord[];
+/** Every record whose collider `accepts` and that contains the point. */
+export declare function recordsAtPoint(world: PhysicsWorld, at: Point3d, accepts: (record: BodyRecord) => boolean): BodyRecord[];