@waica/engine 0.24.0 → 0.26.0

package/dist/physics-3d/body-sync.js

@@ -0,0 +1,153 @@
+import { RIGID_BODY_TYPES, RigidBody } from '../components/rigid-body.js';
+/** The dimensions a collider needs are positive finite numbers (Rapier does not defend itself against anything else). */
+function positive(...values) {
+    return values.every((value) => Number.isFinite(value) && value > 0);
+}
+function shapeProblem(collider) {
+    switch (collider.shape) {
+        case 'box':
+            return Array.isArray(collider.size) && collider.size.length === 3 && positive(...collider.size)
+                ? null
+                : 'a box needs a size of three positive numbers';
+        case 'sphere':
+            return positive(collider.radius) ? null : 'a sphere needs a positive radius';
+        case 'capsule':
+            return positive(collider.radius, collider.height) ? null : 'a capsule needs a positive radius and height';
+        default:
+            return `unknown shape "${String(collider.shape)}"`;
+    }
+}
+const isVec3 = (value) => Array.isArray(value) && value.length === 3 && value.every(Number.isFinite);
+const isUnitInterval = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+/** Why this collider cannot become a Rapier shape, or null when it can. */
+export function colliderProblem(collider) {
+    if (!isVec3(collider.offset))
+        return 'the offset needs three finite numbers';
+    if (!isUnitInterval(collider.friction) || !isUnitInterval(collider.restitution))
+        return 'friction and restitution need numbers from 0 to 1';
+    const problem = shapeProblem(collider);
+    if (problem !== null)
+        return problem;
+    // A shorter capsule would silently become a sphere of diameter 2 * radius, taller than the height declared.
+    if (collider.shape === 'capsule' && collider.height < 2 * collider.radius)
+        return 'a capsule needs a height of at least twice its radius';
+    return null;
+}
+const MIN_MASS = RigidBody.params.mass.min;
+/** Why this RigidBody cannot become a Rapier body, or null when it can (the mirror of `colliderProblem`). */
+export function rigidBodyProblem(rigid) {
+    if (!RIGID_BODY_TYPES.includes(rigid.type))
+        return `type must be ${RIGID_BODY_TYPES.join(' or ')}; got ${JSON.stringify(rigid.type)}`;
+    if (!Number.isFinite(rigid.mass) || rigid.mass < MIN_MASS)
+        return `mass must be at least ${MIN_MASS}`;
+    if (!Number.isFinite(rigid.gravityScale))
+        return 'gravityScale must be a finite number';
+    for (const [name, value] of [['linearDamping', rigid.linearDamping], ['angularDamping', rigid.angularDamping]]) {
+        if (!Number.isFinite(value) || value < 0)
+            return `${name} must be at least 0`;
+    }
+    if (!isVec3(rigid.velocity))
+        return 'velocity must be three finite numbers';
+    return null;
+}
+/**
+ * The Rapier shape of a collider at the entity's current scale (inference 9,
+ * issue #159): a box's size and a capsule's height scale per axis, a sphere's
+ * radius by the largest axis, a capsule's radius by the larger of x and z.
+ * A capsule's `height` is end to end, so its straight part is the rest.
+ */
+function shapeDesc(R, collider, scale) {
+    const [sx, sy, sz] = [Math.abs(scale.x), Math.abs(scale.y), Math.abs(scale.z)];
+    switch (collider.shape) {
+        case 'sphere':
+            return R.ColliderDesc.ball(collider.radius * Math.max(sx, sy, sz));
+        case 'capsule': {
+            const radius = collider.radius * Math.max(sx, sz);
+            return R.ColliderDesc.capsule(Math.max(0, (collider.height * sy) / 2 - radius), radius);
+        }
+        case 'box': {
+            const [x, y, z] = collider.size;
+            return R.ColliderDesc.cuboid((x * sx) / 2, (y * sy) / 2, (z * sz) / 2);
+        }
+    }
+}
+function bodyKind(rigid) {
+    if (!rigid)
+        return 'fixed';
+    return rigid.type === 'kinematic' ? 'kinematic' : 'dynamic';
+}
+function bodyDesc(R, entity, rigid) {
+    const kind = bodyKind(rigid);
+    const desc = kind === 'dynamic' ? R.RigidBodyDesc.dynamic() : kind === 'kinematic' ? R.RigidBodyDesc.kinematicPositionBased() : R.RigidBodyDesc.fixed();
+    const { x, y, z } = entity.position;
+    const q = entity.node.quaternion;
+    desc.setTranslation(x, y, z).setRotation({ x: q.x, y: q.y, z: q.z, w: q.w });
+    if (kind === 'dynamic' && rigid) {
+        const [vx, vy, vz] = rigid.velocity;
+        desc
+            .setGravityScale(rigid.gravityScale)
+            .setLinearDamping(rigid.linearDamping)
+            .setAngularDamping(rigid.angularDamping)
+            .setLinvel(vx, vy, vz);
+        if (rigid.lockRotations)
+            desc.lockRotations();
+    }
+    if (kind === 'kinematic')
+        desc.lockRotations();
+    return desc;
+}
+/**
+ * Which pairs Rapier computes contacts for. Its default leaves out every pair
+ * with a kinematic body and no dynamic one, so a character standing on the
+ * floor or against a wall would never hear `onBodyContact`: solid colliders
+ * add the kinematic-fixed and kinematic-kinematic pairs on both sides. A
+ * sensor on a fixed or kinematic body must still see the others (ALL leaves
+ * fixed-fixed out).
+ */
+function activeCollisionTypes(R, sensor) {
+    const { ActiveCollisionTypes: types } = R;
+    return sensor ? types.ALL | types.FIXED_FIXED : types.DEFAULT | types.KINEMATIC_FIXED | types.KINEMATIC_KINEMATIC;
+}
+/**
+ * Builds the entity's body and collider from its components and puts them in
+ * the world. Static bodies are created once and never follow the entity; a
+ * dynamic body is Rapier's from here on. The caller has checked the parts
+ * with `colliderProblem` and `rigidBodyProblem`.
+ */
+export function createBody(R, world, parts) {
+    const { entity, collider, rigid } = parts;
+    const scale = entity.scale;
+    const body = world.createRigidBody(bodyDesc(R, entity, rigid));
+    const [ox, oy, oz] = collider.offset;
+    const desc = shapeDesc(R, collider, scale)
+        .setTranslation(ox * scale.x, oy * scale.y, oz * scale.z)
+        .setSensor(collider.sensor)
+        .setFriction(collider.friction)
+        .setRestitution(collider.restitution)
+        .setActiveCollisionTypes(activeCollisionTypes(R, collider.sensor));
+    if (rigid)
+        desc.setMass(rigid.mass);
+    const shape = world.createCollider(desc, body);
+    return { entity, collider, rigid, kind: bodyKind(rigid), sensor: collider.sensor, body, shape, grounded: false, vy: 0, velocity: { x: 0, y: 0, z: 0 } };
+}
+/** A body's linear velocity: Rapier's for a dynamic one, the measured movement of a kinematic one, none for a fixed one. */
+export function bodyVelocity(record) {
+    if (record.kind === 'kinematic')
+        return { ...record.velocity };
+    if (record.kind === 'dynamic') {
+        const { x, y, z } = record.body.linvel();
+        return { x, y, z };
+    }
+    return { x: 0, y: 0, z: 0 };
+}
+/** After a step: a moving body's pose becomes its entity's (a sleeping dynamic body has not moved). */
+export function syncBodyPose(record) {
+    if (record.kind === 'fixed' || (record.kind === 'dynamic' && record.body.isSleeping()))
+        return;
+    const t = record.body.translation();
+    record.entity.position.set(t.x, t.y, t.z);
+    if (record.kind === 'kinematic')
+        return;
+    const q = record.body.rotation();
+    record.entity.node.quaternion.set(q.x, q.y, q.z, q.w);
+}

package/dist/physics-3d/character-controller.d.ts

@@ -0,0 +1,44 @@
+import type { BodyRecord } from './body-sync.js';
+import type { RapierModule, RapierWorld } from './rapier-module.js';
+/**
+ * Moves the kinematic bodies of a world through Rapier's character controller
+ * (ADR 0028): one controller per world, tuned for each body from its
+ * RigidBody before it moves. The controller applies no gravity, so the engine
+ * integrates each body's vertical velocity here (inference 19, issue #159).
+ */
+export declare class CharacterMotion {
+    private readonly R;
+    private readonly world;
+    private controller;
+    private profile;
+    constructor(R: RapierModule, world: RapierWorld);
+    /**
+     * Puts every kinematic body where game code moved its entity since the last
+     * step (a teleport), before any of them moves: the controller reads the
+     * colliders' poses, which Rapier updates only inside a step, so they are
+     * propagated here, and a teleported body starts over (no fall speed, not
+     * grounded).
+     */
+    follow(records: Iterable<BodyRecord>): void;
+    /** Moves one kinematic body for this Simulation Step; Rapier applies the new position at `world.step()`. */
+    move(record: BodyRecord): void;
+    /** Releases the controller; the world is freed right after. */
+    free(): void;
+    /**
+     * Whether what holds the body up, where this step leaves it, is ground it
+     * may stand on: Rapier's `computedGrounded` counts any contact short of a
+     * wall, `maxSlope` included or not, so a body would stand on, and jump off,
+     * a slope it cannot climb. A short cast of its own collider straight down
+     * finds the surface under it and its outward normal; ground is one within
+     * `maxSlope` of up. On a steeper slope gravity keeps pulling the body down
+     * it. (The controller records no collision for a resting contact, so the
+     * movement's own collisions cannot tell the slope.)
+     */
+    private standsWithin;
+    /** The entity is where the body put it, unless game code moved it since: then the body goes there (a teleport). */
+    private followEntity;
+    /** After the move: standing ends a fall, and a ceiling ends a rise. */
+    private settleVertical;
+    private tuned;
+    private created;
+}

package/dist/physics-3d/character-controller.js

@@ -0,0 +1,126 @@
+import { SIMULATION_STEP } from '../fixed-step.js';
+/** The gap Rapier's controller keeps between the character and what it touches. */
+const SKIN = 0.01;
+/** The narrowest ledge an autostep may land on. */
+const MIN_STEP_WIDTH = 0.2;
+/** How far below the body the probe for the ground it stands on looks: past the skin, with room for a slope's slant. */
+const GROUND_PROBE = SKIN * 4;
+const DOWN = { x: 0, y: -1, z: 0 };
+const DEGREES = Math.PI / 180;
+const profileOf = (rigid) => `${rigid.stepHeight}/${rigid.maxSlope}/${rigid.snapDistance}`;
+/**
+ * Moves the kinematic bodies of a world through Rapier's character controller
+ * (ADR 0028): one controller per world, tuned for each body from its
+ * RigidBody before it moves. The controller applies no gravity, so the engine
+ * integrates each body's vertical velocity here (inference 19, issue #159).
+ */
+export class CharacterMotion {
+    R;
+    world;
+    controller = null;
+    profile = null;
+    constructor(R, world) {
+        this.R = R;
+        this.world = world;
+    }
+    /**
+     * Puts every kinematic body where game code moved its entity since the last
+     * step (a teleport), before any of them moves: the controller reads the
+     * colliders' poses, which Rapier updates only inside a step, so they are
+     * propagated here, and a teleported body starts over (no fall speed, not
+     * grounded).
+     */
+    follow(records) {
+        let teleported = false;
+        for (const record of records) {
+            if (record.kind !== 'kinematic' || !this.followEntity(record))
+                continue;
+            teleported = true;
+            record.vy = 0;
+            record.grounded = false;
+        }
+        if (teleported)
+            this.world.propagateModifiedBodyPositionsToColliders();
+    }
+    /** Moves one kinematic body for this Simulation Step; Rapier applies the new position at `world.step()`. */
+    move(record) {
+        const { rigid, body, shape } = record;
+        if (!rigid)
+            return;
+        // A body standing on the ground feels no gravity: pulling it into the floor every step makes it sink.
+        if (!(record.grounded && record.vy <= 0))
+            record.vy += this.world.gravity.y * rigid.gravityScale * SIMULATION_STEP;
+        const desired = { x: rigid.desiredVelocity.x * SIMULATION_STEP, y: record.vy * SIMULATION_STEP, z: rigid.desiredVelocity.z * SIMULATION_STEP };
+        const controller = this.tuned(rigid);
+        controller.computeColliderMovement(shape, desired, this.R.QueryFilterFlags.EXCLUDE_SENSORS);
+        const moved = controller.computedMovement();
+        const at = body.translation();
+        body.setNextKinematicTranslation({ x: at.x + moved.x, y: at.y + moved.y, z: at.z + moved.z });
+        record.grounded = controller.computedGrounded() && this.standsWithin(record, moved, rigid.maxSlope);
+        record.velocity = { x: moved.x / SIMULATION_STEP, y: moved.y / SIMULATION_STEP, z: moved.z / SIMULATION_STEP };
+        this.settleVertical(record, desired.y, moved.y);
+    }
+    /** Releases the controller; the world is freed right after. */
+    free() {
+        if (this.controller)
+            this.world.removeCharacterController(this.controller);
+        this.controller = null;
+        this.profile = null;
+    }
+    /**
+     * Whether what holds the body up, where this step leaves it, is ground it
+     * may stand on: Rapier's `computedGrounded` counts any contact short of a
+     * wall, `maxSlope` included or not, so a body would stand on, and jump off,
+     * a slope it cannot climb. A short cast of its own collider straight down
+     * finds the surface under it and its outward normal; ground is one within
+     * `maxSlope` of up. On a steeper slope gravity keeps pulling the body down
+     * it. (The controller records no collision for a resting contact, so the
+     * movement's own collisions cannot tell the slope.)
+     */
+    standsWithin({ shape }, moved, maxSlope) {
+        const at = shape.translation();
+        const next = { x: at.x + moved.x, y: at.y + moved.y, z: at.z + moved.z };
+        const flags = this.R.QueryFilterFlags.EXCLUDE_SENSORS;
+        const hit = this.world.castShape(next, shape.rotation(), DOWN, shape.shape, 0, GROUND_PROBE, true, flags, undefined, shape);
+        return hit !== null && hit.normal1.y >= Math.cos(maxSlope * DEGREES);
+    }
+    /** The entity is where the body put it, unless game code moved it since: then the body goes there (a teleport). */
+    followEntity({ entity, body }) {
+        const at = body.translation();
+        const { x, y, z } = entity.position;
+        if (x === at.x && y === at.y && z === at.z)
+            return false;
+        body.setTranslation({ x, y, z }, true);
+        return true;
+    }
+    /** After the move: standing ends a fall, and a ceiling ends a rise. */
+    settleVertical(record, wanted, got) {
+        if (record.grounded && record.vy <= 0)
+            record.vy = 0;
+        else if (record.vy > 0 && got < wanted / 2)
+            record.vy = 0;
+    }
+    tuned(rigid) {
+        const controller = (this.controller ??= this.created());
+        const profile = profileOf(rigid);
+        if (profile === this.profile)
+            return controller;
+        this.profile = profile;
+        if (rigid.stepHeight > 0)
+            controller.enableAutostep(rigid.stepHeight, MIN_STEP_WIDTH, true);
+        else
+            controller.disableAutostep();
+        controller.setMaxSlopeClimbAngle(rigid.maxSlope * DEGREES);
+        if (rigid.snapDistance > 0)
+            controller.enableSnapToGround(rigid.snapDistance);
+        else
+            controller.disableSnapToGround();
+        return controller;
+    }
+    created() {
+        const controller = this.world.createCharacterController(SKIN);
+        controller.setUp({ x: 0, y: 1, z: 0 });
+        controller.setApplyImpulsesToDynamicBodies(true);
+        return controller;
+    }
+}

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;
+}