@waica/engine 0.16.0 → 0.18.0

package/dist/assets/asset-loader.js

@@ -0,0 +1,138 @@
+import * as THREE from 'three';
+import { ThreeTextureBackend } from './texture-backend.js';
+/**
+ * Not `base.clone()`: `Texture.copy` sets `needsUpdate`, which bumps the
+ * shared Source's version — a GPU re-upload of the same image for every
+ * clone — and, while the image is still missing, makes the renderer warn
+ * on every frame. Sharing the Source and mirroring `version` instead marks
+ * the clone uploadable exactly when the base is, and three then keeps one
+ * GPU texture per (Source, sampler parameters), reference-counted across
+ * clones (WebGLTextures). Colour space is the base's; filters, repeat and
+ * offset are the clone's own.
+ */
+function cloneOf(base) {
+    const clone = new THREE.Texture();
+    clone.source = base.source;
+    clone.colorSpace = base.colorSpace;
+    clone.version = base.version;
+    return clone;
+}
+/**
+ * The engine's texture cache (`game.assets`, ADR 0019): keep-all for the
+ * Game's whole life, keyed by the URL as received, one backend load and one
+ * base texture per URL. `ready()` is the **Assets Ready** signal — a
+ * promise beside the synchronous scene load — and a failed image is
+ * recorded, not thrown, so it never breaks a host or a Run Session that
+ * awaits it. `unloadScene()` never touches this cache; `dispose()` empties it.
+ */
+export class AssetLoader {
+    backend;
+    resolveAsset;
+    entries = new Map();
+    pendingCount = 0;
+    loadedCount = 0;
+    failedCount = 0;
+    constructor(options = {}) {
+        this.backend = options.backend ?? new ThreeTextureBackend();
+        this.resolveAsset = options.resolveAsset ?? ((uri) => uri);
+    }
+    /** A fresh object on every read: `pending` is current, `loaded` and `failed` only grow until `dispose()`. */
+    get status() {
+        return { pending: this.pendingCount, loaded: this.loadedCount, failed: this.failedCount };
+    }
+    /**
+     * The consumer entry (Sprite, AnimatedSprite, Tilemap): requests `url`
+     * — already resolved by `resolveProps` — and returns a clone of its base
+     * right away, so a mesh exists before the image arrives, plus the
+     * settlement of that URL, which also fires on a cache hit.
+     */
+    texture(url) {
+        const entry = this.request(url);
+        const texture = cloneOf(entry.base);
+        if (entry.outcome === null) {
+            // Chained here, before the consumer chains its own continuation on
+            // `settled`, so the clone is uploadable by the time that one runs.
+            void entry.settled.then((outcome) => {
+                if (outcome === 'loaded')
+                    texture.version = entry.base.version;
+            });
+        }
+        return { texture, settled: entry.settled };
+    }
+    /**
+     * Requests every uri ahead of time, each resolved through the registered
+     * scene catalog. Resolves once all of them settled, failures included —
+     * a failure still only warns once, the same as a component's request.
+     */
+    async preload(uris) {
+        await Promise.all(uris.map((uri) => this.request(this.resolveAsset(uri)).settled));
+    }
+    /**
+     * Assets Ready: resolves the first time `pending` is 0 after the call —
+     * at once when nothing is pending, otherwise once every URL requested
+     * before or while waiting has settled. Never rejects. Resolves after the
+     * `settled` continuations consumers chained before the call, so a host
+     * that does `await game.assets.ready()` then `game.start()` renders its
+     * first frame with the textures in place.
+     */
+    async ready() {
+        while (this.pendingCount > 0) {
+            const inFlight = [...this.entries.values()].filter((entry) => entry.outcome === null);
+            await Promise.all(inFlight.map((entry) => entry.settled));
+        }
+    }
+    /** Disposes every cached base exactly once and forgets everything; called by `Game.dispose()`. */
+    dispose() {
+        for (const entry of this.entries.values())
+            entry.base.dispose();
+        this.entries.clear();
+        this.pendingCount = 0;
+        this.loadedCount = 0;
+        this.failedCount = 0;
+    }
+    request(url) {
+        const existing = this.entries.get(url);
+        if (existing)
+            return existing;
+        const base = new THREE.Texture();
+        base.colorSpace = THREE.SRGBColorSpace;
+        const entry = { base, outcome: null, settled: Promise.resolve('failed') };
+        // Registered and counted before the backend runs, so a backend that
+        // throws synchronously still settles this very entry.
+        this.entries.set(url, entry);
+        this.pendingCount += 1;
+        entry.settled = this.load(url, entry);
+        return entry;
+    }
+    async load(url, entry) {
+        const attempt = await this.attempt(url);
+        // A dispose() in flight already forgot this entry and disposed its base:
+        // nothing to write, warn about or count. Only the settlement is still
+        // owed, so a consumer awaiting it never hangs; it reports what the
+        // backend did.
+        if (this.entries.get(url) !== entry)
+            return attempt.outcome;
+        if (attempt.outcome === 'loaded') {
+            // The image lands on the base's Source, which every clone shares.
+            entry.base.image = attempt.texture.image;
+            entry.base.needsUpdate = true;
+            this.loadedCount += 1;
+        }
+        else {
+            console.warn(`[waica] assets: failed to load "${url}"`, attempt.error);
+            this.failedCount += 1;
+        }
+        entry.outcome = attempt.outcome;
+        this.pendingCount -= 1;
+        return attempt.outcome;
+    }
+    /** One backend load as an outcome, never a rejection — a backend that throws synchronously included. */
+    async attempt(url) {
+        try {
+            return { outcome: 'loaded', texture: await this.backend.load(url) };
+        }
+        catch (error) {
+            return { outcome: 'failed', error };
+        }
+    }
+}

package/dist/assets/texture-backend.d.ts

@@ -0,0 +1,17 @@
+import * as THREE from 'three';
+/**
+ * The seam between `game.assets` and the browser (ADR 0013's move, applied
+ * to textures — ADR 0019). `load` resolves once the image behind `url` is
+ * decoded, with a texture whose `image` the loader adopts into its own
+ * cached base; it rejects on a load error and never throws synchronously.
+ * `happy-dom` decodes no images, so a test injects `FakeTextureBackend`
+ * (assets/test-helpers.ts) through `GameOptions.textures`.
+ */
+export interface TextureBackend {
+    load(url: string): Promise<THREE.Texture>;
+}
+/** The real implementation: one `THREE.TextureLoader` per Game, wrapped in a promise. */
+export declare class ThreeTextureBackend implements TextureBackend {
+    private readonly loader;
+    load(url: string): Promise<THREE.Texture>;
+}

package/dist/assets/texture-backend.js

@@ -0,0 +1,15 @@
+import * as THREE from 'three';
+/** The real implementation: one `THREE.TextureLoader` per Game, wrapped in a promise. */
+export class ThreeTextureBackend {
+    loader = new THREE.TextureLoader();
+    load(url) {
+        return new Promise((resolve, reject) => {
+            try {
+                this.loader.load(url, resolve, undefined, reject);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    }
+}

package/dist/component.d.ts

@@ -12,7 +12,7 @@ export interface ParamSpec {
     /** Allowed values for a string param; rendered as a dropdown. Takes precedence over ref. */
     options?: string[];
     /** Project value this string param names; rendered and validated as a typed reference. */
-    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound';
+    ref?: 'prefab' | 'stat' | 'action' | 'clip' | 'sound' | 'ui';
 }
 export interface ComponentClass<T extends Component = Component> {
     new (): T;

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.d.ts

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import { AssetLoader } from './assets/asset-loader.js';
+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';
@@ -38,6 +40,13 @@ export interface GameOptions {
      * first unlock (CA-6), never eagerly here.
      */
     audio?: AudioBackend;
+    /**
+     * Replaces the real `THREE.TextureLoader` implementation behind
+     * `game.assets` (ADR 0013's seam, applied to textures — ADR 0019), mainly
+     * for a project's own tests: `happy-dom` decodes no images. Defaults to
+     * the real backend either way; `game.assets` always exists.
+     */
+    textures?: TextureBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -68,6 +77,12 @@ export declare class Game {
     readonly ui: GameUi;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     readonly audio: AudioSubsystem;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    readonly assets: AssetLoader;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
     /** Registry retained by loadScene for runtime prefab spawning. */
@@ -171,7 +186,7 @@ export declare class Game {
     setSceneCamera(json?: SceneCameraJson): void;
     start(): void;
     stop(): void;
-    /** Internal: called by Entity.destroy(). */
+    /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity: Entity): void;
     /** The scene's render projection; null keeps logical and render space identical. */
     get projection(): 'isometric' | null;

package/dist/game.js

@@ -1,4 +1,6 @@
 import * as THREE from 'three';
+import { gameViewport } from './anchored-pieces.js';
+import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
@@ -16,7 +18,7 @@ import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { createSpatialQuery } from './spatial-query.js';
 import { Stats } from './stats.js';
-import { GameUi } from './ui.js';
+import { anchoredPiecesOf, GameUi } from './ui.js';
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -34,6 +36,12 @@ export class Game {
     ui;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     audio;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    assets;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
@@ -88,6 +96,11 @@ export class Game {
         this.query = createSpatialQuery(this);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
+        anchoredPiecesOf(this.ui).connect(() => ({
+            camera: this.camera,
+            viewport: gameViewport(canvas.clientWidth, canvas.clientHeight, this.resolution),
+            projection: this.sceneProjection,
+        }));
         this.audio = new AudioSubsystem({
             canvas,
             backend: options.audio,
@@ -97,6 +110,12 @@ export class Game {
             // music bed needs across a scene swap.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.assets = new AssetLoader({
+            backend: options.textures,
+            // Same late lookup as audio's: preload() resolves through whatever
+            // catalog is registered at call time, which outlives every scene.
+            resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -304,6 +323,7 @@ export class Game {
                     },
                     loadScene: (name) => this.loadSceneByName(name),
                     availableScenes: () => this.availableScenes,
+                    assets: () => this.assets.status,
                 });
                 activation.register(this.runtimeBridge);
                 this.audio.setSilenced(true);
@@ -318,8 +338,9 @@ export class Game {
     stop() {
         this.renderer.setAnimationLoop(null);
     }
-    /** Internal: called by Entity.destroy(). */
+    /** Internal: called by Entity.destroy(). Its Anchored Pieces go (or freeze) with it. */
     removeEntity(entity) {
+        anchoredPiecesOf(this.ui).release(entity);
         const i = this.entities.indexOf(entity);
         if (i !== -1)
             this.entities.splice(i, 1);
@@ -350,6 +371,9 @@ export class Game {
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        // After the entities: their clones go with the cascade above, the
+        // cached bases go here, exactly once (ADR 0019).
+        this.assets.dispose();
         this.renderer.dispose();
     }
     /**
@@ -511,6 +535,7 @@ 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);

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
+export type { AssetStatus } from './assets/asset-loader.js';
+export type { TextureBackend } from './assets/texture-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
 export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
@@ -32,11 +35,12 @@ 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, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, 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';
 export { GameUi } from './ui.js';
+export type { AnchoredPieceHandle, AttachOptions } from './anchored-pieces.js';
 export { Sprite } from './components/sprite.js';
 export { Solid } from './components/solid.js';
 export { Hitbox } from './components/hitbox.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Game } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';

package/dist/input.d.ts

@@ -24,6 +24,12 @@ export declare class Input {
     justPressed(action: ActionName): boolean;
     /** Installed semantic action names in deterministic order. */
     availableActions(): ActionName[];
+    /**
+     * The key codes bound to the action, in their declared order (e.g.
+     * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
+     * array every call: mutating it never changes the bindings.
+     */
+    bindingsFor(action: ActionName): string[];
     /** Currently held semantic action names in deterministic order. */
     heldActions(): ActionName[];
     /** Injects an action by semantic name; false means the action is not installed. */