@codexo/exojs 0.13.0 → 0.14.0

package/dist/esm/core/Scene.js

@@ -1,4 +1,9 @@
 import { Container } from '../rendering/Container.js';
+import { UIRoot } from '../ui/UIRoot.js';
+import { DisposalScope } from './DisposalScope.js';
+import { serializeTree, migrate, deserializeInto } from './serialization/serialize.js';
+import { SERIALIZATION_VERSION } from './serialization/types.js';
+import { SystemRegistry } from './SystemRegistry.js';
 
 /**
  * Scene-bound input proxy. Bindings created here are automatically unbound
@@ -22,8 +27,7 @@ class SceneInputs {
     onTrigger(channel, callback, options) {
         return this._track(this._scene.app.input.onTrigger(channel, callback, options));
     }
-    /** @internal */
-    _disposeAll() {
+    destroy() {
         for (const binding of this._bindings) {
             binding.unbind();
         }
@@ -54,8 +58,7 @@ class SceneTweens {
         this._tweens.add(tween);
         return this;
     }
-    /** @internal */
-    _disposeAll() {
+    destroy() {
         for (const tween of this._tweens) {
             tween.stop();
         }
@@ -84,9 +87,16 @@ class SceneTweens {
 class Scene {
     _app = null;
     _root = new Container();
-    _stackMode = 'overlay';
+    /**
+     * When `true`, the scene's `update` and systems are skipped each frame while
+     * it keeps drawing — the simple way to freeze gameplay behind a pause menu
+     * (show a panel on `scene.ui`, then set `scene.paused = true`).
+     */
+    paused = false;
     _inputs = null;
     _tweens = null;
+    _systems = null;
+    _disposal = new DisposalScope();
     get app() {
         return this._app;
     }
@@ -121,7 +131,7 @@ class Scene {
             if (this._app === null) {
                 throw new Error('Scene.inputs is unavailable before the scene is attached to an Application.');
             }
-            this._inputs = new SceneInputs(this);
+            this._inputs = this._disposal.track(new SceneInputs(this));
         }
         return this._inputs;
     }
@@ -137,15 +147,62 @@ class Scene {
             if (this._app === null) {
                 throw new Error('Scene.tweens is unavailable before the scene is attached to an Application.');
             }
-            this._tweens = new SceneTweens(this);
+            this._tweens = this._disposal.track(new SceneTweens(this));
         }
         return this._tweens;
     }
-    get stackMode() {
-        return this._stackMode;
+    /**
+     * Register a {@link Destroyable} to be destroyed automatically when this
+     * scene is destroyed (reverse registration order). Returns its argument for
+     * fluent capture: `const world = this.track(new PhysicsWorld())`. The
+     * scene-bound `tweens` and `inputs` registries are tracked the same way.
+     */
+    track(item) {
+        return this._disposal.track(item);
     }
-    set stackMode(mode) {
-        this._stackMode = mode;
+    /**
+     * Scene-bound system registry. Add tickable {@link System}s (e.g. a physics
+     * world) via `this.systems.add(world)`; each is updated once per frame after
+     * {@link Scene.update} (ascending `order`) and destroyed with the scene — no
+     * manual `step()` / `destroy()` wiring. Available before the scene is
+     * attached to an Application (systems tick only while the scene is active).
+     */
+    get systems() {
+        if (this._systems === null) {
+            this._systems = this._disposal.track(new SystemRegistry());
+        }
+        return this._systems;
+    }
+    /** @internal — called by {@link SceneManager} each frame after `update`. */
+    _tickSystems(delta) {
+        this._systems?._tick(delta);
+    }
+    _ui = null;
+    /**
+     * Scene-bound UI layer, rendered screen-fixed on top of the scene content
+     * (after {@link Scene.draw}). Lazily created and destroyed with the scene;
+     * add widgets via `this.ui.addChild(...)`.
+     *
+     * Unlike {@link Scene.root}, the UI layer **is** auto-rendered each frame — a
+     * first-class overlay that always sits above the world. Its children live in
+     * screen space (origin top-left, `0..width` × `0..height`); pointer and
+     * keyboard input route to them ahead of the world layer.
+     */
+    get ui() {
+        if (this._ui === null) {
+            this._ui = this._disposal.track(new UIRoot());
+            // If the scene is already active (its root carries a stage), bind the UI
+            // layer now; otherwise SceneManager attaches it when the scene activates.
+            if (this._root._getStage() !== null) {
+                this._app?.interaction.attachUIRoot(this._ui);
+            }
+        }
+        return this._ui;
+    }
+    /** @internal — the UI layer if materialized, else `null` (no lazy allocation). */
+    // eslint-disable-next-line @typescript-eslint/naming-convention -- UI is an acronym (cf. HTMLText)
+    _peekUI() {
+        return this._ui;
     }
     addChild(child) {
         this._root.addChild(child);
@@ -155,9 +212,43 @@ class Scene {
         this._root.removeChild(child);
         return this;
     }
-    setParticipationPolicy(policy) {
-        if (policy.mode) {
-            this._stackMode = policy.mode;
+    /**
+     * Serialize this scene's structural root subtree to a plain, JSON-able
+     * {@link SerializedScene} descriptor.
+     *
+     * Captures **data, not behaviour**: structure, transforms, visuals and asset
+     * references — never update logic, signal handlers, tweens or systems. When
+     * the scene is attached to an {@link Application}, texture/asset references
+     * resolve to their {@link Loader} source keys. Reattach behaviour in code
+     * after {@link Scene.deserialize}.
+     */
+    serialize() {
+        const loader = this._app?.loader ?? null;
+        const registry = this._app?.serializers;
+        const data = { version: SERIALIZATION_VERSION, root: serializeTree(this._root, loader, registry) };
+        const ui = this._peekUI();
+        if (ui !== null) {
+            data.ui = serializeTree(ui, loader, registry);
+        }
+        return data;
+    }
+    /**
+     * Rebuild this scene's root subtree from a {@link SerializedScene} produced
+     * by {@link Scene.serialize}. Existing root children are removed first, then
+     * the descriptor's children are reconstructed under {@link Scene.root}.
+     *
+     * Assets referenced by the data must already be loaded into the
+     * application's {@link Loader} (pre-load contract). Older documents are
+     * migrated to the current format; documents newer than the running engine
+     * throw. Returns `this`.
+     */
+    deserialize(data) {
+        const migrated = migrate(data);
+        const loader = this._app?.loader ?? null;
+        const registry = this._app?.serializers;
+        deserializeInto(this._root, migrated.root, loader, registry);
+        if (migrated.ui !== undefined) {
+            deserializeInto(this.ui, migrated.ui, loader, registry);
         }
         return this;
     }
@@ -213,10 +304,12 @@ class Scene {
         // override in subclass
     }
     destroy() {
-        this._inputs?._disposeAll();
+        // Destroys everything tracked (scene-bound tweens/inputs + user-tracked
+        // resources) in reverse registration order, then the scene-graph root.
+        this._disposal.destroy();
         this._inputs = null;
-        this._tweens?._disposeAll();
         this._tweens = null;
+        this._systems = null;
         this._root.destroy();
         this._app = null;
     }

package/dist/esm/core/Scene.js.map

@@ -1 +1 @@
-{"version":3,"file":"Scene.js","sources":["../../../../src/core/Scene.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
+{"version":3,"file":"Scene.js","sources":["../../../../src/core/Scene.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/core/SceneManager.d.ts

@@ -1,6 +1,5 @@
 import type { Application } from './Application';
 import { Color } from './Color';
-import type { SceneParticipationPolicy } from './Scene';
 import { Scene } from './Scene';
 import { Signal } from './Signal';
 import type { Time } from './Time';
@@ -21,90 +20,53 @@ export interface SetSceneOptions {
     transition?: SceneTransition;
 }
 /**
- * Options passed to {@link SceneManager.pushScene}. Inherits
- * {@link SceneParticipationPolicy} so the pushed scene's stack mode
- * can be overridden at the call site without subclassing.
- */
-export interface PushSceneOptions extends SceneParticipationPolicy {
-    transition?: SceneTransition;
-}
-/** Options passed to {@link SceneManager.popScene}. */
-export interface PopSceneOptions {
-    transition?: SceneTransition;
-}
-/**
- * Stack-based scene controller owned by {@link Application}. Maintains an
- * ordered stack of {@link Scene} instances, each tagged with its
- * participation policy ({@link SceneStackMode}).
- * Scenes higher on the stack overlay scenes lower; the policy of each
- * scene determines whether scenes below continue to update / render.
- *
- * Use {@link SceneManager.setScene} to replace the entire stack with one
- * scene, {@link SceneManager.pushScene} to overlay a new scene on top, and
- * {@link SceneManager.popScene} to remove the topmost. All three accept an
- * optional fade transition.
+ * Single-active-scene controller owned by {@link Application}. Holds at most one
+ * active {@link Scene} (the current "screen"); {@link SceneManager.setScene}
+ * switches to a new scene — unloading the previous one — with an optional fade
+ * transition.
  *
+ * There is no scene stack: overlays, HUDs and pause menus belong on
+ * {@link Scene.ui} (the screen-fixed UI layer), and "freeze the game but keep
+ * drawing it" is `scene.paused = true` (skips the scene's `update` + systems
+ * while it keeps rendering).
  */
 export declare class SceneManager {
     private readonly _app;
-    private readonly _stack;
+    private _activeScene;
     private readonly _transitionOverlay;
     private _transition;
-    /** Fires whenever the topmost scene changes (push, pop, set, or clear). Payload is the new top, or `null` when the stack becomes empty. */
+    /** Fires whenever the active scene changes (set or clear). Payload is the new scene, or `null` when cleared. */
     readonly onChangeScene: Signal<[Scene | null]>;
-    /** Fires after a scene's `init` resolves and it joins the stack. */
+    /** Fires after a scene's `init` resolves and it becomes active. */
     readonly onStartScene: Signal<[Scene]>;
-    /** Fires once per frame for the topmost scene after its `update` ran. */
+    /** Fires once per frame for the active scene after its `update` ran. */
     readonly onUpdateScene: Signal<[Scene]>;
     /** Fires just before a scene is unloaded (`unload` then `destroy`). */
     readonly onStopScene: Signal<[Scene]>;
     private readonly _asyncUpdateWarned;
     private readonly _asyncDrawWarned;
-    private readonly _updateScratch;
-    private readonly _drawScratch;
     constructor(app: Application);
+    /** The active scene, or `null` when none is set. */
     get currentScene(): Scene | null;
     set currentScene(scene: Scene | null);
-    get scenes(): readonly Scene[];
     /**
-     * Replace the entire scene stack with `scene`, or clear it when `scene`
-     * is `null`. Existing scenes are unloaded in reverse order. If `scene`
-     * is already the topmost, only the scenes underneath are unloaded
-     * (no-op when it is also the only scene).
-     *
-     * Throws if `scene` is somewhere in the stack but not the top.
+     * Switch to `scene` (or clear to `null`), unloading the previously active
+     * scene. No-op when `scene` is already active. An optional fade transition
+     * runs the swap at full opacity. The new scene is loaded before the old one
+     * is torn down, so there is no blank frame between them.
      */
     setScene(scene: Scene | null, options?: SetSceneOptions): Promise<this>;
     /**
-     * Push `scene` onto the stack, leaving any underlying scenes intact.
-     * Resolves once the pushed scene's async `load` + `init` complete.
-     * `options` may override the scene's declared participation policy
-     * (stack mode, input mode) for this particular push.
-     *
-     * Throws if `scene` is already present in the stack.
-     */
-    pushScene(scene: Scene, options?: PushSceneOptions): Promise<this>;
-    /**
-     * Remove the topmost scene from the stack. Resolves once the scene's
-     * `unload` finishes. No-op when the stack is empty.
-     */
-    popScene(options?: PopSceneOptions): Promise<this>;
-    /**
-     * Per-frame entry point called by {@link Application.update}. Advances
-     * any active fade transition, then iterates the stack top-to-bottom
-     * deciding which scenes update and which draw based on each scene's
-     * participation policy (`opaque` covers everything below, `modal`
-     * covers only updates).
+     * Per-frame entry point called by {@link Application.update}. Advances any
+     * active fade transition, then — for the active scene — runs `update` and
+     * ticks its systems (unless {@link Scene.paused}), draws it, and renders its
+     * UI layer on top.
      */
     update(delta: Time): this;
     destroy(): void;
     private _prepareScene;
     private _disposeScene;
-    private _unloadAllScenes;
-    private _unloadCoveredScenes;
-    private _unloadAllScenesOnDestroy;
-    private _resolveParticipationPolicy;
-    private _resolveParticipants;
+    private _unloadActiveSceneOnDestroy;
     private _runWithTransition;
     private _advanceTransition;
     private _executeTransitionAction;

package/dist/esm/core/SceneManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SceneManager.d.ts","sourceRoot":"","sources":["../../../src/core/SceneManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,KAAK,EAAE,wBAAwB,EAAkB,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAWnC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,wBAAwB;IAChE,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAgCD;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA8C;IACjF,OAAO,CAAC,WAAW,CAAqC;IAExD,2IAA2I;IAC3I,SAAgB,aAAa,yBAAgC;IAC7D,oEAAoE;IACpE,SAAgB,YAAY,kBAAyB;IACrD,yEAAyE;IACzE,SAAgB,aAAa,kBAAyB;IACtD,uEAAuE;IACvE,SAAgB,WAAW,kBAAyB;IAEpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;IAEzD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAEzB,GAAG,EAAE,WAAW;IAInC,IAAW,YAAY,IAAI,KAAK,GAAG,IAAI,CAEtC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAE1C;IAED,IAAW,MAAM,IAAI,SAAS,KAAK,EAAE,CAEpC;IAED;;;;;;;OAOG;IACU,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxF;;;;;;;OAOG;IACU,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnF;;;OAGG;IACU,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnE;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI;IA0CzB,OAAO,IAAI,IAAI;YAkBR,aAAa;YA0Cb,aAAa;YAOb,gBAAgB;YAQhB,oBAAoB;YAmBpB,yBAAyB;IAYvC,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,oBAAoB;YA+Bd,kBAAkB;IAiChC,OAAO,CAAC,kBAAkB;YAyBZ,wBAAwB;IA2BtC,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,wBAAwB;CAoBjC"}
+{"version":3,"file":"SceneManager.d.ts","sourceRoot":"","sources":["../../../src/core/SceneManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,yEAAyE;AACzE,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AAgCD;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA8C;IACjF,OAAO,CAAC,WAAW,CAAqC;IAExD,gHAAgH;IAChH,SAAgB,aAAa,yBAAgC;IAC7D,mEAAmE;IACnE,SAAgB,YAAY,kBAAyB;IACrD,wEAAwE;IACxE,SAAgB,aAAa,kBAAyB;IACtD,uEAAuE;IACvE,SAAgB,WAAW,kBAAyB;IAEpD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwB;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAwB;gBAEtC,GAAG,EAAE,WAAW;IAInC,oDAAoD;IACpD,IAAW,YAAY,IAAI,KAAK,GAAG,IAAI,CAEtC;IAED,IAAW,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAE1C;IAED;;;;;OAKG;IACU,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BxF;;;;;OAKG;IACI,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI;IAgDzB,OAAO,IAAI,IAAI;YAkBR,aAAa;YAqDb,aAAa;YAeb,2BAA2B;YAgB3B,kBAAkB;IAiChC,OAAO,CAAC,kBAAkB;YAyBZ,wBAAwB;IA2BtC,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,wBAAwB;CAoBjC"}

package/dist/esm/core/SceneManager.js

@@ -18,152 +18,102 @@ const createOverlayMesh = () => new TransitionOverlayMesh({
 });
 const defaultFadeTransitionDuration = 220;
 /**
- * Stack-based scene controller owned by {@link Application}. Maintains an
- * ordered stack of {@link Scene} instances, each tagged with its
- * participation policy ({@link SceneStackMode}).
- * Scenes higher on the stack overlay scenes lower; the policy of each
- * scene determines whether scenes below continue to update / render.
- *
- * Use {@link SceneManager.setScene} to replace the entire stack with one
- * scene, {@link SceneManager.pushScene} to overlay a new scene on top, and
- * {@link SceneManager.popScene} to remove the topmost. All three accept an
- * optional fade transition.
+ * Single-active-scene controller owned by {@link Application}. Holds at most one
+ * active {@link Scene} (the current "screen"); {@link SceneManager.setScene}
+ * switches to a new scene — unloading the previous one — with an optional fade
+ * transition.
  *
+ * There is no scene stack: overlays, HUDs and pause menus belong on
+ * {@link Scene.ui} (the screen-fixed UI layer), and "freeze the game but keep
+ * drawing it" is `scene.paused = true` (skips the scene's `update` + systems
+ * while it keeps rendering).
  */
 class SceneManager {
     _app;
-    _stack = [];
+    _activeScene = null;
     _transitionOverlay = createOverlayMesh();
     _transition = null;
-    /** Fires whenever the topmost scene changes (push, pop, set, or clear). Payload is the new top, or `null` when the stack becomes empty. */
+    /** Fires whenever the active scene changes (set or clear). Payload is the new scene, or `null` when cleared. */
     onChangeScene = new Signal();
-    /** Fires after a scene's `init` resolves and it joins the stack. */
+    /** Fires after a scene's `init` resolves and it becomes active. */
     onStartScene = new Signal();
-    /** Fires once per frame for the topmost scene after its `update` ran. */
+    /** Fires once per frame for the active scene after its `update` ran. */
     onUpdateScene = new Signal();
     /** Fires just before a scene is unloaded (`unload` then `destroy`). */
     onStopScene = new Signal();
     _asyncUpdateWarned = new WeakSet();
     _asyncDrawWarned = new WeakSet();
-    _updateScratch = [];
-    _drawScratch = [];
     constructor(app) {
         this._app = app;
     }
+    /** The active scene, or `null` when none is set. */
     get currentScene() {
-        return this._stack.at(-1)?.scene ?? null;
+        return this._activeScene;
     }
     set currentScene(scene) {
         void this.setScene(scene);
     }
-    get scenes() {
-        return this._stack.map(entry => entry.scene);
-    }
     /**
-     * Replace the entire scene stack with `scene`, or clear it when `scene`
-     * is `null`. Existing scenes are unloaded in reverse order. If `scene`
-     * is already the topmost, only the scenes underneath are unloaded
-     * (no-op when it is also the only scene).
-     *
-     * Throws if `scene` is somewhere in the stack but not the top.
+     * Switch to `scene` (or clear to `null`), unloading the previously active
+     * scene. No-op when `scene` is already active. An optional fade transition
+     * runs the swap at full opacity. The new scene is loaded before the old one
+     * is torn down, so there is no blank frame between them.
      */
     async setScene(scene, options = {}) {
         await this._runWithTransition(async () => {
-            if (scene === null) {
-                await this._unloadAllScenes();
-                this.onChangeScene.dispatch(null);
-                return;
-            }
-            if (this.currentScene === scene) {
-                if (this._stack.length > 1) {
-                    await this._unloadCoveredScenes();
-                }
+            if (scene === this._activeScene) {
                 return;
             }
-            if (this._stack.some(entry => entry.scene === scene)) {
-                throw new Error('Cannot set a scene that is already present in the scene stack.');
+            if (scene !== null) {
+                await this._prepareScene(scene);
             }
-            const policy = this._resolveParticipationPolicy(scene);
-            await this._prepareScene(scene);
-            await this._unloadAllScenes();
-            this._stack.push({ scene, policy });
-            this.onChangeScene.dispatch(scene);
-            this.onStartScene.dispatch(scene);
-        }, options.transition);
-        return this;
-    }
-    /**
-     * Push `scene` onto the stack, leaving any underlying scenes intact.
-     * Resolves once the pushed scene's async `load` + `init` complete.
-     * `options` may override the scene's declared participation policy
-     * (stack mode, input mode) for this particular push.
-     *
-     * Throws if `scene` is already present in the stack.
-     */
-    async pushScene(scene, options = {}) {
-        await this._runWithTransition(async () => {
-            if (this._stack.some(entry => entry.scene === scene)) {
-                throw new Error('Cannot push a scene instance that is already present in the stack.');
+            const previous = this._activeScene;
+            this._activeScene = scene;
+            if (previous !== null) {
+                await this._disposeScene(previous);
             }
-            const policy = this._resolveParticipationPolicy(scene, options);
-            await this._prepareScene(scene);
-            this._stack.push({ scene, policy });
             this.onChangeScene.dispatch(scene);
-            this.onStartScene.dispatch(scene);
-        }, options.transition);
-        return this;
-    }
-    /**
-     * Remove the topmost scene from the stack. Resolves once the scene's
-     * `unload` finishes. No-op when the stack is empty.
-     */
-    async popScene(options = {}) {
-        await this._runWithTransition(async () => {
-            if (this._stack.length === 0) {
-                return;
+            if (scene !== null) {
+                this.onStartScene.dispatch(scene);
             }
-            const removed = this._stack.at(-1);
-            if (!removed) {
-                return;
-            }
-            await this._disposeScene(removed.scene);
-            this._stack.pop();
-            this.onChangeScene.dispatch(this.currentScene);
         }, options.transition);
         return this;
     }
     /**
-     * Per-frame entry point called by {@link Application.update}. Advances
-     * any active fade transition, then iterates the stack top-to-bottom
-     * deciding which scenes update and which draw based on each scene's
-     * participation policy (`opaque` covers everything below, `modal`
-     * covers only updates).
+     * Per-frame entry point called by {@link Application.update}. Advances any
+     * active fade transition, then — for the active scene — runs `update` and
+     * ticks its systems (unless {@link Scene.paused}), draws it, and renders its
+     * UI layer on top.
      */
     update(delta) {
         this._advanceTransition(delta.milliseconds);
-        this._resolveParticipants();
-        for (const scene of this._updateScratch) {
-            // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
-            const updateResult = scene.update(delta);
-            if (!this._asyncUpdateWarned.has(scene) && updateResult instanceof Promise) {
-                this._asyncUpdateWarned.add(scene);
-                console.warn(`[ExoJS] Scene.update() returned a Promise. update() must be synchronous — async logic here breaks frame timing and silently drops errors. Move async work into load() or init() instead.`);
+        const scene = this._activeScene;
+        if (scene !== null) {
+            if (!scene.paused) {
+                // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+                const updateResult = scene.update(delta);
+                if (!this._asyncUpdateWarned.has(scene) && updateResult instanceof Promise) {
+                    this._asyncUpdateWarned.add(scene);
+                    console.warn(`[ExoJS] Scene.update() returned a Promise. update() must be synchronous — async logic here breaks frame timing and silently drops errors. Move async work into load() or init() instead.`);
+                }
+                // Tick the scene's systems (e.g. a physics world) after its update().
+                scene._tickSystems(delta);
             }
-        }
-        for (const scene of this._drawScratch) {
             // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
             const drawResult = scene.draw(this._app.rendering);
             if (!this._asyncDrawWarned.has(scene) && drawResult instanceof Promise) {
                 this._asyncDrawWarned.add(scene);
                 console.warn(`[ExoJS] Scene.draw() returned a Promise. draw() must be synchronous — an async draw() produces incomplete frames and silently drops errors.`);
             }
+            // Auto-render the scene's screen-fixed UI layer above its content.
+            scene._peekUI()?._render(this._app.rendering);
         }
         const transitionAlpha = this._getTransitionAlpha();
         if (transitionAlpha > 0) {
             this._renderTransitionOverlay(transitionAlpha);
         }
-        if (this.currentScene !== null) {
-            this.onUpdateScene.dispatch(this.currentScene);
+        if (scene !== null) {
+            this.onUpdateScene.dispatch(scene);
         }
         return this;
     }
@@ -174,7 +124,7 @@ class SceneManager {
             transition.color.destroy();
             transition.reject(new Error('SceneManager was destroyed while a transition was active.'));
         }
-        void this._unloadAllScenesOnDestroy();
+        void this._unloadActiveSceneOnDestroy();
         this._transitionOverlay.destroy();
         this.onChangeScene.destroy();
         this.onStartScene.destroy();
@@ -189,6 +139,14 @@ class SceneManager {
             if (scene.root.children.length > 0 && scene.draw === Scene.prototype.draw) {
                 console.warn(`[ExoJS] Scene.root has ${scene.root.children.length} child(ren) after init() but draw() is not overridden. Scene.root is not auto-rendered — call context.render(this.root) inside draw().`);
             }
+            // Bind the scene's root to the app's interaction manager so its nodes
+            // route picking/bounds notifications to this Application (no global).
+            this._app.interaction.attachRoot(scene.root);
+            // Bind the UI layer too, if it was materialized before activation.
+            const ui = scene._peekUI();
+            if (ui !== null) {
+                this._app.interaction.attachUIRoot(ui);
+            }
         }
         catch (error) {
             let cleanupError = null;
@@ -219,69 +177,26 @@ class SceneManager {
     async _disposeScene(scene) {
         this.onStopScene.dispatch(scene);
         await scene.unload(this._app.loader);
+        const ui = scene._peekUI();
+        if (ui !== null) {
+            this._app.interaction.detachUIRoot(ui);
+        }
+        this._app.interaction.detachRoot(scene.root);
         scene.destroy();
         scene.app = null;
     }
-    async _unloadAllScenes() {
-        for (let index = this._stack.length - 1; index >= 0; index--) {
-            await this._disposeScene(this._stack[index].scene);
-        }
-        this._stack.length = 0;
-    }
-    async _unloadCoveredScenes() {
-        if (this._stack.length <= 1) {
+    async _unloadActiveSceneOnDestroy() {
+        const scene = this._activeScene;
+        if (scene === null) {
             return;
         }
-        const activeEntry = this._stack.at(-1);
-        if (!activeEntry) {
-            return;
-        }
-        for (let index = this._stack.length - 2; index >= 0; index--) {
-            await this._disposeScene(this._stack[index].scene);
-        }
-        this._stack.length = 0;
-        this._stack.push(activeEntry);
-    }
-    async _unloadAllScenesOnDestroy() {
-        for (let index = this._stack.length - 1; index >= 0; index--) {
-            try {
-                await this._disposeScene(this._stack[index].scene);
-            }
-            catch (error) {
-                console.error('SceneManager.destroy() failed to unload the active scene.', error);
-            }
+        this._activeScene = null;
+        try {
+            await this._disposeScene(scene);
         }
-        this._stack.length = 0;
-    }
-    _resolveParticipationPolicy(scene, overrides = {}) {
-        const mode = overrides.mode ?? scene.stackMode ?? 'overlay';
-        return { mode };
-    }
-    _resolveParticipants() {
-        const updateScenes = this._updateScratch;
-        const drawScenes = this._drawScratch;
-        updateScenes.length = 0;
-        drawScenes.length = 0;
-        let allowBelowUpdate = true;
-        let allowBelowDraw = true;
-        for (let index = this._stack.length - 1; index >= 0; index--) {
-            const entry = this._stack[index];
-            if (allowBelowUpdate) {
-                updateScenes.push(entry.scene);
-            }
-            if (allowBelowDraw) {
-                drawScenes.push(entry.scene);
-            }
-            if (entry.policy.mode === 'opaque') {
-                allowBelowUpdate = false;
-                allowBelowDraw = false;
-            }
-            else if (entry.policy.mode === 'modal') {
-                allowBelowUpdate = false;
-            }
+        catch (error) {
+            console.error('SceneManager.destroy() failed to unload the active scene.', error);
         }
-        updateScenes.reverse();
-        drawScenes.reverse();
     }
     async _runWithTransition(action, transition) {
         if (transition?.type !== 'fade') {