@waica/engine 0.11.0 → 0.12.0

package/dist/archetype.d.ts

@@ -22,6 +22,13 @@ export interface ArchetypeManifest {
     id: string;
     label: string;
     scene: SceneJson;
+    /**
+     * Additional demo scenes beyond `scene` (its name is always "main"),
+     * keyed by name — the isometric archetype's second demo scene (CA-13).
+     * `start:blank` never emits these; `start:demo` emits one file per entry
+     * alongside `scene`.
+     */
+    extraScenes?: Readonly<Record<string, SceneJson>>;
     blankScene: SceneJson;
     registry: SceneRegistry;
     palette: EntityTemplate[];

package/dist/component.d.ts

@@ -69,6 +69,11 @@ export declare abstract class Component {
     onCollide?(other: Entity): void;
     /** Runs when this entity's DynamicBody physically contacts a Solid. */
     onContact?(contact: SolidContact): void;
+    /**
+     * Runs when this entity wins the nearest-Interactable scan and the
+     * initiator interacts with it (a keypress or a click-to-move NPC order).
+     */
+    onInteract?(initiator: Entity): void;
     /** Runs when the entity is destroyed or the component removed. */
     onDestroy?(): void;
 }

package/dist/game.d.ts

@@ -5,7 +5,7 @@ import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
-import { type SceneRegistry, type SceneRenderJson } from './scene.js';
+import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
 import { Stats, type StatValue } from './stats.js';
 import { GameUi } from './ui.js';
 /** Fixed game resolution: the view keeps this aspect, letterboxed. */
@@ -32,6 +32,11 @@ export interface SpawnPrefabOptions {
     name?: string;
     position?: [number, number];
 }
+/** The Project's scenes by name (a file's stem), plus the registry shared by all of them. */
+export interface SceneCatalog {
+    scenes: Record<string, SceneJson>;
+    registry: SceneRegistry;
+}
 /** Persisted overrides: entity → componentName → prop → value. */
 export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
 /**
@@ -61,12 +66,22 @@ export declare class Game {
     private readonly updateFns;
     private readonly invalidUpdateCompositions;
     private readonly resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    private readonly baseViewHeight;
     private viewHeight;
     private sceneCamera;
     private renderSort;
     private sceneProjection;
     private lastTime;
     private runtimeBridge;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    private sceneCatalog;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    private liveSceneName;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    private insideFrame;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    private pendingSceneLoad;
     constructor(options: GameOptions);
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
@@ -74,6 +89,35 @@ export declare class Game {
     spawnPrefab(prefab: string, options?: SpawnPrefabOptions): Entity | null;
     /** Finds an entity by name. */
     find(name: string): Entity | undefined;
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    unloadScene(): void;
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog: SceneCatalog): void;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName(): string | null;
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes(): string[];
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name: string): boolean;
     /** Loads persisted parameter overrides (waica.params.json). */
     loadParams(url: string): Promise<void>;
     /** Applies persisted overrides to a freshly added component. */
@@ -104,6 +148,7 @@ export declare class Game {
     private resumeRuntime;
     private tick;
     private runFrame;
+    private flushPendingSceneLoad;
     private unregisterRuntimeBridge;
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     private applyYSort;

package/dist/game.js

@@ -11,7 +11,7 @@ import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.
 import { RuntimeInspector } from './runtime-inspection.js';
 import { projectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
-import { registryEntry, spawnFromJson } from './scene.js';
+import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { Stats } from './stats.js';
 import { GameUi } from './ui.js';
 /**
@@ -42,14 +42,25 @@ export class Game {
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
     resolution;
+    /** The constructor's viewHeight — unloadScene() restores it. */
+    baseViewHeight;
     viewHeight;
     sceneCamera = null;
     renderSort = null;
     sceneProjection = null;
     lastTime = 0;
     runtimeBridge = null;
+    /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
+    sceneCatalog = null;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    liveSceneName = null;
+    /** True for the whole extent of a runFrame() call, incl. its tail. */
+    insideFrame = false;
+    /** A loadSceneByName() enqueued while insideFrame; applied at the next runFrame's start. */
+    pendingSceneLoad = null;
     constructor(options) {
         const { canvas, background = 0x1a1a2e, viewHeight = 10 } = options;
+        this.baseViewHeight = viewHeight;
         this.viewHeight = viewHeight;
         this.resolution = options.resolution ?? null;
         this.input = new Input(options.bindings);
@@ -97,6 +108,84 @@ export class Game {
     find(name) {
         return this.entities.find((e) => e.name === name);
     }
+    /**
+     * Destroys the live scene — every entity (Entity.destroy(), so onDestroy
+     * cascades and GPU resources release) and its scene-scoped UI — and
+     * leaves the Game as newly constructed: no registry, no scene camera, no
+     * render sort or projection, viewHeight back to the constructor's.
+     * Session-scoped state (stats, paramOverrides, subscriptions, the scene
+     * catalog) is untouched. See ADR 0011. Public: the seam `loadScene` calls
+     * to replace a scene, and how a host leaves the Game with none loaded.
+     */
+    unloadScene() {
+        this.ui.unloadScene();
+        // An explicit unload means "no scene": a swap queued earlier this frame
+        // would otherwise flush next frame and resurrect one.
+        this.pendingSceneLoad = null;
+        // Entity.destroy() splices itself out of `this.entities` in place — the
+        // Pointer holds that array by reference, so it must never be reassigned.
+        for (const entity of [...this.entities])
+            entity.destroy();
+        this.registry = null;
+        this.renderSort = null;
+        this.sceneProjection = null;
+        this.sceneCamera = null;
+        this.liveSceneName = null;
+        this.setViewHeight(this.baseViewHeight);
+    }
+    /** Registers the Project's scenes by name, resolved by loadSceneByName. */
+    registerSceneCatalog(catalog) {
+        this.sceneCatalog = catalog;
+    }
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    get sceneName() {
+        return this.liveSceneName;
+    }
+    /** Names registered via registerSceneCatalog, in registration order. */
+    get availableScenes() {
+        return this.sceneCatalog ? Object.keys(this.sceneCatalog.scenes) : [];
+    }
+    /**
+     * Resolves `name` through the registered catalog and loads it, replacing
+     * the live scene. An unknown name warns and leaves the live scene
+     * untouched. Triggered mid-frame (e.g. from a SceneTransition's
+     * onCollide/onInteract) the swap is deferred to the very start of the
+     * next runFrame — dispatchCollisions finishes its double loop over the
+     * outgoing scene, and the incoming scene's entities are present only
+     * from the next frame. Called from outside a frame (boot, or the Runtime
+     * Bridge's `scene` control operation) it applies synchronously and wins
+     * over anything queued earlier this frame. A second mid-frame request
+     * loses to the first and says so. Returns whether the load took effect.
+     */
+    loadSceneByName(name) {
+        const catalog = this.sceneCatalog;
+        const json = catalog ? registryEntry(catalog.scenes, name) : undefined;
+        if (!catalog || !json) {
+            console.warn(`[waica] unknown scene: "${name}"`);
+            return false;
+        }
+        const apply = () => {
+            loadScene(this, json, catalog.registry);
+            this.liveSceneName = name;
+        };
+        if (!this.insideFrame) {
+            // Authoritative: dropping the queue is the point. A swap a transition
+            // enqueued earlier would otherwise flush on the next frame and silently
+            // undo this load, reporting success for a scene the caller never got.
+            this.pendingSceneLoad = null;
+            apply();
+            return true;
+        }
+        if (this.pendingSceneLoad) {
+            // Two transitions resolving in the same collision dispatch: the one the
+            // simulation reached first wins, and the loser is told. Last-write-wins
+            // would drop the player in the other door's destination with no signal.
+            console.warn(`[waica] a scene swap is already queued this frame; ignoring "${name}"`);
+            return false;
+        }
+        this.pendingSceneLoad = apply;
+        return true;
+    }
     /** Loads persisted parameter overrides (waica.params.json). */
     async loadParams(url) {
         try {
@@ -173,6 +262,8 @@ export class Game {
                     click: (x, y) => {
                         this.pointer.injectClick(x, y);
                     },
+                    loadScene: (name) => this.loadSceneByName(name),
+                    availableScenes: () => this.availableScenes,
                 });
                 activation.register(this.runtimeBridge);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
@@ -230,23 +321,40 @@ export class Game {
         this.runFrame(dt);
     }
     runFrame(dt) {
-        if (this.simulate) {
-            for (const entity of [...this.entities]) {
-                const schedule = this.componentUpdateSchedule(entity);
-                if (!schedule)
-                    continue;
-                for (const component of schedule)
-                    component.onUpdate?.(dt);
+        this.insideFrame = true;
+        try {
+            // Flushes a scene swap enqueued mid-frame last time (CA-7): applied
+            // before this frame's own simulation, so the incoming scene's
+            // entities are present only from this next frame onward.
+            this.flushPendingSceneLoad();
+            if (this.simulate) {
+                for (const entity of [...this.entities]) {
+                    const schedule = this.componentUpdateSchedule(entity);
+                    if (!schedule)
+                        continue;
+                    for (const component of schedule)
+                        component.onUpdate?.(dt);
+                }
+                this.dispatchCollisions();
+                this.updateSceneCamera(dt);
             }
-            this.dispatchCollisions();
-            this.updateSceneCamera(dt);
+            // The UI must react to the pause itself (hide until resumed).
+            this.ui.setActive(this.simulate);
+            for (const fn of this.updateFns)
+                fn(dt);
+            this.input.endFrame();
+            this.renderSurface();
         }
-        // The UI must react to the pause itself (hide until resumed).
-        this.ui.setActive(this.simulate);
-        for (const fn of this.updateFns)
-            fn(dt);
-        this.input.endFrame();
-        this.renderSurface();
+        finally {
+            this.insideFrame = false;
+        }
+    }
+    flushPendingSceneLoad() {
+        const pending = this.pendingSceneLoad;
+        if (!pending)
+            return;
+        this.pendingSceneLoad = null;
+        pending();
     }
     unregisterRuntimeBridge = () => {
         window.removeEventListener('pagehide', this.unregisterRuntimeBridge);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Game } from './game.js';
-export type { GameOptions, GameResolution, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';

package/dist/runtime-bridge.d.ts

@@ -11,7 +11,7 @@ export type RuntimeMode = 'paused' | 'real-time';
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -33,6 +33,9 @@ export type RuntimeControlRequest = {
     operation: 'click';
     x: number;
     y: number;
+} | {
+    operation: 'scene';
+    scene: string;
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
@@ -40,8 +43,9 @@ export interface RuntimeControlResult extends RuntimeMetadata {
 export declare class RuntimeBridgeOperationError extends Error {
     readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
     readonly availableActions?: string[] | undefined;
+    readonly availableScenes?: string[] | undefined;
     readonly stage: 'control';
-    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined);
+    constructor(code: 'runtime-invalid-state' | 'runtime-operation-failed', message: string, availableActions?: string[] | undefined, availableScenes?: string[] | undefined);
 }
 /** Engine-owned capability registered only in an MCP-activated page. */
 export interface RuntimeBridge {
@@ -66,6 +70,9 @@ export interface RuntimeBridgeHost {
     heldActions(): string[];
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     click(x: number, y: number): void;
+    /** Resolves `name` through the registered catalog and loads it. */
+    loadScene(name: string): boolean;
+    availableScenes(): string[];
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -10,15 +10,17 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click'];
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
+    availableScenes;
     stage = 'control';
-    constructor(code, message, availableActions) {
+    constructor(code, message, availableActions, availableScenes) {
         super(message);
         this.code = code;
         this.availableActions = availableActions;
+        this.availableScenes = availableScenes;
         this.name = 'RuntimeBridgeOperationError';
     }
 }
@@ -106,6 +108,13 @@ export class EngineRuntimeBridge {
                 this.host.click(request.x, request.y);
                 break;
             }
+            case 'scene': {
+                if (!this.host.loadScene(request.scene)) {
+                    const available = this.host.availableScenes();
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown scene "${request.scene}". Available scenes: ${available.join(', ') || '(none)'}.`, undefined, available);
+                }
+                break;
+            }
             default: {
                 const unsupported = request;
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);

package/dist/runtime-inspection.d.ts

@@ -50,6 +50,8 @@ export interface RuntimeEntitySnapshot {
 }
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
+    /** The live scene's name (its catalog key), or null with no scene loaded. */
+    scene: string | null;
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
 }

package/dist/runtime-inspection.js

@@ -234,6 +234,7 @@ export class RuntimeInspector {
         return this.capSnapshot({
             ...metadata,
             stats: Object.fromEntries([...this.game.stats.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+            scene: this.game.sceneName,
             entities,
             projectionIssues,
         });

package/dist/scene.d.ts

@@ -88,5 +88,9 @@ export declare function resolveProps(props: Record<string, unknown> | undefined,
 export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
 /** Instantiates a scene entity into the game. */
 export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export declare function loadScene(game: Game, scene: SceneJson, registry: SceneRegistry): void;

package/dist/scene.js

@@ -79,8 +79,14 @@ export function spawnFromJson(game, json, registry) {
     }
     return entity;
 }
-/** Loads a full scene into the game. */
+/**
+ * Loads a full scene into the game, replacing whatever scene is already
+ * live (Game.unloadScene() first) — see ADR 0011. A Game shows one scene
+ * at a time.
+ */
 export function loadScene(game, scene, registry) {
+    if (game.registry)
+        game.unloadScene();
     game.registry = registry;
     game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)
@@ -89,6 +95,7 @@ export function loadScene(game, scene, registry) {
     game.setSceneCamera(scene.camera);
     if (registry.ui)
         game.ui.defineAll(registry.ui);
+    // Scene-scoped: Game.unloadScene() unmounts these along with the entities.
     for (const name of scene.ui ?? [])
-        game.ui.show(name);
+        game.ui.show(name, { scope: 'scene' });
 }

package/dist/ui.d.ts

@@ -27,7 +27,7 @@ export declare class GameUi {
     defineAll(pieces: Record<string, string>): void;
     /** Piece names available to show (defined via the registry or define()). */
     names(): string[];
-    show(name: string): void;
+    show(name: string, options?: ShowOptions): void;
     hide(name: string): void;
     toggle(name: string): void;
     isVisible(name: string): boolean;
@@ -41,7 +41,18 @@ export declare class GameUi {
     setActive(active: boolean): void;
     /** Unmounts every piece and removes the overlay (Game.dispose). */
     dispose(): void;
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene(): void;
     private mount;
     private mountOverlay;
     private sync;
 }
+export interface ShowOptions {
+    /** 'scene': unmounted by Game.unloadScene() along with the rest of the scene. */
+    scope?: 'scene';
+}

package/dist/ui.js

@@ -35,10 +35,19 @@ export class GameUi {
     names() {
         return [...this.sources.keys()];
     }
-    show(name) {
+    show(name, options = {}) {
+        const mounted = this.pieces.has(name);
         const piece = this.mount(name);
-        if (piece)
+        if (piece) {
             piece.visible = true;
+            // Scope belongs to whoever mounts the piece, and a later show never
+            // changes it. Otherwise a scene whose `ui` list happens to name a piece
+            // the host already mounted would quietly take ownership of it and
+            // destroy it on the next unload — a session-scoped HUD dying with a
+            // map it merely shares a name with.
+            if (!mounted)
+                piece.scope = options.scope;
+        }
         this.sync();
     }
     hide(name) {
@@ -81,6 +90,23 @@ export class GameUi {
         this.overlay?.remove();
         this.overlay = undefined;
     }
+    /**
+     * Unmounts every scene-scoped piece: the ones `loadScene` showed from the
+     * outgoing scene's `ui` list, plus any shown with `{ scope: 'scene' }`.
+     * A piece the host showed with no scope is untouched. The definition
+     * catalog (sources) always survives — Game.unloadScene.
+     */
+    unloadScene() {
+        for (const [name, piece] of this.pieces) {
+            if (piece.scope !== 'scene')
+                continue;
+            for (const off of piece.unsubs)
+                off();
+            piece.shell.remove();
+            this.pieces.delete(name);
+        }
+        this.sync();
+    }
     mount(name) {
         const existing = this.pieces.get(name);
         if (existing)
@@ -100,7 +126,13 @@ export class GameUi {
         root.style.display = 'contents';
         root.innerHTML = html;
         shadow.append(root);
-        const piece = { shell, root, visible: false, unsubs: bindStats(root, this.stats) };
+        const piece = {
+            shell,
+            root,
+            visible: false,
+            scope: undefined,
+            unsubs: bindStats(root, this.stats),
+        };
         this.mountOverlay().append(shell);
         this.pieces.set(name, piece);
         return piece;

package/package.json

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