@waica/engine 0.24.0 → 0.26.0

package/dist/post-effects.js

@@ -0,0 +1,48 @@
+import { resolveColorGrade, resolvePostEffects, resolveVignette, } from './scene-render-options.js';
+/**
+ * `game.post` (issue #78): the live scene's Post Effects — a vignette and a
+ * color grade, each off (null) unless its scene declares it or a game turns
+ * it on. With either on, the frame renders through a render target and one
+ * full-screen pass; with both off, it draws straight to the canvas. Camera
+ * Effects (ADR 0020) sit above and are never altered. They die with their scene.
+ */
+export class GamePost {
+    state = resolvePostEffects(undefined);
+    /** The vignette now, a copy; null when off. */
+    get vignette() {
+        const { vignette } = this.state;
+        return vignette ? { ...vignette } : null;
+    }
+    /**
+     * Turns the vignette off with null, or changes it field by field over the
+     * current one (absent fields take their defaults when it was off), clamped to 0..1.
+     */
+    set vignette(value) {
+        this.state = { ...this.state, vignette: value ? resolveVignette({ ...this.state.vignette, ...value }) : null };
+    }
+    /** The color grade now, a copy; null when off. */
+    get colorGrade() {
+        const { colorGrade } = this.state;
+        return colorGrade ? { ...colorGrade } : null;
+    }
+    /**
+     * Turns the color grade off with null, or changes it field by field over the
+     * current one (absent fields neutral when it was off), clamped — like
+     * `game.lighting.ambient`, so a tween of one field keeps the others.
+     */
+    set colorGrade(value) {
+        this.state = { ...this.state, colorGrade: value ? resolveColorGrade({ ...this.state.colorGrade, ...value }) : null };
+    }
+    /** Whether any Post Effect is on. */
+    get active() {
+        return this.state.vignette !== null || this.state.colorGrade !== null;
+    }
+    /** Adopts a scene's `render.post`, replacing whatever the previous scene left. Called by Game. */
+    loadScene(render) {
+        this.state = resolvePostEffects(render?.post);
+    }
+    /** Every effect off again. */
+    unloadScene() {
+        this.loadScene(undefined);
+    }
+}

package/dist/post-pass.d.ts

@@ -0,0 +1,23 @@
+import * as THREE from 'three/webgpu';
+import type { PostEffectsState } from './scene-render-options.js';
+/**
+ * The Post Effects' render target and pass: the frame is drawn into `target`
+ * exactly as onto the canvas — 8-bit, sRGB-encoded, blending on sRGB values
+ * (ADR 0025's canvas path) — at the light-map resolution with nearest upscale
+ * (E2), then `draw` writes it to the canvas through the effects. A half-float
+ * linear target drew nothing on CI's headless Linux WebGPU (PR #150), and it
+ * changed every translucent edge.
+ */
+export declare class PostPass {
+    readonly target: THREE.RenderTarget<THREE.Texture<unknown, THREE.TextureEventMap>, THREE.RenderTargetEventMap>;
+    private readonly uniforms;
+    private readonly drawnLikeCanvas;
+    private readonly quad;
+    /** Sizes the target for this frame. */
+    resize(width: number, height: number): void;
+    /** Draws the target to whatever is bound now (the canvas), with this frame's effects. */
+    draw(renderer: THREE.WebGPURenderer, effects: PostEffectsState): void;
+    private setVignette;
+    private setColorGrade;
+    dispose(): void;
+}

package/dist/post-pass.js

@@ -0,0 +1,93 @@
+import { clamp, dot, float, length, max, mix, texture, uniform, uv, vec3, vec4 } from 'three/tsl';
+import * as THREE from 'three/webgpu';
+import { FrameQuad } from './frame-quad.js';
+import { hexChannels } from './scene-lighting.js';
+import { drawLikeCanvas } from './render-output.js';
+function createUniforms() {
+    return {
+        vignetteOn: uniform(0),
+        vignetteIntensity: uniform(0),
+        vignetteRadius: uniform(0),
+        gradeOn: uniform(0),
+        tint: uniform(new THREE.Vector3(1, 1, 1)),
+        contrast: uniform(1),
+        saturation: uniform(1),
+    };
+}
+/**
+ * The single full-screen pass of the Post Effects (issue #78 CA-11): it reads
+ * the frame from the target, already in the canvas's sRGB values, grades it —
+ * tint, then saturation around Rec. 709 luma, then contrast around mid grey —
+ * and darkens it towards the corners. Its output is the canvas's sRGB value.
+ */
+function createPostMaterial(scene, u) {
+    const material = new THREE.MeshBasicNodeMaterial();
+    // Already the canvas's sRGB values (drawLikeCanvas): graded as they would show.
+    const display = texture(scene, uv()).rgb;
+    const tinted = display.mul(u.tint);
+    const luma = dot(tinted, vec3(0.2126, 0.7152, 0.0722));
+    const saturated = mix(vec3(luma, luma, luma), tinted, u.saturation);
+    const graded = saturated.sub(0.5).mul(u.contrast).add(0.5);
+    const color = mix(display, graded, u.gradeOn);
+    // 0 at the centre, 1 at the corners.
+    const distance = length(uv().sub(0.5).mul(2)).div(Math.SQRT2);
+    const ramp = clamp(distance.sub(u.vignetteRadius).div(max(float(1).sub(u.vignetteRadius), 1e-3)), 0, 1);
+    const eased = ramp.mul(ramp).mul(float(3).sub(ramp.mul(2)));
+    const vignette = float(1).sub(u.vignetteIntensity.mul(eased).mul(u.vignetteOn));
+    material.fragmentNode = vec4(clamp(color.mul(vignette), vec3(0, 0, 0), vec3(1, 1, 1)), 1);
+    material.depthTest = false;
+    material.depthWrite = false;
+    return material;
+}
+/**
+ * The Post Effects' render target and pass: the frame is drawn into `target`
+ * exactly as onto the canvas — 8-bit, sRGB-encoded, blending on sRGB values
+ * (ADR 0025's canvas path) — at the light-map resolution with nearest upscale
+ * (E2), then `draw` writes it to the canvas through the effects. A half-float
+ * linear target drew nothing on CI's headless Linux WebGPU (PR #150), and it
+ * changed every translucent edge.
+ */
+export class PostPass {
+    target = new THREE.RenderTarget(1, 1, {
+        type: THREE.UnsignedByteType,
+        minFilter: THREE.NearestFilter,
+        magFilter: THREE.NearestFilter,
+        depthBuffer: true,
+        // The canvas's own MSAA (antialias: true): geometry edges match the frame without post.
+        samples: 4,
+    });
+    uniforms = createUniforms();
+    drawnLikeCanvas = drawLikeCanvas(this.target);
+    quad = new FrameQuad(createPostMaterial(this.target.texture, this.uniforms));
+    /** Sizes the target for this frame. */
+    resize(width, height) {
+        if (this.target.width !== width || this.target.height !== height)
+            this.target.setSize(width, height);
+    }
+    /** Draws the target to whatever is bound now (the canvas), with this frame's effects. */
+    draw(renderer, effects) {
+        this.setVignette(effects.vignette);
+        this.setColorGrade(effects.colorGrade);
+        this.quad.render(renderer);
+    }
+    setVignette(vignette) {
+        const u = this.uniforms;
+        u.vignetteOn.value = vignette ? 1 : 0;
+        u.vignetteIntensity.value = vignette ? vignette.intensity : 0;
+        u.vignetteRadius.value = vignette ? vignette.radius : 0;
+    }
+    setColorGrade(grade) {
+        const u = this.uniforms;
+        const neutral = { tint: '#ffffff', contrast: 1, saturation: 1 };
+        const { tint, contrast, saturation } = grade ?? neutral;
+        u.gradeOn.value = grade ? 1 : 0;
+        const [r, g, b] = hexChannels(tint);
+        u.tint.value.set(r, g, b);
+        u.contrast.value = contrast;
+        u.saturation.value = saturation;
+    }
+    dispose() {
+        this.target.dispose();
+        this.quad.dispose();
+    }
+}

package/dist/render-layers.d.ts

@@ -0,0 +1,18 @@
+import type * as THREE from 'three/webgpu';
+/**
+ * The three.js layer an Emissive drawable lives on, alone (issue #78 CA-10).
+ * The Game's camera sees layer 0 and this one, so an unlit scene draws an
+ * Emissive drawable in place like any other; a lit scene draws layer 0, then
+ * its light-map, then this layer at full brightness (ADR 0026).
+ */
+export declare const EMISSIVE_LAYER = 1;
+/** Puts `object` on the Emissive layer alone, or back on the default layer 0. */
+export declare function setEmissive(object: THREE.Object3D, emissive: boolean): void;
+/**
+ * The alphaTest every drawable carries (PR #150 review): a texel whose alpha
+ * byte is 0 is discarded instead of drawn. It contributes no color either way
+ * (normal blending keeps the frame), but discarded it also writes no depth, so
+ * an Emissive drawable drawn after the lit pass shows through the transparent
+ * texels of a lit sprite in front of it, and stays hidden behind its opaque ones.
+ */
+export declare const TRANSPARENT_TEXEL_ALPHA: number;

package/dist/render-layers.js

@@ -0,0 +1,19 @@
+/**
+ * The three.js layer an Emissive drawable lives on, alone (issue #78 CA-10).
+ * The Game's camera sees layer 0 and this one, so an unlit scene draws an
+ * Emissive drawable in place like any other; a lit scene draws layer 0, then
+ * its light-map, then this layer at full brightness (ADR 0026).
+ */
+export const EMISSIVE_LAYER = 1;
+/** Puts `object` on the Emissive layer alone, or back on the default layer 0. */
+export function setEmissive(object, emissive) {
+    object.layers.set(emissive ? EMISSIVE_LAYER : 0);
+}
+/**
+ * The alphaTest every drawable carries (PR #150 review): a texel whose alpha
+ * byte is 0 is discarded instead of drawn. It contributes no color either way
+ * (normal blending keeps the frame), but discarded it also writes no depth, so
+ * an Emissive drawable drawn after the lit pass shows through the transparent
+ * texels of a lit sprite in front of it, and stays hidden behind its opaque ones.
+ */
+export const TRANSPARENT_TEXEL_ALPHA = 1 / 512;

package/dist/render-output.d.ts

@@ -8,6 +8,13 @@ import * as THREE from 'three/webgpu';
  * one more draw per frame. A render target keeps the linear working space.
  */
 export declare function drawStraightToCanvas(renderer: THREE.WebGPURenderer): void;
+/**
+ * Makes `target` receive what the canvas would (issue #78): every material
+ * encodes to sRGB into it and blends on sRGB values, so a frame drawn there
+ * and copied to the canvas is the frame drawn straight to the canvas. The
+ * Post Effects' 8-bit target.
+ */
+export declare function drawLikeCanvas(target: THREE.RenderTarget): THREE.RenderTarget;
 /**
  * The scene background for a canvas drawn straight: three clears with a
  * color's working-space (linear) components, and the canvas stores sRGB, so

package/dist/render-output.js

@@ -12,7 +12,23 @@ export function drawStraightToCanvas(renderer) {
     // The working space as output: three then needs no intermediate target.
     renderer.outputColorSpace = THREE.ColorManagement.workingColorSpace;
     const context = renderer.contextNode.value;
-    context.getOutput = (output, builder) => builder.renderer.getRenderTarget() === null ? workingToColorSpace(output, THREE.SRGBColorSpace) : output;
+    context.getOutput = (output, builder) => {
+        const target = builder.renderer.getRenderTarget();
+        const likeCanvas = target === null || (typeof target === 'object' && canvasLike.has(target));
+        return likeCanvas ? workingToColorSpace(output, THREE.SRGBColorSpace) : output;
+    };
+}
+/** Render targets that hold a frame exactly as the canvas would: sRGB-encoded 8-bit values. */
+const canvasLike = new WeakSet();
+/**
+ * Makes `target` receive what the canvas would (issue #78): every material
+ * encodes to sRGB into it and blends on sRGB values, so a frame drawn there
+ * and copied to the canvas is the frame drawn straight to the canvas. The
+ * Post Effects' 8-bit target.
+ */
+export function drawLikeCanvas(target) {
+    canvasLike.add(target);
+    return target;
 }
 /**
  * The scene background for a canvas drawn straight: three clears with a

package/dist/runtime-bridge.d.ts

@@ -85,7 +85,7 @@ export interface RuntimeBridge {
 }
 /** Why a Game can never become operational; reported through the activation. */
 export interface RuntimeBridgeFailure {
-    code: 'render-backend-failed';
+    code: 'render-backend-failed' | 'physics-backend-failed';
     message: string;
 }
 /** Ephemeral pre-page hook installed by the owner of a browser context. */

package/dist/runtime-inspection.d.ts

@@ -1,8 +1,12 @@
 import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
 import type { CameraEffectsState } from './camera-effects.js';
+import type { SceneSpace } from './scene-space.js';
+import { type RuntimeSnapshotView } from './runtime-view-snapshot.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
+import { type RuntimeSnapshotLighting, type RuntimeSnapshotPost } from './runtime-lighting-snapshot.js';
+import { type RuntimeSnapshotPhysics } from './runtime-physics-snapshot.js';
 export type ProjectionMarkerKind = 'cycle' | 'unsupported' | 'error' | 'truncated';
 export interface ProjectionMarker {
     $waica: ProjectionMarkerKind | 'date' | 'bigint' | 'map' | 'set';
@@ -124,6 +128,16 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     time: RuntimeSnapshotTime;
     ui: RuntimeSnapshotUi;
     camera: RuntimeSnapshotCamera;
+    /** The live scene's space (`render.space`, ADR 0027); `'2d'` with no scene. Never filtered. */
+    space: SceneSpace;
+    /** The view the scene is drawn from: the orthographic centre and zoom, or the perspective pose (issue #154 CA-16). Never filtered. */
+    view: RuntimeSnapshotView;
+    /** Ambient Light and live Lights (issue #78 CA-12), logical coordinates; never filtered. */
+    lighting: RuntimeSnapshotLighting;
+    /** Post Effects (issue #78 CA-12), each null when off; never filtered. */
+    post: RuntimeSnapshotPost;
+    /** The live 3D scene's physics world: state, gravity and bodies (issue #159 CA-17); absent in a 2D scene, never filtered. */
+    physics?: RuntimeSnapshotPhysics;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;

package/dist/runtime-inspection.js

@@ -1,5 +1,8 @@
+import { cameraEffectsSnapshot, viewSnapshot } from './runtime-view-snapshot.js';
 import { anchoredPiecesOf } from './ui.js';
 import { componentClassOf } from './component-registry.js';
+import { capLights, lightingSnapshot, postSnapshot, } from './runtime-lighting-snapshot.js';
+import { capBodies, physicsSection } from './runtime-physics-snapshot.js';
 export const RUNTIME_PROJECTION_LIMITS = {
     depth: 5,
     entries: 100,
@@ -292,7 +295,12 @@ export class RuntimeInspector {
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
-            camera: this.game.cameraEffects.state,
+            camera: cameraEffectsSnapshot(this.game),
+            space: this.game.space,
+            view: viewSnapshot(this.game),
+            lighting: lightingSnapshot(this.game, (entity) => this.idFor(entity)),
+            post: postSnapshot(this.game),
+            ...physicsSection(this.game, (entity) => this.idFor(entity)),
         });
     }
     audioSnapshot() {
@@ -341,7 +349,9 @@ export class RuntimeInspector {
             if (fitsSnapshot(capped))
                 return capped;
         }
-        return capAnchored(capped);
+        const anchoredCapped = capAnchored(capped);
+        const bodiesCapped = capBodies(anchoredCapped, fitsSnapshot);
+        return fitsSnapshot(bodiesCapped) ? bodiesCapped : capLights(bodiesCapped, fitsSnapshot);
     }
     idFor(entity) {
         const existing = this.ids.get(entity);

package/dist/runtime-lighting-snapshot.d.ts

@@ -0,0 +1,67 @@
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import type { ProjectionIssue } from './runtime-inspection.js';
+import type { Vec3Json } from './scene-camera-3d.js';
+import type { AmbientLight, PostEffectsState } from './scene-render-options.js';
+/** One live Light as a Runtime Snapshot reports it: its entity's name, logical position and params. */
+export interface RuntimeSnapshotLight {
+    /** The entity's name, as `ui.anchored[].entity` reports it. */
+    entity: string;
+    /** The entity's snapshot id (`entity-N`), unique where names repeat. */
+    id: string;
+    x: number;
+    y: number;
+    radius: number;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+    bands: number;
+    softness: number;
+    castShadows: boolean;
+}
+/** One live Sun in a 3D scene (issue #154 CA-16): its entity's name and id, the unit direction it shines along, color and intensity. */
+export interface RuntimeSnapshotSun {
+    entity: string;
+    id: string;
+    direction: Vec3Json;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+}
+/** One live Point Light in a 3D scene (issue #154 CA-16): its world position and look; `distance` 0 is unlimited. */
+export interface RuntimeSnapshotPointLight {
+    entity: string;
+    id: string;
+    position: Vec3Json;
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+    distance: number;
+}
+/**
+ * `game.lighting` (issue #78 CA-12): the Ambient Light now and every live
+ * Light, in logical coordinates. A 3D scene (issue #154 CA-16) adds its
+ * Suns and Point Lights; a 2D scene's snapshot has neither key.
+ */
+export interface RuntimeSnapshotLighting {
+    ambient: AmbientLight;
+    lights: RuntimeSnapshotLight[];
+    sun?: RuntimeSnapshotSun[];
+    pointLights?: RuntimeSnapshotPointLight[];
+}
+/** `game.post` (issue #78 CA-12): each Post Effect, null when off. */
+export type RuntimeSnapshotPost = PostEffectsState;
+export declare function lightingSnapshot(game: Game, idFor: (entity: Entity) => string): RuntimeSnapshotLighting;
+export declare function postSnapshot(game: Game): RuntimeSnapshotPost;
+/** What capping the lights needs from a snapshot: its lights and its projection issues. */
+interface LightsCappable {
+    lighting: RuntimeSnapshotLighting;
+    projectionIssues: ProjectionIssue[];
+}
+/**
+ * The global cap's last stage, once entities and Anchored Pieces are gone
+ * (review): drops lights from the end until the snapshot fits, recording how
+ * many went with a `truncated` marker at `lighting.lights[n]`.
+ */
+export declare function capLights<T extends LightsCappable>(snapshot: T, fits: (candidate: T) => boolean): T;
+export {};

package/dist/runtime-lighting-snapshot.js

@@ -0,0 +1,77 @@
+import * as THREE from 'three/webgpu';
+import { PointLight } from './components/point-light.js';
+import { Sun } from './components/sun.js';
+const hex = (channel) => Math.round(channel * 255).toString(16).padStart(2, '0');
+const rounded = (value) => Math.round(value * 1e6) / 1e6 || 0;
+const hexOf = (color) => `#${(color & 0xffffff).toString(16).padStart(6, '0')}`;
+function unit(direction) {
+    const [x, y, z] = new THREE.Vector3(...direction).normalize().toArray();
+    return [rounded(x), rounded(y), rounded(z)];
+}
+/** The Suns and Point Lights of a 3D scene's entities, in spawn order. */
+function lights3dSnapshot(game, idFor) {
+    const sun = [];
+    const pointLights = [];
+    for (const entity of game.entities) {
+        for (const component of entity.components) {
+            if (component instanceof Sun) {
+                const { direction, color, intensity } = component;
+                sun.push({ entity: entity.name, id: idFor(entity), direction: unit(direction), color: hexOf(color), intensity });
+            }
+            else if (component instanceof PointLight && component.light) {
+                const { color, intensity, distance, light } = component;
+                light.updateWorldMatrix(true, false);
+                const at = light.getWorldPosition(new THREE.Vector3());
+                const position = [rounded(at.x), rounded(at.y), rounded(at.z)];
+                pointLights.push({ entity: entity.name, id: idFor(entity), position, color: hexOf(color), intensity, distance });
+            }
+        }
+    }
+    return { sun, pointLights };
+}
+export function lightingSnapshot(game, idFor) {
+    return {
+        ...(game.space === '3d' ? lights3dSnapshot(game, idFor) : {}),
+        ambient: game.lighting.ambient,
+        lights: game.lighting.lights.map((light) => {
+            const field = light.field();
+            const [r, g, b] = field.color;
+            return {
+                entity: light.entity.name,
+                id: idFor(light.entity),
+                x: field.x,
+                y: field.y,
+                radius: field.radius,
+                color: `#${hex(r)}${hex(g)}${hex(b)}`,
+                intensity: field.intensity,
+                bands: field.bands,
+                softness: field.softness,
+                castShadows: field.castShadows,
+            };
+        }),
+    };
+}
+export function postSnapshot(game) {
+    return { vignette: game.post.vignette, colorGrade: game.post.colorGrade };
+}
+/**
+ * The global cap's last stage, once entities and Anchored Pieces are gone
+ * (review): drops lights from the end until the snapshot fits, recording how
+ * many went with a `truncated` marker at `lighting.lights[n]`.
+ */
+export function capLights(snapshot, fits) {
+    let capped = snapshot;
+    const retained = [...snapshot.lighting.lights];
+    while (retained.length > 0) {
+        retained.pop();
+        const omitted = snapshot.lighting.lights.length - retained.length;
+        capped = {
+            ...snapshot,
+            lighting: { ...snapshot.lighting, lights: [...retained] },
+            projectionIssues: [...snapshot.projectionIssues, { path: `lighting.lights[${retained.length}]`, marker: 'truncated', omitted }],
+        };
+        if (fits(capped))
+            return capped;
+    }
+    return capped;
+}

package/dist/runtime-physics-snapshot.d.ts

@@ -0,0 +1,41 @@
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+import { type BodyKind } from './physics-3d/body-sync.js';
+import type { PhysicsState } from './physics-3d/physics-host.js';
+import type { ProjectionIssue } from './runtime-inspection.js';
+import type { Vec3Json } from './scene-camera-3d.js';
+/** One live body of a 3D scene (issue #159 CA-17): its entity's name and snapshot id, its Rapier type, velocity and whether it stands on something. */
+export interface RuntimeSnapshotBody {
+    entity: string;
+    id: string;
+    type: BodyKind;
+    velocity: Vec3Json;
+    grounded: boolean;
+}
+/**
+ * `game.physics` of a 3D scene (issue #159 CA-17), beside `lighting`: the
+ * world's state (`loading` until the Rapier module arrives), its gravity and
+ * every body in spawn order, rounded to 1e-6. Never filtered by entity or
+ * component filters; a 2D scene's snapshot has no `physics` key.
+ */
+export interface RuntimeSnapshotPhysics {
+    state: PhysicsState;
+    gravity: Vec3Json;
+    bodies: RuntimeSnapshotBody[];
+}
+/** The `physics` section of a 3D scene's snapshot, as the spread that adds it; nothing in a 2D scene. */
+export declare function physicsSection(game: Game, idFor: (entity: Entity) => string): {
+    physics?: RuntimeSnapshotPhysics;
+};
+/** What capping the bodies needs from a snapshot: its physics section and its projection issues. */
+interface BodiesCappable {
+    physics?: RuntimeSnapshotPhysics;
+    projectionIssues: ProjectionIssue[];
+}
+/**
+ * The global cap's stage for bodies, beside the lights' (`capLights`): drops
+ * bodies from the end until the snapshot fits, recording how many went with a
+ * `truncated` marker at `physics.bodies[n]`.
+ */
+export declare function capBodies<T extends BodiesCappable>(snapshot: T, fits: (candidate: T) => boolean): T;
+export {};

package/dist/runtime-physics-snapshot.js

@@ -0,0 +1,45 @@
+import { bodyVelocity } from './physics-3d/body-sync.js';
+const rounded = (value) => Math.round(value * 1e6) / 1e6 || 0;
+const roundedVector = (x, y, z) => [rounded(x), rounded(y), rounded(z)];
+/** The `physics` section of a 3D scene's snapshot, as the spread that adds it; nothing in a 2D scene. */
+export function physicsSection(game, idFor) {
+    if (game.space !== '3d')
+        return {};
+    const world = game.physics.world;
+    const [gx, gy, gz] = game.physics.sceneGravity;
+    const bodies = (world?.bodiesOf(game.entities) ?? []).map((record) => {
+        const { x, y, z } = bodyVelocity(record);
+        return {
+            entity: record.entity.name,
+            id: idFor(record.entity),
+            type: record.kind,
+            velocity: roundedVector(x, y, z),
+            grounded: record.grounded,
+        };
+    });
+    return { physics: { state: game.physics.state, gravity: roundedVector(gx, gy, gz), bodies } };
+}
+/**
+ * The global cap's stage for bodies, beside the lights' (`capLights`): drops
+ * bodies from the end until the snapshot fits, recording how many went with a
+ * `truncated` marker at `physics.bodies[n]`.
+ */
+export function capBodies(snapshot, fits) {
+    const physics = snapshot.physics;
+    if (!physics || fits(snapshot))
+        return snapshot;
+    let capped = snapshot;
+    const retained = [...physics.bodies];
+    while (retained.length > 0) {
+        retained.pop();
+        const omitted = physics.bodies.length - retained.length;
+        capped = {
+            ...snapshot,
+            physics: { ...physics, bodies: [...retained] },
+            projectionIssues: [...snapshot.projectionIssues, { path: `physics.bodies[${retained.length}]`, marker: 'truncated', omitted }],
+        };
+        if (fits(capped))
+            return capped;
+    }
+    return capped;
+}

package/dist/runtime-view-snapshot.d.ts

@@ -0,0 +1,25 @@
+import type { CameraEffectsState } from './camera-effects.js';
+import type { Game } from './game.js';
+import type { Vec3Json } from './scene-camera-3d.js';
+/**
+ * The view the scene is drawn from (issue #154 CA-16), beside the Camera
+ * Effects `camera`: the orthographic camera's centre and visible height, or
+ * the perspective camera's pose. Always reflects the live camera.
+ */
+export type RuntimeSnapshotView = {
+    kind: 'orthographic';
+    position: [number, number];
+    zoom: number;
+} | {
+    kind: 'perspective';
+    position: Vec3Json;
+    target: Vec3Json;
+    fov: number;
+};
+export declare function viewSnapshot(game: Game): RuntimeSnapshotView;
+/**
+ * `game.cameraEffects.state` as the snapshot reports it. A perspective camera
+ * does not shake (spec decision 24: shake is a no-op in a 3D scene), so a 3D
+ * scene reports no offset even though the effect's own state keeps decaying.
+ */
+export declare function cameraEffectsSnapshot(game: Game): CameraEffectsState;

package/dist/runtime-view-snapshot.js

@@ -0,0 +1,30 @@
+import * as THREE from 'three/webgpu';
+import { isPerspectiveCamera } from './camera-projection.js';
+/** Float noise off a pose, so a camera that did not move reports the numbers it was declared with. */
+const clean = (value) => Math.round(value * 1e6) / 1e6 || 0;
+function vector(value) {
+    return [clean(value.x), clean(value.y), clean(value.z)];
+}
+export function viewSnapshot(game) {
+    const camera = game.camera;
+    if (!isPerspectiveCamera(camera)) {
+        return { kind: 'orthographic', position: [clean(camera.position.x), clean(camera.position.y)], zoom: game.view };
+    }
+    camera.updateMatrixWorld();
+    const ahead = camera.getWorldDirection(new THREE.Vector3()).multiplyScalar(game.cameraRig.lookDistance);
+    return {
+        kind: 'perspective',
+        position: vector(camera.position),
+        target: vector(camera.position.clone().add(ahead)),
+        fov: camera.fov,
+    };
+}
+/**
+ * `game.cameraEffects.state` as the snapshot reports it. A perspective camera
+ * does not shake (spec decision 24: shake is a no-op in a 3D scene), so a 3D
+ * scene reports no offset even though the effect's own state keeps decaying.
+ */
+export function cameraEffectsSnapshot(game) {
+    const state = game.cameraEffects.state;
+    return game.space === '3d' ? { ...state, shake: { x: 0, y: 0 } } : state;
+}