@waica/engine 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -3,12 +3,17 @@ export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, Upd
 export { AssetLoader } from './assets/asset-loader.js';
 export type { AssetStatus } from './assets/asset-loader.js';
 export type { TextureBackend } from './assets/texture-backend.js';
+export { GltfModelBackend } from './assets/model-backend.js';
+export type { LoadedModel, ModelBackend } from './assets/model-backend.js';
+export type { ModelHandle, ModelOutcome } from './assets/model-cache.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
 export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
 export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
+export { isClipTarget } from './animation/clip-target.js';
+export type { ClipTarget } from './animation/clip-target.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
 export type { YSortBatchParticipant, YSortEntry, YSortParticipant } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
@@ -21,11 +26,20 @@ export { CameraEffects } from './camera-effects.js';
 export type { CameraEffectColor, CameraEffectHandle, CameraEffectsOptions, CameraEffectsState, FadeOptions, FlashOptions, ShakeOptions, } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game-time.js';
-export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
+export type { SceneCameraJson, OrthographicSceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
+export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
+export type { PerspectiveSceneCameraJson, ResolvedPerspectiveCamera, SceneFieldIssue, Vec3Json, } from './scene-camera-3d.js';
+export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
+export type { GameCamera, NormalizedPoint, ViewCamera, WorldPoint } from './camera-projection.js';
+export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
+export type { SceneSpace, SpaceMarked } from './scene-space.js';
+export type { RuntimeSnapshotView } from './runtime-view-snapshot.js';
+export { applyTransformJson } from './entity-transform.js';
+export type { PositionJson, TransformJson } from './entity-transform.js';
 export { Entity } from './entity.js';
-export { Component } from './component.js';
+export { COMPONENT_SPACES, Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';
-export type { ComponentClass, ContactNormal, ParamSpec, SolidContact, } from './component.js';
+export type { BodyContact, ComponentClass, ComponentSpace, ContactNormal, ParamSpec, SolidContact, } from './component.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export type { ComponentModule } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
@@ -40,7 +54,7 @@ export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_B
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeBridgeFailure, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export type { RenderBackend } from './render-readiness.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { RuntimeSnapshotLight, RuntimeSnapshotLighting, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.js';
+export type { RuntimeSnapshotLight, RuntimeSnapshotLighting, RuntimeSnapshotPointLight, RuntimeSnapshotSun, RuntimeSnapshotPost, } from './runtime-lighting-snapshot.js';
 export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotCamera, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
@@ -49,6 +63,21 @@ export { GameUi } from './ui.js';
 export type { AnchoredPieceHandle, AttachOptions } from './anchored-pieces.js';
 export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
+export { Model } from './components/model.js';
+export type { ModelShape } from './components/model.js';
+export { Animator } from './components/animator.js';
+export type { AnimatorClipOverride, AnimatorState } from './components/animator.js';
+export { poseHash } from './animation/pose-hash.js';
+export { Sun } from './components/sun.js';
+export { Collider, COLLIDER_SHAPES } from './components/collider.js';
+export type { ColliderShape } from './components/collider.js';
+export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';
+export type { BodyVector, RigidBodyType } from './components/rigid-body.js';
+export { DEFAULT_GRAVITY, resolveSceneSimulation, sceneSimulationIssues } from './scene-simulation.js';
+export type { ResolvedSceneSimulation, SceneSimulationJson } from './scene-simulation.js';
+export type { PhysicsBackend, RapierModule } from './physics-3d/rapier-module.js';
+export type { RuntimeSnapshotBody, RuntimeSnapshotPhysics } from './runtime-physics-snapshot.js';
+export { PointLight } from './components/point-light.js';
 export { GameLighting } from './scene-lighting.js';
 export type { AmbientLightInput } from './scene-lighting.js';
 export { GamePost } from './post-effects.js';
@@ -74,6 +103,7 @@ export type { TilemapCell, TilemapCellBounds, TilemapGridSpec, } from './tilemap
 export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
 export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
 export type { EntityWith, NearestQueryContext, NearestSpatialQueryFilter, RayHit, SpatialQuery, SpatialQueryFilter, } from './spatial-query.js';
+export type { Point3d, QueryVolume3d, RayHit3d } from './spatial-query-3d.js';
 export { Emitter } from './events.js';
 export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
 export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, SceneRenderJson, SceneLightingJson, ScenePostJson, PrefabJson, } from './scene.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 export { Game } from './game.js';
 export { AssetLoader } from './assets/asset-loader.js';
+export { GltfModelBackend } from './assets/model-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
+export { isClipTarget } from './animation/clip-target.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 export { spritePlacement } from './sprite-placement.js';
@@ -9,8 +11,12 @@ export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepScen
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
 export { CameraEffects } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
+export { isPerspectiveCameraJson, PERSPECTIVE_DEFAULTS, perspectiveCameraIssues, placePerspectiveCamera, resolvePerspectiveCamera, } from './scene-camera-3d.js';
+export { isPerspectiveCamera, worldToNormalized } from './camera-projection.js';
+export { componentSpaceMismatch, componentSpaceOf, entityTransformIssues, resolveSceneSpace, SCENE_SPACES, sceneSpaceIssues, } from './scene-space.js';
+export { applyTransformJson } from './entity-transform.js';
 export { Entity } from './entity.js';
-export { Component } from './component.js';
+export { COMPONENT_SPACES, Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
@@ -23,6 +29,14 @@ export { Stats } from './stats.js';
 export { GameUi } from './ui.js';
 export { Sprite } from './components/sprite.js';
 export { Light } from './components/light.js';
+export { Model } from './components/model.js';
+export { Animator } from './components/animator.js';
+export { poseHash } from './animation/pose-hash.js';
+export { Sun } from './components/sun.js';
+export { Collider, COLLIDER_SHAPES } from './components/collider.js';
+export { RigidBody, RIGID_BODY_TYPES } from './components/rigid-body.js';
+export { DEFAULT_GRAVITY, resolveSceneSimulation, sceneSimulationIssues } from './scene-simulation.js';
+export { PointLight } from './components/point-light.js';
 export { GameLighting } from './scene-lighting.js';
 export { GamePost } from './post-effects.js';
 export { EMISSIVE_LAYER, setEmissive } from './render-layers.js';

package/dist/lit-frame.js

@@ -56,8 +56,10 @@ export class FrameComposer {
     }
     draw() {
         // Full Ambient Light: the light-map would be 1 everywhere, so nothing to multiply.
-        const lit = this.surface.game.lighting.active && !ambientIsFull(this.surface.game.lighting);
-        const post = this.surface.game.post.active;
+        // A 3D scene never builds one: its lights are three's own (ADR 0027).
+        const { game } = this.surface;
+        const lit = game.space === '2d' && game.lighting.active && !ambientIsFull(game.lighting);
+        const post = game.post.active;
         if (!lit && !post) {
             this.clearLetterbox();
             this.drawScene();
@@ -98,7 +100,12 @@ export class FrameComposer {
     /** The scene through its Sprite Batches (ADR 0024), for the camera's current layers. */
     drawScene() {
         const { spriteBatches, renderer } = this.surface;
-        const { scene, camera } = this.surface.game;
+        const { scene, camera, space } = this.surface.game;
+        // A 3D scene has no sprites to batch: it draws straight, the depth buffer ordering it.
+        if (space === '3d') {
+            renderer.render(scene, camera);
+            return;
+        }
         spriteBatches.drawFrame(scene, camera, () => renderer.render(scene, camera));
     }
     /** The scene for one layer mask, restoring the camera's own mask after. */

package/dist/physics-3d/body-contacts.d.ts

@@ -0,0 +1,10 @@
+import type { Game } from '../game.js';
+import type { PhysicsWorld } from './physics-world.js';
+/**
+ * After the physics step (CA-15): every component on an entity with a solid
+ * Collider that implements `onBodyContact` hears about each other entity it
+ * touches, once per step, with the normal pointing from it to the other. The
+ * common scene, where no component listens, allocates nothing here: the
+ * narrow phase is read only for an entity that has a receiver.
+ */
+export declare function dispatchBodyContacts(game: Game, world: PhysicsWorld): void;

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

@@ -0,0 +1,59 @@
+/** Adds zero so a negated zero reads as 0, not -0. */
+const clean = (value) => value + 0;
+/** The contact one Rapier manifold makes for `record` against `other`, or null when it holds no solver contact point. */
+function manifoldContact(sides, manifold, flipped) {
+    const [record, other] = sides;
+    const point = manifold.numSolverContacts() > 0 ? manifold.solverContactPoint(0) : null;
+    if (!point)
+        return null;
+    // The manifold's normal points from its first shape to its second; `flipped` says that first shape is the other one, so it is negated to point from ours.
+    const n = manifold.normal();
+    const sign = flipped ? -1 : 1;
+    return {
+        entity: record.entity,
+        other: other.entity,
+        normal: { x: clean(sign * n.x), y: clean(sign * n.y), z: clean(sign * n.z) },
+        point: { x: point.x, y: point.y, z: point.z },
+    };
+}
+/** The solid contacts of one body this step, one per other entity, read from Rapier's narrow phase. */
+function contactsOf(world, record) {
+    const contacts = new Map();
+    world.raw.contactPairsWith(record.shape, (shape) => {
+        const other = world.recordOfCollider(shape.handle);
+        if (!other || other === record || contacts.has(other))
+            return;
+        world.raw.contactPair(record.shape, shape, (manifold, flipped) => {
+            const contact = contacts.has(other) ? null : manifoldContact([record, other], manifold, flipped);
+            if (contact)
+                contacts.set(other, contact);
+        });
+    });
+    return [...contacts.values()];
+}
+const listens = (component) => typeof component.onBodyContact === 'function';
+function deliver(contacts, receivers) {
+    for (const contact of contacts) {
+        if (!contact.entity.alive || !contact.other.alive)
+            continue;
+        for (const component of receivers)
+            component.onBodyContact?.(contact);
+    }
+}
+/**
+ * After the physics step (CA-15): every component on an entity with a solid
+ * Collider that implements `onBodyContact` hears about each other entity it
+ * touches, once per step, with the normal pointing from it to the other. The
+ * common scene, where no component listens, allocates nothing here: the
+ * narrow phase is read only for an entity that has a receiver.
+ */
+export function dispatchBodyContacts(game, world) {
+    for (const entity of game.entities) {
+        if (game.physics.world !== world)
+            return;
+        const record = world.recordOf(entity);
+        if (!record || record.sensor || !entity.alive || !entity.components.some(listens))
+            continue;
+        deliver(contactsOf(world, record), entity.components.filter(listens));
+    }
+}

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

@@ -0,0 +1,52 @@
+import type { Collider } from '../components/collider.js';
+import { RigidBody } from '../components/rigid-body.js';
+import type { Entity } from '../entity.js';
+import type { RapierBody, RapierCollider, RapierModule, RapierWorld } from './rapier-module.js';
+/** Rapier's three body types, as the Runtime Snapshot names them. */
+export type BodyKind = 'fixed' | 'dynamic' | 'kinematic';
+/** What a body is built from: the entity and the Collider and RigidBody components it has. */
+export interface BodyParts {
+    readonly entity: Entity;
+    readonly collider: Collider;
+    readonly rigid: RigidBody | null;
+}
+/** One entity's body in the world: its components and the Rapier handles built from them. */
+export interface BodyRecord {
+    readonly entity: Entity;
+    readonly collider: Collider;
+    readonly rigid: RigidBody | null;
+    readonly kind: BodyKind;
+    /** Whether the Rapier collider was built as a sensor; frozen here because `Collider.sensor` is a plain field a script may flip later. */
+    readonly sensor: boolean;
+    readonly body: RapierBody;
+    readonly shape: RapierCollider;
+    /** Whether a kinematic body stands on something after the last step; written by the character controller. */
+    grounded: boolean;
+    /** A kinematic body's vertical velocity (units per second), integrated by the character controller. */
+    vy: number;
+    /** A kinematic body's movement over the last step, per second. */
+    velocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Why this collider cannot become a Rapier shape, or null when it can. */
+export declare function colliderProblem(collider: Collider): string | null;
+/** Why this RigidBody cannot become a Rapier body, or null when it can (the mirror of `colliderProblem`). */
+export declare function rigidBodyProblem(rigid: RigidBody): string | null;
+/**
+ * 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 declare function createBody(R: RapierModule, world: RapierWorld, parts: BodyParts): BodyRecord;
+/** A body's linear velocity: Rapier's for a dynamic one, the measured movement of a kinematic one, none for a fixed one. */
+export declare function bodyVelocity(record: BodyRecord): {
+    x: number;
+    y: number;
+    z: number;
+};
+/** After a step: a moving body's pose becomes its entity's (a sleeping dynamic body has not moved). */
+export declare function syncBodyPose(record: BodyRecord): void;

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