@waica/engine 0.25.0 → 0.26.0

package/dist/game.js

@@ -2,8 +2,9 @@ import * as THREE from 'three/webgpu';
 import { gameViewport } from './anchored-pieces.js';
 import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
-import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
+import { listenerPosition, screenPanOf } from './audio/spatial.js';
+import { worldToNormalized } from './camera-projection.js';
+import { CameraRig } from './camera-rig.js';
 import { advanceCameraEffects, CameraEffects, layoutCameraEffects } from './camera-effects.js';
 import { implementsOnUpdate, resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
@@ -11,19 +12,23 @@ import { Emitter } from './events.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
 import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
+import { PhysicsHost } from './physics-3d/physics-host.js';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
 import { FrameComposer } from './lit-frame.js';
-import { EMISSIVE_LAYER } from './render-layers.js';
-import { projectIsometric, unprojectIsometric } from './projection.js';
+import { projectIsometric } from './projection.js';
 import { canvasBackground, drawStraightToCanvas, mapUvPerVertex } from './render-output.js';
 import { RenderReadiness } from './render-readiness.js';
 import { applyYSort } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { sceneDrainsOf } from './scene-drains.js';
+import { resolveSceneSimulation } from './scene-simulation.js';
+import { SceneAmbientLight3d } from './scene-lights-3d.js';
+import { resolveRenderPolicy } from './scene-space.js';
 import { GameLighting } from './scene-lighting.js';
+import { runSimulationPhases } from './simulation-phases.js';
 import { createSpriteBatches } from './sprite-batches.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
@@ -44,7 +49,6 @@ function componentsInOrder(order, byName) {
  */
 export class Game {
     scene = new THREE.Scene();
-    camera;
     input;
     pointer;
     query;
@@ -72,6 +76,8 @@ export class Game {
     lighting = new GameLighting();
     /** The live scene's Post Effects (vignette, color grade); they die with their scene. */
     post = new GamePost();
+    /** The live 3D scene's Rapier world and bodies (ADR 0028); package-internal, read by the physics components and the Runtime Snapshot. */
+    physics;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -103,8 +109,21 @@ export class Game {
     baseViewHeight;
     viewHeight;
     sceneCamera = null;
+    /** The orthographic camera of 2D scenes and the perspective one of 3D scenes (ADR 0027); read by the Runtime Snapshot, not part of the game-facing API. */
+    cameraRig = new CameraRig();
+    sceneSpace = '2d';
+    /** A 3D scene's stereo pan, reading the live camera at every call (built once, not per frame). */
+    screenPan = screenPanOf(() => this.camera);
+    /** What following an entity reads from the Game, built once rather than per Simulation Step. */
+    followHost = {
+        find: (name) => this.find(name),
+        renderPoint: (x, y) => this.renderPoint(x, y),
+        viewHeight: () => this.viewHeight,
+    };
     renderSort = null;
     sceneProjection = null;
+    /** The Ambient Light of a 3D scene, fed by `lighting.ambient` (ADR 0027). */
+    ambientLight3d = new SceneAmbientLight3d(this.scene);
     /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
     lastTime = null;
     /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
@@ -147,11 +166,13 @@ export class Game {
         });
         this.assets = new AssetLoader({
             backend: options.textures,
+            models: options.models,
             // Same late lookup as audio's: preload() resolves through whatever
             // catalog is registered at call time, which outlives every scene.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
         this.spriteBatches = createSpriteBatches(this, this.assets);
+        this.physics = new PhysicsHost(this, options.physics);
         this.cameraEffects = new CameraEffects({
             host: () => canvas.parentElement ?? document.body,
             // One screen pixel in world units: the shake snaps to it (never the base).
@@ -170,14 +191,10 @@ export class Game {
                 activeRuntimeBridgeHook()?.fail?.({ code: 'render-backend-failed', message: error.message });
         });
         this.scene.background = canvasBackground(background);
-        this.camera = new THREE.OrthographicCamera();
-        this.camera.position.z = 10;
-        // Emissive drawables sit on their own layer; an unlit frame draws it in place.
-        this.camera.layers.enable(EMISSIVE_LAYER);
         const { renderer, spriteBatches, resolution } = this;
         this.frame = new FrameComposer({ game: this, renderer, spriteBatches, resolution });
         this.pointer = new Pointer(canvas, {
-            camera: this.camera,
+            camera: () => this.camera,
             resolution: this.resolution,
             projection: () => this.sceneProjection,
             entities: this.entities,
@@ -188,12 +205,14 @@ export class Game {
     }
     /**
      * Resolves once the renderer can draw; rejects, naming both Render
-     * Backends, when neither initializes. Every call returns the same promise.
+     * Backends, when neither initializes. While the live scene is 3D it also
+     * waits for the physics module, and rejects naming its package if that
+     * fails to load (ADR 0028).
      * Frames before it simulate but draw nothing, so a host awaits it before
      * its first frame (ADR 0025).
      */
     ready() {
-        return this.readiness.promise;
+        return this.physics.whenReady(this.readiness.promise);
     }
     /** The Render Backend the renderer settled on; null until ready() resolved. */
     get backend() {
@@ -251,6 +270,8 @@ export class Game {
         // Pointer holds that array by reference, so it must never be reassigned.
         for (const entity of [...this.entities])
             entity.destroy();
+        // After the cascade removed every body: the world goes with its scene.
+        this.physics.unloadScene();
         // Drains transferred by the destruction cascade above are scene-scoped too.
         sceneDrainsOf(this).clear();
         // After the cascade freed every slot: the batches go with their scene.
@@ -259,6 +280,8 @@ export class Game {
         this.renderSort = null;
         this.sceneProjection = null;
         this.sceneCamera = null;
+        this.sceneSpace = '2d';
+        this.cameraRig.reset();
         this.liveSceneName = null;
         this.setViewHeight(this.baseViewHeight);
     }
@@ -348,11 +371,13 @@ export class Game {
      * draw order stays layer-banded with spawn-order ties.
      */
     setSceneRender(json) {
-        this.renderSort = json?.sort === 'y' ? 'y' : null;
+        const { space, sort, projection } = resolveRenderPolicy(json);
+        this.sceneSpace = space;
+        this.renderSort = sort;
         this.spriteBatches.enabled = json?.batch !== false;
         this.lighting.loadScene(json);
         this.post.loadScene(json);
-        const projection = json?.projection === 'isometric' ? 'isometric' : null;
+        this.physics.enterScene(space);
         if (projection === this.sceneProjection)
             return;
         this.sceneProjection = projection;
@@ -362,26 +387,28 @@ export class Game {
                 component.onProjectionChange?.(projection);
         }
     }
+    /** Adopts a scene's simulation block (gravity); called by loadScene beside setSceneRender. */
+    setSceneSimulation(json) {
+        this.physics.setSimulation(resolveSceneSimulation(json));
+    }
     /**
      * Adopts a scene's camera block: jumps to its framing and, while
      * simulating, follows/clamps per its settings. Called by loadScene.
      */
     setSceneCamera(json) {
-        // No camera block: leave the camera to the host (constructor viewHeight).
-        if (!json) {
-            this.sceneCamera = null;
+        // No orthographic block (none, or a 3D scene): leave the camera to the host.
+        const cam = (this.sceneCamera = this.cameraRig.adopt(json, this.sceneSpace));
+        if (!cam)
             return;
-        }
-        this.sceneCamera = resolveSceneCamera(json);
         // With a follow target the declared position is moot: start centered on
         // the target so play begins framed like the editor shows it.
-        const followed = this.sceneCamera.follow ? this.find(this.sceneCamera.follow) : undefined;
+        const followed = cam.follow ? this.find(cam.follow) : undefined;
         const center = followed
             ? this.renderPoint(followed.position.x, followed.position.y)
-            : { x: this.sceneCamera.position[0], y: this.sceneCamera.position[1] };
+            : { x: cam.position[0], y: cam.position[1] };
         this.camera.position.x = center.x;
         this.camera.position.y = center.y;
-        this.setViewHeight(this.sceneCamera.zoom);
+        this.setViewHeight(cam.zoom);
     }
     start() {
         if (this.disposed)
@@ -438,11 +465,35 @@ export class Game {
     get projection() {
         return this.sceneProjection;
     }
-    /** Visible world height (2D camera zoom). */
+    /** The live scene's space (`render.space`); `'2d'` with no scene (ADR 0027). */
+    get space() {
+        return this.sceneSpace;
+    }
+    /** The camera the live scene draws with: orthographic in 2D scenes, perspective in 3D ones. */
+    get camera() {
+        return this.cameraRig.camera;
+    }
+    /**
+     * Where a logical point falls on the canvas, in CSS px from its top-left
+     * corner inside the letterbox; null when a perspective camera cannot see it
+     * (behind its near plane). The one projection Anchored Pieces, spatial
+     * audio and the editor share (CA-6).
+     */
+    worldToScreen(point) {
+        const { clientWidth: w, clientHeight: h } = this.renderer.domElement;
+        const view = gameViewport(w, h, this.resolution);
+        const render = this.renderPoint(point.x, point.y);
+        const at = worldToNormalized(this.camera, { x: render.x, y: render.y, z: point.z });
+        return at && { x: view.x + at.nx * view.width, y: view.y + at.ny * view.height };
+    }
+    /** Visible world height (2D camera zoom); a perspective camera does not use it. */
     get view() {
         return this.viewHeight;
     }
     setViewHeight(value) {
+        // A perspective camera frames by its lens, not by a visible height.
+        if (this.sceneSpace === '3d')
+            return;
         this.viewHeight = Math.min(Math.max(value, 2), 80);
         this.resize();
     }
@@ -462,6 +513,7 @@ export class Game {
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        this.physics.dispose();
         sceneDrainsOf(this).clear();
         this.spriteBatches.unload();
         // After the entities: their clones go with the cascade above, the
@@ -555,7 +607,7 @@ export class Game {
             // Positional audio (CA-8): recomputed every frame, on this same pass —
             // never a second walk of `this.entities`, since `this.audio` already
             // holds direct references to whichever entities are tracked.
-            this.audio.updatePlacements(this.audioListenerPosition(), (x, y) => this.renderPoint(x, y));
+            this.audio.updatePlacements(listenerPosition(this.sceneSpace, this.camera, this.sceneProjection), (x, y) => this.renderPoint(x, y), this.sceneSpace === '3d' ? this.screenPan : undefined);
             this.renderSurface();
         }
         finally {
@@ -581,7 +633,7 @@ export class Game {
             for (const component of schedule)
                 component.onUpdate?.(SIMULATION_STEP);
         }
-        this.dispatchCollisions();
+        runSimulationPhases(this);
         this.updateSceneCamera(SIMULATION_STEP);
         advanceCameraEffects(this.cameraEffects);
         this.finishStep();
@@ -625,11 +677,13 @@ export class Game {
         if (this.renderSort === 'y')
             applyYSort(this.entities, sceneDrainsOf(this).participants());
         this.ui.setActive(this.simulate);
+        this.ambientLight3d.sync(this.sceneSpace, this.lighting.ambient);
         // The shake offset exists only while drawing (ADR 0020): Anchored Pieces
         // and the render see the drawn center, then the base comes back exactly,
         // so follow smoothing never starts from its own jitter.
         const { x, y } = this.camera.position;
-        const { shake } = this.cameraEffects.state;
+        // A perspective camera does not shake: the offset is in orthographic world units.
+        const shake = this.sceneSpace === '3d' ? { x: 0, y: 0 } : this.cameraEffects.state.shake;
         this.camera.position.x = x + shake.x;
         this.camera.position.y = y + shake.y;
         try {
@@ -688,48 +742,13 @@ export class Game {
         return componentsInOrder(result.order, byName);
     }
     updateSceneCamera(dt) {
-        const cam = this.sceneCamera;
-        if (!cam)
+        if (!this.sceneCamera)
             return;
-        const followed = cam.follow ? this.find(cam.follow) : undefined;
-        const provider = followed?.components.find((c) => isCameraVelocityProvider(c));
-        const velocity = provider?.getCameraVelocity();
-        const target = followed
-            ? this.renderPoint(followed.position.x, followed.position.y)
-            : null;
-        const renderVelocity = velocity
-            ? this.renderPoint(velocity.vx, velocity.vy)
-            : { x: 0, y: 0 };
-        const next = stepSceneCamera(cam, {
-            x: this.camera.position.x,
-            y: this.camera.position.y,
-            halfW: (this.camera.right - this.camera.left) / 2,
-            halfH: this.viewHeight / 2,
-            target,
-            vx: renderVelocity.x,
-            vy: renderVelocity.y,
-            dt,
-        });
-        this.camera.position.x = next.x;
-        this.camera.position.y = next.y;
+        this.cameraRig.follow(this.sceneCamera, this.followHost, dt);
     }
     renderPoint(x, y) {
         return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };
     }
-    /**
-     * The audio listener's position (CA-8) in logical coordinates. The camera
-     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
-     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
-     * inverse of `renderPoint` — without it, distance-based attenuation would
-     * measure render-space distance instead of real game distance.
-     */
-    audioListenerPosition() {
-        const { x, y } = this.camera.position;
-        return this.sceneProjection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
-    }
-    dispatchCollisions() {
-        dispatchHitboxCollisions(this);
-    }
     resize() {
         const canvas = this.renderer.domElement;
         const { clientWidth: w, clientHeight: h } = canvas;
@@ -747,13 +766,7 @@ export class Game {
             this.renderer.setViewport(vx, vy, vw, vh);
             this.renderer.setScissor(vx, vy, vw, vh);
         }
-        const halfH = this.viewHeight / 2;
-        const halfW = halfH * aspect;
-        this.camera.left = -halfW;
-        this.camera.right = halfW;
-        this.camera.top = halfH;
-        this.camera.bottom = -halfH;
-        this.camera.updateProjectionMatrix();
+        this.cameraRig.fit(aspect, this.viewHeight);
         layoutCameraEffects(this.cameraEffects, gameViewport(w, h, this.resolution));
     }
 }

package/dist/index.d.ts

@@ -3,6 +3,9 @@ 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';
@@ -21,11 +24,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 +52,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 +61,18 @@ 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 { 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 +98,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,5 +1,6 @@
 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 { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';
@@ -9,8 +10,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 +28,12 @@ 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 { 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;