@waica/engine 0.18.0 → 0.19.0

package/README.md

@@ -194,6 +194,28 @@ game.time.now  // seconds of Game Time since the Game started
 - **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
 - **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.
 
+## game.cameraEffects: shake, fade and flash
+
+Every `Game` owns a `cameraEffects: CameraEffects` service beside `game.camera`, which stays the plain `THREE.OrthographicCamera` (ADR 0020). Effects advance only inside a Simulation Step, right after the scene camera, so nothing moves while the Game is not simulating, is stopped, or a Run Session is paused; `step { frames: N }` advances them by exactly N steps.
+
+```ts
+game.cameraEffects.shake({ intensity: 0.3, seconds: 0.25 })          // world units, decaying to 0
+const out = game.cameraEffects.fade({ to: 'black', seconds: 0.4 })   // 'black' | 'white' | '#rrggbb' | 'clear'
+game.cameraEffects.flash({ color: 'white', seconds: 0.15 })          // up to 1, back to exactly 0
+out.cancel()                                                          // opacity stays where it was
+await out.done                                                        // true: completed; false: cancelled or replaced
+```
+
+- **Shake.** An offset added to the camera only while drawing (the world render and Anchored Pieces), never to the base center that follow, deadzone and limits compute, so smoothing never feeds on it. Each axis stays within `intensity · (1 − ease(t / seconds))` (`easing` takes `game.time`'s names, `'linear'` by default) and is exactly `{0, 0}` from `seconds` on. Overlapping shakes apply the largest current amplitude. The jitter is deterministic per Simulation Step (no `Math.random`), so a Run Session reproduces it. It is not re-clamped to `limits`: at a map edge up to `intensity` beyond them can show. Under a fixed `resolution` the offset snaps to whole screen pixels; the base center is never snapped.
+- **Fade.** Carries an HTML layer over the game viewport — inside the letterbox, above the world, UI Pieces and Anchored Pieces — from its current opacity to 1 in the given color, or to 0 with `'clear'`, and then holds. A new `fade` cancels a running one (its `done` resolves `false`) and starts from the current opacity.
+- **Flash.** Its own layer above the Fade, shown at opacity 1 and returned to exactly 0 over `seconds`; it never changes the Fade.
+- **Scope.** A Fade is session-scoped: it survives `unloadScene()` and every scene load with its color, opacity and any running progress, so it can cover a scene change. A Shake or Flash is scene-scoped: `unloadScene()` ends it, running no callback (its `done` resolves `false`). `game.dispose()` ends everything and removes the layers. This follows the audio and timer scope notes above (ADR 0011, ADR 0017): a transition fade is exactly the case that must cross a scene change.
+- **Invalid arguments never throw.** A non-finite or negative `seconds`/`intensity`, an unknown color or an unknown easing logs one `[waica]` warning and returns a handle whose `done` resolves `false`; no effect changes.
+- **Scene Transition.** `SceneTransition` takes `fadeSeconds` (default 0: a hard cut) and `fadeColor` (default `'black'`): it fades out over `fadeSeconds`, loads its destination, then clears over `fadeSeconds` in the incoming scene. Simulation and input keep running; the component ignores further triggers during its outgoing fade. The Runtime Bridge `scene` operation stays a hard cut.
+- **Runtime Snapshot.** Every snapshot carries `camera: { shake: { x, y }, fade: { color, opacity }, flash: { color, opacity } }` from the last completed step, under the `'camera-effects'` capability.
+
+A Fade to a color that nothing clears leaves the view covered; the engine does not warn.
+
 ## game.ui.attach: Anchored Pieces
 
 A UI Piece shown with `game.ui.show(name)` is a screen-space singleton. `game.ui.attach(piece, entity, options?)` instead creates an **Anchored Piece**: a new instance of the piece that follows `entity` across the screen, with its own shadow root and its own values. Every call is a new instance — five orcs can each carry a `health-bar` — and the screen piece of the same name is never mounted, shown or changed by it.

package/dist/camera-effects.d.ts

@@ -0,0 +1,142 @@
+import type { ViewportRect } from './anchored-pieces.js';
+import { type EasingName } from './game-time.js';
+/** A Camera Effect color: a name or a six-digit hex, case-insensitive. */
+export type CameraEffectColor = 'black' | 'white' | `#${string}`;
+export interface ShakeOptions {
+    /** The largest offset, in world units, on each axis. Finite and >= 0. */
+    intensity: number;
+    /** Seconds of Game Time until the offset reaches 0. Finite and >= 0. */
+    seconds: number;
+    /** How the amplitude decays from `intensity` to 0; default `'linear'`. */
+    easing?: EasingName;
+}
+export interface FadeOptions {
+    /** The color to carry the view to (opacity 1), or `'clear'` (opacity 0, color kept). */
+    to: CameraEffectColor | 'clear';
+    /** Seconds of Game Time from the current opacity to the target. Finite and >= 0. */
+    seconds: number;
+    easing?: EasingName;
+}
+export interface FlashOptions {
+    color: CameraEffectColor;
+    /** Seconds of Game Time from opacity 1 back to 0. Finite and >= 0. */
+    seconds: number;
+}
+/** What `shake`, `fade` and `flash` hand back. */
+export interface CameraEffectHandle {
+    /** Stops the effect where it is. Idempotent; resolves `done` with false. */
+    cancel(): void;
+    /** True once the effect completed; false if cancelled, replaced, ended by its scope or invalid. */
+    readonly done: Promise<boolean>;
+    /**
+     * True once a *later* call to the same kind of effect has taken over
+     * before this one ended on its own — false while it is still running,
+     * and false once it ends on its own accord (completes, is cancelled, or
+     * ends by its scope) with nothing else in its place. A Shake never
+     * supersedes another (CA-7: overlapping shakes coexist), so this is
+     * always false for a Shake handle. Unlike `done`, this reads
+     * synchronously: a Promise only notifies its `.then()` in a microtask,
+     * which can land well after a caller scheduled on Game Time needs the
+     * answer on an exact Simulation Step (PR #98 review, `scene-
+     * transition.ts`).
+     */
+    readonly superseded: boolean;
+}
+/** The effects' state after the last completed Simulation Step (read-only copy). */
+export interface CameraEffectsState {
+    /** The offset, in world units, added to the camera only while drawing. */
+    shake: {
+        x: number;
+        y: number;
+    };
+    fade: {
+        color: string;
+        opacity: number;
+    };
+    flash: {
+        color: string;
+        opacity: number;
+    };
+}
+export interface CameraEffectsOptions {
+    /** Where the Fade and Flash layers mount (the canvas's parent); resolved lazily. */
+    host: () => HTMLElement;
+    /** One screen pixel in world units under a fixed resolution, or null (no snap). */
+    pixel: () => number | null;
+}
+declare const ADVANCE: unique symbol;
+declare const LAYOUT: unique symbol;
+/**
+ * Screen-level Camera Effects (issue #74, ADR 0020): Shake, Fade and Flash,
+ * beside `game.camera` and never written into it. They advance only inside
+ * a Simulation Step, right after the scene camera (spec inference 9), so
+ * nothing moves while the Game is not simulating or a Run Session is
+ * paused. A Shake is an offset the Game adds to the camera only while it
+ * draws; a Fade and a Flash are HTML layers over the letterboxed game
+ * viewport, above the UI overlay. A Fade is session-scoped (it survives a
+ * scene change, ADR 0011); a Shake or Flash dies with its scene.
+ */
+export declare class CameraEffects {
+    private readonly options;
+    private steps;
+    private readonly shakes;
+    private offset;
+    private fadeRun;
+    private flashRun;
+    private readonly fadeLayer;
+    private readonly flashLayer;
+    private rect;
+    constructor(options: CameraEffectsOptions);
+    /** A fresh copy of the effects after the last completed Simulation Step. */
+    get state(): CameraEffectsState;
+    /**
+     * Jitters the drawn view by up to `intensity` world units per axis,
+     * decaying to 0 over `seconds`. Overlapping shakes apply the largest
+     * current amplitude. Not re-clamped to the scene camera's limits; snapped
+     * to whole screen pixels under a fixed resolution.
+     */
+    shake(options: ShakeOptions): CameraEffectHandle;
+    /**
+     * Carries the Fade layer from its current opacity to 1 in `to`'s color,
+     * or to 0 with `'clear'`, over `seconds`; the result then holds. A new
+     * fade cancels a running one (its `done` resolves false).
+     */
+    fade(options: FadeOptions): CameraEffectHandle;
+    /**
+     * Shows the Flash layer at opacity 1 in `color` and returns it to exactly
+     * 0 over `seconds`, independent of (and drawn above) the Fade. A new flash
+     * replaces a running one.
+     */
+    flash(options: FlashOptions): CameraEffectHandle;
+    /**
+     * Ends every Shake and Flash (their `done` resolves false) and keeps the
+     * Fade — opacity, color and any running progress. Called by
+     * `Game.unloadScene()`.
+     */
+    unloadScene(): void;
+    /** Ends every effect and removes the layers (`Game.dispose()`). */
+    dispose(): void;
+    /** Engine-internal: see advanceCameraEffects. */
+    [ADVANCE](): void;
+    /** Engine-internal: see layoutCameraEffects. */
+    [LAYOUT](rect: ViewportRect): void;
+    /** Normalized progress of a timed effect after the current step: 1 at (and past) its end. */
+    private progress;
+    private advanceShakes;
+    /** Mirrors both layers' state onto their elements, mounting them on first need. */
+    private draw;
+    private mount;
+    /** Sizes a layer to the game viewport (the whole host until the Game lays it out). */
+    private place;
+    private invalid;
+}
+/**
+ * Engine-internal: advances every Camera Effect by exactly one Simulation
+ * Step. `Game.simulateStep()` calls it right after the scene camera, so
+ * nothing advances while the Game is not simulating. Not re-exported from
+ * the package entry.
+ */
+export declare function advanceCameraEffects(effects: CameraEffects): void;
+/** Engine-internal: sizes the Fade and Flash layers to the game viewport (`Game.resize()`). */
+export declare function layoutCameraEffects(effects: CameraEffects, rect: ViewportRect): void;
+export {};

package/dist/camera-effects.js

@@ -0,0 +1,334 @@
+import { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+import { resolveEasing } from './game-time.js';
+const COLORS = { black: '#000000', white: '#ffffff' };
+/** Above the UI overlay (`ui.ts`, z-index 9000): a Fade covers the HUD too. */
+const FADE_Z = 9001;
+const FLASH_Z = 9002;
+const ADVANCE = Symbol('waica.cameraEffects.advance');
+const LAYOUT = Symbol('waica.cameraEffects.layout');
+function normalizeColor(value) {
+    if (typeof value !== 'string')
+        return null;
+    if (Object.prototype.hasOwnProperty.call(COLORS, value))
+        return COLORS[value];
+    return /^#[0-9a-fA-F]{6}$/.test(value) ? value.toLowerCase() : null;
+}
+function validSeconds(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function easingOf(value) {
+    if (value !== undefined && typeof value !== 'string')
+        return null;
+    return resolveEasing(value);
+}
+/**
+ * Integer-only hash of (shake creation step, current step, axis) into
+ * [0, 1): the same bits in Node and every browser (spec inference 3), so a
+ * Run Session reproduces a shake frame for frame. No global RNG.
+ */
+function jitter(seed, step, axis) {
+    let h = (Math.imul(seed + 1, 0x9e3779b1) ^ Math.imul(step + 1, 0x85ebca77) ^ Math.imul(axis + 1, 0xc2b2ae3d)) >>> 0;
+    h = Math.imul(h ^ (h >>> 16), 0x7feb352d) >>> 0;
+    h = Math.imul(h ^ (h >>> 15), 0x846ca68b) >>> 0;
+    return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+function settledHandle(done, cancel, superseded) {
+    return {
+        cancel,
+        done,
+        get superseded() {
+            return superseded();
+        },
+    };
+}
+/**
+ * Screen-level Camera Effects (issue #74, ADR 0020): Shake, Fade and Flash,
+ * beside `game.camera` and never written into it. They advance only inside
+ * a Simulation Step, right after the scene camera (spec inference 9), so
+ * nothing moves while the Game is not simulating or a Run Session is
+ * paused. A Shake is an offset the Game adds to the camera only while it
+ * draws; a Fade and a Flash are HTML layers over the letterboxed game
+ * viewport, above the UI overlay. A Fade is session-scoped (it survives a
+ * scene change, ADR 0011); a Shake or Flash dies with its scene.
+ */
+export class CameraEffects {
+    options;
+    steps = 0;
+    shakes = [];
+    offset = { x: 0, y: 0 };
+    fadeRun = null;
+    flashRun = null;
+    fadeLayer = { color: '#000000', opacity: 0, element: null };
+    flashLayer = { color: '#ffffff', opacity: 0, element: null };
+    rect = null;
+    constructor(options) {
+        this.options = options;
+    }
+    /** A fresh copy of the effects after the last completed Simulation Step. */
+    get state() {
+        return {
+            shake: { ...this.offset },
+            fade: { color: this.fadeLayer.color, opacity: this.fadeLayer.opacity },
+            flash: { color: this.flashLayer.color, opacity: this.flashLayer.opacity },
+        };
+    }
+    /**
+     * Jitters the drawn view by up to `intensity` world units per axis,
+     * decaying to 0 over `seconds`. Overlapping shakes apply the largest
+     * current amplitude. Not re-clamped to the scene camera's limits; snapped
+     * to whole screen pixels under a fixed resolution.
+     */
+    shake(options) {
+        const { intensity, seconds } = options;
+        if (!validSeconds(intensity))
+            return this.invalid('shake(): intensity must be a finite number >= 0');
+        if (!validSeconds(seconds))
+            return this.invalid('shake(): seconds must be a finite number >= 0');
+        const ease = easingOf(options.easing);
+        if (!ease)
+            return this.invalid('shake(): easing must be a known easing name');
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = { start: this.steps, seconds, ease, resolve, intensity, superseded: false };
+        this.shakes.push(entry);
+        return settledHandle(done, () => {
+            const index = this.shakes.indexOf(entry);
+            if (index === -1)
+                return;
+            this.shakes.splice(index, 1);
+            entry.resolve(false);
+        }, 
+        // Never superseded (CA-7): overlapping shakes coexist, so nothing
+        // ever sets a Shake entry's flag; it stays false for its own life.
+        () => entry.superseded);
+    }
+    /**
+     * Carries the Fade layer from its current opacity to 1 in `to`'s color,
+     * or to 0 with `'clear'`, over `seconds`; the result then holds. A new
+     * fade cancels a running one (its `done` resolves false).
+     */
+    fade(options) {
+        const clear = options.to === 'clear';
+        const color = clear ? this.fadeLayer.color : normalizeColor(options.to);
+        if (!color)
+            return this.invalid(`fade(): unknown color "${String(options.to)}"; use 'black', 'white', '#rrggbb' or 'clear'`);
+        if (!validSeconds(options.seconds))
+            return this.invalid('fade(): seconds must be a finite number >= 0');
+        const ease = easingOf(options.easing);
+        if (!ease)
+            return this.invalid('fade(): easing must be a known easing name');
+        // Marks the outgoing fade superseded (not just cancelled) before
+        // resolving `done` false: a caller checking `.superseded` later must
+        // see this, whatever happens to the layer afterwards (PR #98 review).
+        if (this.fadeRun)
+            this.fadeRun.superseded = true;
+        this.fadeRun?.resolve(false);
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = {
+            start: this.steps,
+            seconds: options.seconds,
+            ease,
+            resolve,
+            from: this.fadeLayer.opacity,
+            to: clear ? 0 : 1,
+            superseded: false,
+        };
+        this.fadeRun = entry;
+        this.fadeLayer.color = color;
+        this.draw();
+        return settledHandle(done, () => {
+            if (this.fadeRun !== entry)
+                return;
+            this.fadeRun = null;
+            entry.resolve(false);
+        }, () => entry.superseded);
+    }
+    /**
+     * Shows the Flash layer at opacity 1 in `color` and returns it to exactly
+     * 0 over `seconds`, independent of (and drawn above) the Fade. A new flash
+     * replaces a running one.
+     */
+    flash(options) {
+        const color = normalizeColor(options.color);
+        if (!color)
+            return this.invalid(`flash(): unknown color "${String(options.color)}"; use 'black', 'white' or '#rrggbb'`);
+        if (!validSeconds(options.seconds))
+            return this.invalid('flash(): seconds must be a finite number >= 0');
+        if (this.flashRun)
+            this.flashRun.superseded = true;
+        this.flashRun?.resolve(false);
+        let resolve = () => { };
+        const done = new Promise((r) => (resolve = r));
+        const entry = { start: this.steps, seconds: options.seconds, ease: (t) => t, resolve, superseded: false };
+        this.flashRun = entry;
+        this.flashLayer.color = color;
+        this.flashLayer.opacity = 1;
+        this.draw();
+        return settledHandle(done, () => {
+            if (this.flashRun !== entry)
+                return;
+            this.flashRun = null;
+            this.flashLayer.opacity = 0;
+            this.draw();
+            entry.resolve(false);
+        }, () => entry.superseded);
+    }
+    /**
+     * Ends every Shake and Flash (their `done` resolves false) and keeps the
+     * Fade — opacity, color and any running progress. Called by
+     * `Game.unloadScene()`.
+     */
+    unloadScene() {
+        for (const shake of this.shakes.splice(0))
+            shake.resolve(false);
+        this.offset = { x: 0, y: 0 };
+        this.flashRun?.resolve(false);
+        this.flashRun = null;
+        this.flashLayer.opacity = 0;
+        this.draw();
+    }
+    /** Ends every effect and removes the layers (`Game.dispose()`). */
+    dispose() {
+        this.unloadScene();
+        this.fadeRun?.resolve(false);
+        this.fadeRun = null;
+        this.fadeLayer.color = '#000000';
+        this.fadeLayer.opacity = 0;
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            layer.element?.remove();
+            layer.element = null;
+        }
+    }
+    /** Engine-internal: see advanceCameraEffects. */
+    [ADVANCE]() {
+        this.steps += 1;
+        this.advanceShakes();
+        const fade = this.fadeRun;
+        if (fade) {
+            const t = this.progress(fade);
+            this.fadeLayer.opacity = t >= 1 ? fade.to : fade.from + (fade.to - fade.from) * fade.ease(t);
+            if (t >= 1) {
+                this.fadeRun = null;
+                fade.resolve(true);
+            }
+        }
+        const flash = this.flashRun;
+        if (flash) {
+            const t = this.progress(flash);
+            this.flashLayer.opacity = t >= 1 ? 0 : 1 - flash.ease(t);
+            if (t >= 1) {
+                this.flashRun = null;
+                flash.resolve(true);
+            }
+        }
+        this.draw();
+    }
+    /** Engine-internal: see layoutCameraEffects. */
+    [LAYOUT](rect) {
+        this.rect = { ...rect };
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            if (layer.element)
+                this.place(layer.element);
+        }
+    }
+    /** Normalized progress of a timed effect after the current step: 1 at (and past) its end. */
+    progress(entry) {
+        const elapsed = (this.steps - entry.start) * SIMULATION_STEP;
+        if (elapsed >= entry.seconds - SIMULATION_TIME_EPSILON)
+            return 1;
+        return elapsed / entry.seconds;
+    }
+    advanceShakes() {
+        let amplitude = 0;
+        let seed = 0;
+        for (const shake of [...this.shakes]) {
+            const t = this.progress(shake);
+            if (t >= 1) {
+                this.shakes.splice(this.shakes.indexOf(shake), 1);
+                shake.resolve(true);
+                continue;
+            }
+            const current = shake.intensity * (1 - shake.ease(t));
+            if (current > amplitude) {
+                amplitude = current;
+                seed = shake.start;
+            }
+        }
+        if (amplitude <= 0) {
+            this.offset = { x: 0, y: 0 };
+            return;
+        }
+        const pixel = this.options.pixel();
+        const axis = (index) => {
+            const raw = amplitude * (2 * jitter(seed, this.steps, index) - 1);
+            // Truncating toward zero keeps a snapped offset inside the envelope.
+            const snapped = pixel ? Math.trunc(raw / pixel) * pixel : raw;
+            return snapped + 0;
+        };
+        this.offset = { x: axis(0), y: axis(1) };
+    }
+    /** Mirrors both layers' state onto their elements, mounting them on first need. */
+    draw() {
+        const needed = this.fadeLayer.opacity > 0 || this.flashLayer.opacity > 0;
+        if (needed && !this.fadeLayer.element)
+            this.mount();
+        for (const layer of [this.fadeLayer, this.flashLayer]) {
+            const element = layer.element;
+            if (!element)
+                continue;
+            element.style.backgroundColor = layer.color;
+            element.style.opacity = String(layer.opacity);
+            element.style.display = layer.opacity > 0 ? '' : 'none';
+        }
+    }
+    mount() {
+        const host = this.options.host();
+        if (getComputedStyle(host).position === 'static')
+            host.style.position = 'relative';
+        for (const [layer, name, z] of [
+            [this.fadeLayer, 'fade', FADE_Z],
+            [this.flashLayer, 'flash', FLASH_Z],
+        ]) {
+            const element = document.createElement('div');
+            element.dataset.waicaCameraEffect = name;
+            element.style.position = 'absolute';
+            element.style.pointerEvents = 'none';
+            element.style.zIndex = String(z);
+            element.style.display = 'none';
+            this.place(element);
+            host.append(element);
+            layer.element = element;
+        }
+    }
+    /** Sizes a layer to the game viewport (the whole host until the Game lays it out). */
+    place(element) {
+        const rect = this.rect;
+        if (!rect) {
+            element.style.inset = '0';
+            return;
+        }
+        element.style.inset = '';
+        element.style.left = `${rect.x}px`;
+        element.style.top = `${rect.y}px`;
+        element.style.width = `${rect.width}px`;
+        element.style.height = `${rect.height}px`;
+    }
+    invalid(message) {
+        console.warn(`[waica] cameraEffects.${message}`);
+        return settledHandle(Promise.resolve(false), () => { }, () => false);
+    }
+}
+/**
+ * Engine-internal: advances every Camera Effect by exactly one Simulation
+ * Step. `Game.simulateStep()` calls it right after the scene camera, so
+ * nothing advances while the Game is not simulating. Not re-exported from
+ * the package entry.
+ */
+export function advanceCameraEffects(effects) {
+    effects[ADVANCE]();
+}
+/** Engine-internal: sizes the Fade and Flash layers to the game viewport (`Game.resize()`). */
+export function layoutCameraEffects(effects, rect) {
+    effects[LAYOUT](rect);
+}

package/dist/game-time.d.ts

@@ -1,5 +1,7 @@
 /** The closed set of named Penner curves a Tween can ease through. */
 export type EasingName = 'linear' | 'quadIn' | 'quadOut' | 'quadInOut' | 'cubicIn' | 'cubicOut' | 'cubicInOut' | 'sineInOut';
+/** A resolved easing: normalized progress in, eased progress out. */
+type EasingFn = (t: number) => number;
 /** What `after`/`every`/`tween` hand back: see CA-6. */
 export interface TimerHandle {
     /** Idempotent and silent, even on an already-inactive handle. */
@@ -59,6 +61,8 @@ export interface TweenOptions {
     /** Same as `TimerOptions.scope`: `'session'` survives a scene change, anything else means scene. */
     scope?: 'scene' | 'session';
 }
+/** Engine-internal (not re-exported from the package entry): also resolves Camera Effect easings. */
+export declare function resolveEasing(easing: EasingName | ((t: number) => number) | undefined): EasingFn | null;
 /**
  * Module-private key for the per-step advance pass. Not exported, so
  * `time[ADVANCE]()` cannot be spelled outside this file — `advanceGameTime`

package/dist/game-time.js

@@ -15,7 +15,8 @@ const EASINGS = {
     cubicInOut: (t) => (t < 0.5 ? 4 * t * t * t : 1 - ((-2 * t + 2) ** 3) / 2),
     sineInOut: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
 };
-function resolveEasing(easing) {
+/** Engine-internal (not re-exported from the package entry): also resolves Camera Effect easings. */
+export function resolveEasing(easing) {
     if (easing === undefined)
         return EASINGS.linear;
     if (typeof easing === 'function')

package/dist/game.d.ts

@@ -4,6 +4,7 @@ import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { type SceneCameraJson } from './camera.js';
+import { CameraEffects } from './camera-effects.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
@@ -83,6 +84,11 @@ export declare class Game {
      * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
      */
     readonly assets: AssetLoader;
+    /**
+     * Shake, Fade and Flash, beside `camera` and never written into it
+     * (ADR 0020). A Fade survives `unloadScene()`; a Shake or Flash does not.
+     */
+    readonly cameraEffects: CameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
     /** Registry retained by loadScene for runtime prefab spawning. */

package/dist/game.js

@@ -4,6 +4,7 @@ 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 { advanceCameraEffects, CameraEffects, layoutCameraEffects } from './camera-effects.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
@@ -42,6 +43,11 @@ export class Game {
      * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
      */
     assets;
+    /**
+     * Shake, Fade and Flash, beside `camera` and never written into it
+     * (ADR 0020). A Fade survives `unloadScene()`; a Shake or Flash does not.
+     */
+    cameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
@@ -116,6 +122,11 @@ export class Game {
             // catalog is registered at call time, which outlives every scene.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.cameraEffects = new CameraEffects({
+            host: () => canvas.parentElement ?? document.body,
+            // One screen pixel in world units: the shake snaps to it (never the base).
+            pixel: () => (this.resolution ? this.viewHeight / this.resolution.height : null),
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -173,6 +184,7 @@ export class Game {
         // Scene-scoped timers/tweens die here too (ADR 0017): before entities are
         // destroyed below, so an owner's own destroy() cancellation is a no-op.
         this.time.cancelSceneScoped();
+        this.cameraEffects.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -366,6 +378,7 @@ export class Game {
         this.resizeObserver.disconnect();
         this.ui.dispose();
         this.audio.dispose();
+        this.cameraEffects.dispose();
         // Cancels both scopes, including session-scoped work no entity owns
         // (entity.destroy() below only ever reaches owned work) — ADR 0017.
         this.time.cancelAll();
@@ -478,6 +491,7 @@ export class Game {
         }
         this.dispatchCollisions();
         this.updateSceneCamera(SIMULATION_STEP);
+        advanceCameraEffects(this.cameraEffects);
         this.finishStep();
     }
     /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
@@ -535,15 +549,28 @@ export class Game {
         if (this.renderSort === 'y')
             this.applyYSort();
         this.ui.setActive(this.simulate);
-        anchoredPiecesOf(this.ui).place();
-        if (this.resolution) {
-            // Letterbox bars: clear the whole canvas, then render inside the scissor.
-            this.renderer.setScissorTest(false);
-            this.renderer.setClearColor(0x000000, 1);
-            this.renderer.clear(true, false, false);
-            this.renderer.setScissorTest(true);
+        // 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;
+        this.camera.position.x = x + shake.x;
+        this.camera.position.y = y + shake.y;
+        try {
+            anchoredPiecesOf(this.ui).place();
+            if (this.resolution) {
+                // Letterbox bars: clear the whole canvas, then render inside the scissor.
+                this.renderer.setScissorTest(false);
+                this.renderer.setClearColor(0x000000, 1);
+                this.renderer.clear(true, false, false);
+                this.renderer.setScissorTest(true);
+            }
+            this.renderer.render(this.scene, this.camera);
+        }
+        finally {
+            this.camera.position.x = x;
+            this.camera.position.y = y;
         }
-        this.renderer.render(this.scene, this.camera);
     }
     componentUpdateSchedule(entity) {
         const components = [...entity.components];
@@ -655,5 +682,6 @@ export class Game {
         this.camera.top = halfH;
         this.camera.bottom = -halfH;
         this.camera.updateProjectionMatrix();
+        layoutCameraEffects(this.cameraEffects, gameViewport(w, h, this.resolution));
     }
 }

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { spritePlacement } from './sprite-placement.js';
 export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+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';
@@ -35,7 +37,7 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.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';
 export type { StatValue } from './stats.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export { projectIsometric, screenInputToLogical, unprojectIsometric } from './pr
 export { spritePlacement } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { CameraEffects } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';

package/dist/runtime-bridge.d.ts

@@ -15,9 +15,11 @@ export type RuntimeMode = 'paused' | 'real-time';
  * (ADR 0019) announces that every metadata carries `assets: { pending,
  * loaded, failed }` from `game.assets.status`, so a Run Session can wait
  * for Assets Ready (`pending === 0`) at readiness, after a `scene`
- * operation and before a screenshot.
+ * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
+ * announces that every snapshot carries `camera: { shake, fade, flash }`
+ * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;

package/dist/runtime-bridge.js

@@ -14,9 +14,17 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * (ADR 0019) announces that every metadata carries `assets: { pending,
  * loaded, failed }` from `game.assets.status`, so a Run Session can wait
  * for Assets Ready (`pending === 0`) at readiness, after a `scene`
- * operation and before a screenshot.
+ * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
+ * announces that every snapshot carries `camera: { shake, fade, flash }`
+ * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step', 'assets'];
+export const RUNTIME_BRIDGE_CAPABILITIES = [
+    'click',
+    'scene',
+    'fixed-step',
+    'assets',
+    'camera-effects',
+];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;

package/dist/runtime-inspection.d.ts

@@ -1,4 +1,5 @@
 import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
+import type { CameraEffectsState } from './camera-effects.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
@@ -106,6 +107,13 @@ export interface RuntimeSnapshotUi {
         values: Record<string, StatValue | ProjectionMarker> | ProjectionMarker;
     }>;
 }
+/**
+ * `game.cameraEffects.state` (issue #74 CA-17), beside `time` and `ui`: the
+ * shake offset (world units, added to the camera only while drawing) and
+ * the Fade and Flash layers' `#rrggbb` color and opacity, all from the
+ * last completed Simulation Step. Emitted unconditionally — never filtered.
+ */
+export type RuntimeSnapshotCamera = CameraEffectsState;
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
@@ -115,6 +123,7 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     audio: RuntimeSnapshotAudio;
     time: RuntimeSnapshotTime;
     ui: RuntimeSnapshotUi;
+    camera: RuntimeSnapshotCamera;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;

package/dist/runtime-inspection.js

@@ -272,6 +272,7 @@ export class RuntimeInspector {
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
+            camera: this.game.cameraEffects.state,
         });
     }
     audioSnapshot() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",