@waica/engine 0.17.0 → 0.19.0

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/components/animated-sprite.d.ts

@@ -6,10 +6,11 @@ import type { YSortParticipant } from '../render-sort.js';
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
  * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
- * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
- * independently. On sheets with explicit cells the frames vary in pixel size,
- * so the quad rescales per frame, anchored bottom-center — width/height size
- * the sheet's largest frame and smaller ones keep their feet planted.
+ * sheet 1 the next n1, …). Each instance owns its own clones of the cached
+ * sheets (game.assets, ADR 0019) to animate UVs independently. On sheets
+ * with explicit cells the frames vary in pixel size, so the quad rescales
+ * per frame, anchored bottom-center — width/height size the sheet's largest
+ * frame and smaller ones keep their feet planted.
  */
 export declare class AnimatedSprite extends Component implements YSortParticipant {
     static componentName: string;
@@ -91,6 +92,7 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     private readonly player;
     private sheets;
     private texs;
+    private readonly failedSheets;
     private mesh?;
     private frame;
     private frameScaleX;
@@ -100,6 +102,17 @@ export declare class AnimatedSprite extends Component implements YSortParticipan
     play(name: string): void;
     onUpdate(dt: number): void;
     onDestroy(): void;
+    /**
+     * The sheet's own clone of the cached base. Non-uniform slicing needs
+     * the image's pixel size, so the current frame is re-applied once the
+     * sheet settles — on a cache hit too, whose settlement is already
+     * resolved — unless this sprite was destroyed meanwhile. A sheet that
+     * fails is remembered so the quad shows its flat material on that
+     * sheet's frames instead of sampling an image that never arrived (CA-4).
+     * An empty url (a sheet not authored yet) owns a bare texture and never
+     * touches game.assets, so it counts nowhere and warns about nothing.
+     */
+    private sheetTexture;
     private showFrame;
     /** Repositions/rescales the displayed frame inside its anchored full-size box. */
     private syncQuad;

package/dist/components/animated-sprite.js

@@ -3,16 +3,16 @@ import { Component } from '../component.js';
 import { ClipPlayer } from '../animation/clip-player.js';
 import { locateFrame, sheetCell } from '../animation/sheet.js';
 import { spritePlacement } from '../sprite-placement.js';
-const loader = new THREE.TextureLoader();
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Sprite animated from one or more spritesheets. The main sheet is the
  * top-level texture/cols/rows (or explicit cells); extraSheets append after
  * it, and clip frames index the sheets consecutively (sheet 0 owns 0..n0-1,
- * sheet 1 the next n1, …). Each instance clones its textures to animate UVs
- * independently. On sheets with explicit cells the frames vary in pixel size,
- * so the quad rescales per frame, anchored bottom-center — width/height size
- * the sheet's largest frame and smaller ones keep their feet planted.
+ * sheet 1 the next n1, …). Each instance owns its own clones of the cached
+ * sheets (game.assets, ADR 0019) to animate UVs independently. On sheets
+ * with explicit cells the frames vary in pixel size, so the quad rescales
+ * per frame, anchored bottom-center — width/height size the sheet's largest
+ * frame and smaller ones keep their feet planted.
  */
 export class AnimatedSprite extends Component {
     static componentName = 'AnimatedSprite';
@@ -30,6 +30,7 @@ export class AnimatedSprite extends Component {
         'player',
         'sheets',
         'texs',
+        'failedSheets',
         'mesh',
         'frame',
         'frameScaleX',
@@ -135,6 +136,8 @@ export class AnimatedSprite extends Component {
     player = new ClipPlayer();
     sheets = [];
     texs = [];
+    // Clones whose sheet failed to load: applyFrame never installs them (CA-4).
+    failedSheets = new Set();
     mesh;
     frame = 0;
     // Current frame's quad scale relative to the sheet's largest cell: always
@@ -157,10 +160,7 @@ export class AnimatedSprite extends Component {
             main.cells = this.cells;
         this.sheets = [main, ...this.extraSheets];
         this.texs = this.sheets.map((sheet) => {
-            // Non-uniform slicing needs the image's pixel size, so re-apply the
-            // current frame once each texture is in.
-            const tex = loader.load(sheet.texture, () => this.applyFrame());
-            tex.colorSpace = THREE.SRGBColorSpace;
+            const tex = this.sheetTexture(sheet.texture);
             if (this.pixelArt) {
                 tex.magFilter = THREE.NearestFilter;
                 tex.minFilter = THREE.NearestFilter;
@@ -195,8 +195,34 @@ export class AnimatedSprite extends Component {
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
         this.mesh?.material.dispose();
+        // Only this sprite's clones: the cached bases live with the Game.
         for (const tex of this.texs)
             tex.dispose();
+        this.texs = [];
+        this.failedSheets.clear();
+    }
+    /**
+     * The sheet's own clone of the cached base. Non-uniform slicing needs
+     * the image's pixel size, so the current frame is re-applied once the
+     * sheet settles — on a cache hit too, whose settlement is already
+     * resolved — unless this sprite was destroyed meanwhile. A sheet that
+     * fails is remembered so the quad shows its flat material on that
+     * sheet's frames instead of sampling an image that never arrived (CA-4).
+     * An empty url (a sheet not authored yet) owns a bare texture and never
+     * touches game.assets, so it counts nowhere and warns about nothing.
+     */
+    sheetTexture(url) {
+        if (!url)
+            return new THREE.Texture();
+        const { texture, settled } = this.game.assets.texture(url);
+        void settled.then((outcome) => {
+            if (!this.texs.includes(texture))
+                return;
+            if (outcome === 'failed')
+                this.failedSheets.add(texture);
+            this.applyFrame();
+        });
+        return texture;
     }
     showFrame(index) {
         this.frame = index;
@@ -227,9 +253,12 @@ export class AnimatedSprite extends Component {
         const tex = this.texs[located.sheet];
         if (!sheet || !tex)
             return;
-        if (this.mesh && this.mesh.material.map !== tex) {
-            this.mesh.material.map = tex;
-            this.mesh.material.needsUpdate = true;
+        if (this.mesh) {
+            const map = this.failedSheets.has(tex) ? null : tex;
+            if (this.mesh.material.map !== map) {
+                this.mesh.material.map = map;
+                this.mesh.material.needsUpdate = true;
+            }
         }
         const cells = sheet.cells;
         if (cells?.length) {

package/dist/components/sprite.d.ts

@@ -69,6 +69,12 @@ export declare class Sprite extends Component implements YSortParticipant {
     private mesh?;
     onReady(): void;
     onDestroy(): void;
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white quad over an empty map. Skipped once the sprite
+     * was destroyed or the clone is no longer this material's map.
+     */
+    private dropFailedTexture;
     private syncQuad;
     private createGeometry;
 }

package/dist/components/sprite.js

@@ -1,7 +1,6 @@
 import * as THREE from 'three';
 import { Component } from '../component.js';
 import { spritePlacement } from '../sprite-placement.js';
-const loader = new THREE.TextureLoader();
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
@@ -109,14 +108,20 @@ export class Sprite extends Component {
     onReady() {
         const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
         if (this.texture) {
-            const tex = loader.load(this.texture);
+            // Its own clone of the cached base (game.assets, ADR 0019): filters
+            // are per clone, colour space comes with the base, and the image lands
+            // on the Source every clone of this URL shares.
+            const { texture, settled } = this.game.assets.texture(this.texture);
             if (this.pixelArt) {
-                tex.magFilter = THREE.NearestFilter;
-                tex.minFilter = THREE.NearestFilter;
+                texture.magFilter = THREE.NearestFilter;
+                texture.minFilter = THREE.NearestFilter;
             }
-            tex.colorSpace = THREE.SRGBColorSpace;
-            material.map = tex;
+            material.map = texture;
             material.color.set(0xffffff);
+            void settled.then((outcome) => {
+                if (outcome === 'failed')
+                    this.dropFailedTexture(texture);
+            });
         }
         this.mesh = new THREE.Mesh(this.createGeometry(), material);
         this.mesh.position.z = this.layer * 0.01;
@@ -126,7 +131,24 @@ export class Sprite extends Component {
     onDestroy() {
         this.mesh?.removeFromParent();
         this.mesh?.geometry.dispose();
+        // Only this sprite's clone: the cached base lives with the Game.
+        this.mesh?.material.map?.dispose();
         this.mesh?.material.dispose();
+        this.mesh = undefined;
+    }
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white quad over an empty map. Skipped once the sprite
+     * was destroyed or the clone is no longer this material's map.
+     */
+    dropFailedTexture(texture) {
+        const material = this.mesh?.material;
+        if (!material || material.map !== texture)
+            return;
+        material.map = null;
+        texture.dispose();
+        material.color.setHex(this.color);
+        material.needsUpdate = true;
     }
     syncQuad() {
         if (!this.mesh)

package/dist/components/tilemap.d.ts

@@ -107,6 +107,12 @@ export declare class Tilemap extends Component implements SolidSource {
     private gridSpec;
     private rebuildMap;
     private rebuildMaterial;
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white map over an empty texture. Only reached while the
+     * failed clone is still the current one (see rebuildMaterial).
+     */
+    private dropFailedTexture;
     private makeMaterial;
     private rebuildGeometry;
     private rebuildSolids;

package/dist/components/tilemap.js

@@ -5,7 +5,6 @@ import { projectIsometric } from '../projection.js';
 import { SOLID_SOURCE_SYMBOL } from '../scene-solids.js';
 import { cellAt as gridCellAt, cellBounds as gridCellBounds, cellIndex as gridCellIndex, } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
-const loader = new THREE.TextureLoader();
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
@@ -212,20 +211,45 @@ export class Tilemap extends Component {
         if (!this.texture)
             return;
         const requested = this.texture;
-        const texture = loader.load(requested, () => {
-            if (this.loadedTexture === texture && this.texture === requested)
+        // Its own clone of the cached base (game.assets, ADR 0019). The image's
+        // pixel size drives the UVs, so the geometry is rebuilt once the texture
+        // settles — on a cache hit too, whose settlement is already resolved —
+        // and a texture that fails is dropped for the flat colour; neither
+        // happens if the texture was replaced or the component destroyed
+        // meanwhile.
+        const { texture, settled } = this.game.assets.texture(requested);
+        void settled.then((outcome) => {
+            if (this.loadedTexture !== texture || this.texture !== requested)
+                return;
+            if (outcome === 'loaded')
                 this.rebuildGeometry();
+            else
+                this.dropFailedTexture();
         });
         if (this.pixelArt) {
             texture.magFilter = THREE.NearestFilter;
             texture.minFilter = THREE.NearestFilter;
         }
-        texture.colorSpace = THREE.SRGBColorSpace;
         this.loadedTexture = texture;
         mesh.material.map = texture;
         mesh.material.color.set(0xffffff);
         mesh.material.needsUpdate = true;
     }
+    /**
+     * CA-4's failure rule: an image that never arrives leaves the flat
+     * `color`, not a white map over an empty texture. Only reached while the
+     * failed clone is still the current one (see rebuildMaterial).
+     */
+    dropFailedTexture() {
+        const mesh = this.mesh;
+        if (!mesh)
+            return;
+        this.loadedTexture?.dispose();
+        this.loadedTexture = undefined;
+        mesh.material.map = null;
+        mesh.material.color.setHex(this.color);
+        mesh.material.needsUpdate = true;
+    }
     makeMaterial() {
         return new THREE.MeshBasicMaterial({
             color: this.color,

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')