@waica/engine 0.14.1 → 0.16.0

package/dist/game-time.js

@@ -0,0 +1,401 @@
+import { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+const INACTIVE_HANDLE = Object.freeze({
+    cancel() { },
+    active: false,
+    elapsed: 0,
+    remaining: 0,
+});
+const EASINGS = {
+    linear: (t) => t,
+    quadIn: (t) => t * t,
+    quadOut: (t) => 1 - (1 - t) * (1 - t),
+    quadInOut: (t) => (t < 0.5 ? 2 * t * t : 1 - ((-2 * t + 2) ** 2) / 2),
+    cubicIn: (t) => t * t * t,
+    cubicOut: (t) => 1 - (1 - t) ** 3,
+    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) {
+    if (easing === undefined)
+        return EASINGS.linear;
+    if (typeof easing === 'function')
+        return easing;
+    return Object.prototype.hasOwnProperty.call(EASINGS, easing) ? EASINGS[easing] : null;
+}
+function isValidOwner(owner) {
+    return (typeof owner === 'object' &&
+        owner !== null &&
+        typeof owner['alive'] === 'boolean');
+}
+/** `'session'` survives a scene change; any other value (including absent) means scene. */
+function normalizeScope(scope) {
+    return scope === 'session' ? 'session' : 'scene';
+}
+/**
+ * Module-private key for the per-step advance pass. Not exported, so
+ * `time[ADVANCE]()` cannot be spelled outside this file — `advanceGameTime`
+ * (below, exported) is the only reachable entry point from project code.
+ */
+const ADVANCE = Symbol('waica.gameTime.advance');
+/**
+ * The `game.time` service (CA-1..CA-9, CA-14): `after`, `every` and `tween`
+ * scheduled against Game Time (`now`), advanced only by Simulation Steps —
+ * never the wall clock, never synchronously, never while paused or not
+ * simulating. Constructible standalone, like `Stats`: a `Game` owns one via
+ * `game.time`, and a behaviors-test stub game can carry its own, advanced by
+ * the same engine-internal hook `Game` uses (`advanceGameTime`, exported
+ * below — not part of this class's documented API).
+ */
+export class GameTime {
+    stepCount = 0;
+    nextId = 0;
+    timers = [];
+    tweens = [];
+    /**
+     * Set whenever a timer/tween goes inactive since the matching array was
+     * last pruned, whether by firing/completing the per-step advance pass or
+     * by a plain `handle.cancel()` from outside it; consumed (and cleared) by
+     * the next `reclaim()` that actually reassigns that array (CA-3 perf: no
+     * reassignment when nothing died). Invariant: a flag is false only when
+     * its array holds no inactive entries — every path that clears a flag
+     * prunes that array first, and every path that deactivates an entry sets
+     * the matching flag. `reclaim()` relies on this to skip a prune safely.
+     */
+    timersDirty = false;
+    tweensDirty = false;
+    /** 0 on a new GameTime; `N * SIMULATION_STEP` exactly after N steps — computed, never summed (CA-9). */
+    get now() {
+        return this.stepCount * SIMULATION_STEP;
+    }
+    /** Active timers plus active tweens across both scopes (CA-10). */
+    get pending() {
+        return this.countActive(this.timers) + this.countActive(this.tweens);
+    }
+    /** Smallest positive integer n s.t. n more steps fires/completes something; null when nothing is pending (CA-10). */
+    get nextInSteps() {
+        return this.minStepsUntilDue(this.tweens, this.minStepsUntilDue(this.timers, null));
+    }
+    /** Shared traversal for `pending`: how many entries in `entries` are active. */
+    countActive(entries) {
+        let count = 0;
+        for (const entry of entries)
+            if (entry.active)
+                count += 1;
+        return count;
+    }
+    /** Shared traversal for `nextInSteps`: folds `stepsUntilDue` over every active entry, starting from `min`. */
+    minStepsUntilDue(entries, min) {
+        for (const entry of entries) {
+            if (!entry.active)
+                continue;
+            const steps = this.stepsUntilDue(entry.dueTime);
+            min = min === null ? steps : Math.min(min, steps);
+        }
+        return min;
+    }
+    /**
+     * Runs `callback` once, `seconds` of Game Time from now (0 or a negative
+     * duration: the start of the next step). Never synchronous (CA-1).
+     */
+    after(seconds, callback, options = {}) {
+        if (!Number.isFinite(seconds))
+            return this.invalid('after(): seconds must be finite');
+        if (typeof callback !== 'function')
+            return this.invalid('after(): callback must be a function');
+        const owner = options.owner;
+        if (owner !== undefined && !isValidOwner(owner)) {
+            return this.invalid('after(): owner must be an object with a boolean "alive" property');
+        }
+        if (owner !== undefined && !owner.alive)
+            return INACTIVE_HANDLE;
+        const effective = Math.max(0, seconds);
+        const startTime = this.now;
+        const entry = {
+            id: this.nextId++,
+            kind: 'after',
+            scope: normalizeScope(options.scope),
+            owner,
+            active: true,
+            referenceStart: startTime,
+            dueTime: startTime + effective,
+            deactivatedAt: null,
+            callback,
+        };
+        this.timers.push(entry);
+        return this.handleFor(entry);
+    }
+    /**
+     * Runs `callback` every `max(seconds, SIMULATION_STEP)` of Game Time,
+     * first one interval after creation, with no drift: each due time is
+     * `start + n * interval`, computed directly rather than by repeated
+     * addition (CA-2).
+     */
+    every(seconds, callback, options = {}) {
+        if (!Number.isFinite(seconds))
+            return this.invalid('every(): seconds must be finite');
+        if (typeof callback !== 'function')
+            return this.invalid('every(): callback must be a function');
+        const owner = options.owner;
+        if (owner !== undefined && !isValidOwner(owner)) {
+            return this.invalid('every(): owner must be an object with a boolean "alive" property');
+        }
+        if (owner !== undefined && !owner.alive)
+            return INACTIVE_HANDLE;
+        const interval = Math.max(seconds, SIMULATION_STEP);
+        const startTime = this.now;
+        const entry = {
+            id: this.nextId++,
+            kind: 'every',
+            scope: normalizeScope(options.scope),
+            owner,
+            active: true,
+            referenceStart: startTime,
+            dueTime: startTime + interval,
+            deactivatedAt: null,
+            callback,
+            startTime,
+            intervalSeconds: interval,
+            occurrence: 1,
+        };
+        this.timers.push(entry);
+        return this.handleFor(entry);
+    }
+    /**
+     * Carries a single number from `from` to `to` over `seconds` of Game
+     * Time, reporting it through `onUpdate` on every step including creation
+     * (synchronous, before this returns — CA-7). Owner already dead, or any
+     * invalid input, skips even that first call.
+     */
+    tween(options) {
+        const { from, to, seconds, onUpdate, onComplete } = options;
+        if (!Number.isFinite(seconds))
+            return this.invalid('tween(): seconds must be finite');
+        if (!Number.isFinite(from))
+            return this.invalid('tween(): from must be finite');
+        if (!Number.isFinite(to))
+            return this.invalid('tween(): to must be finite');
+        if (typeof onUpdate !== 'function')
+            return this.invalid('tween(): onUpdate must be a function');
+        if (onComplete !== undefined && typeof onComplete !== 'function') {
+            return this.invalid('tween(): onComplete must be a function when present');
+        }
+        const ease = resolveEasing(options.easing);
+        if (!ease)
+            return this.invalid('tween(): easing must be a known name or a function');
+        const owner = options.owner;
+        if (owner !== undefined && !isValidOwner(owner)) {
+            return this.invalid('tween(): owner must be an object with a boolean "alive" property');
+        }
+        if (owner !== undefined && !owner.alive)
+            return INACTIVE_HANDLE;
+        const effective = Math.max(0, seconds);
+        const createdAt = this.now;
+        const entry = {
+            id: this.nextId++,
+            kind: 'tween',
+            scope: normalizeScope(options.scope),
+            owner,
+            active: true,
+            referenceStart: createdAt,
+            dueTime: createdAt + effective,
+            deactivatedAt: null,
+            from,
+            to,
+            seconds: effective,
+            ease,
+            onUpdate,
+            onComplete,
+        };
+        // Registers nothing if this throws (CA-7): the entry is only pushed after.
+        onUpdate(from);
+        this.tweens.push(entry);
+        return this.handleFor(entry);
+    }
+    /**
+     * Internal: the start-of-step pass (CA-3) — advances `now`, then runs
+     * every due timer (due time, then creation order), then advances every
+     * tween that existed before this pass (creation order). Reachable only as
+     * `time[ADVANCE]()`, and `ADVANCE` is not exported, so `advanceGameTime()`
+     * (below, exported) is genuinely the only way in from project code. With
+     * nothing scheduled (the common case once a scene settles) this does no
+     * allocation beyond the step count itself; with timers but no tweens, the
+     * tween snapshot and `advanceTweens()` are skipped too.
+     */
+    [ADVANCE]() {
+        this.stepCount += 1;
+        if (this.timers.length === 0 && this.tweens.length === 0)
+            return;
+        if (this.tweens.length === 0) {
+            this.runDueTimers();
+        }
+        else {
+            // Snapshot before any callback runs: a tween a due timer creates
+            // during this pass must not be advanced (or completed) until the
+            // next step. Skipped entirely above when there is nothing to snapshot.
+            const tweens = [...this.tweens];
+            this.runDueTimers();
+            this.advanceTweens(tweens);
+        }
+        this.reclaim();
+    }
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Game.unloadScene()` and every
+     * scene load are expected to call, including the first (CA-4).
+     */
+    cancelSceneScoped() {
+        for (const timer of this.timers)
+            if (timer.scope !== 'session')
+                this.deactivate(timer);
+        for (const tween of this.tweens)
+            if (tween.scope !== 'session')
+                this.deactivate(tween);
+        this.reclaim();
+    }
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Entity.destroy()` (CA-5) is
+     * expected to be the only caller of. Nothing re-reads `owner.alive` on
+     * later steps; a non-`Entity` owner whose `alive` flips without ever
+     * going through a real `destroy()` call never reaches here, so its
+     * timers/tweens keep running (see `TimerOptions.owner`).
+     */
+    cancelOwnedBy(owner) {
+        for (const timer of this.timers)
+            if (timer.owner === owner)
+                this.deactivate(timer);
+        for (const tween of this.tweens)
+            if (tween.owner === owner)
+                this.deactivate(tween);
+        this.reclaim();
+    }
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Game.dispose()` is expected to
+     * call (CA-4).
+     */
+    cancelAll() {
+        for (const timer of this.timers)
+            this.deactivate(timer);
+        for (const tween of this.tweens)
+            this.deactivate(tween);
+        this.reclaim();
+    }
+    /**
+     * Prunes each array only when its dirty flag is set, then clears that
+     * flag — safe because of the invariant documented on `timersDirty`
+     * /`tweensDirty`: a false flag means the array already holds no inactive
+     * entries, so skipping the filter changes no observable behavior. Called
+     * both at the tail of the per-step advance pass and by
+     * `cancelSceneScoped`/`cancelOwnedBy`/`cancelAll`, which are also
+     * reachable with `simulate === false` (e.g. the editor's edit mode
+     * calling `loadScene` on every edit), when no step ever runs to reclaim
+     * otherwise.
+     */
+    reclaim() {
+        if (this.timersDirty) {
+            this.timers = this.timers.filter((timer) => timer.active);
+            this.timersDirty = false;
+        }
+        if (this.tweensDirty) {
+            this.tweens = this.tweens.filter((tween) => tween.active);
+            this.tweensDirty = false;
+        }
+    }
+    runDueTimers() {
+        const due = this.timers.filter((timer) => timer.active && timer.dueTime <= this.now + SIMULATION_TIME_EPSILON);
+        if (due.length === 0)
+            return;
+        if (due.length > 1)
+            due.sort((a, b) => a.dueTime - b.dueTime || a.id - b.id);
+        for (const timer of due) {
+            if (!timer.active)
+                continue; // an earlier callback this same pass may have cancelled it
+            if (timer.kind === 'every') {
+                timer.referenceStart = timer.dueTime;
+                timer.occurrence += 1;
+                timer.dueTime = timer.startTime + timer.occurrence * timer.intervalSeconds;
+            }
+            else {
+                timer.active = false;
+                timer.deactivatedAt = timer.dueTime;
+                this.timersDirty = true;
+            }
+            timer.callback();
+        }
+    }
+    advanceTweens(tweens) {
+        for (const tween of tweens) {
+            if (!tween.active)
+                continue;
+            if (tween.dueTime <= this.now + SIMULATION_TIME_EPSILON) {
+                tween.active = false;
+                tween.deactivatedAt = tween.dueTime;
+                this.tweensDirty = true;
+                tween.onUpdate(tween.to);
+                tween.onComplete?.();
+                continue;
+            }
+            const elapsed = this.now - tween.referenceStart;
+            // Reaching 1 would mean elapsed >= seconds, i.e. now >= dueTime — the
+            // branch above always exits first in that case, so this is never
+            // clamped in practice.
+            const t = elapsed / tween.seconds;
+            tween.onUpdate(tween.from + (tween.to - tween.from) * tween.ease(t));
+        }
+    }
+    deactivate(entry) {
+        if (!entry.active)
+            return;
+        entry.active = false;
+        entry.deactivatedAt = this.now;
+        if (entry.kind === 'tween')
+            this.tweensDirty = true;
+        else
+            this.timersDirty = true;
+    }
+    /** Smallest n >= 1 such that `n` more steps reaches `dueTime`, guarding against float noise near a step boundary. */
+    stepsUntilDue(dueTime) {
+        const raw = (dueTime - this.now) / SIMULATION_STEP;
+        const n = Math.ceil(raw - SIMULATION_TIME_EPSILON / SIMULATION_STEP);
+        return Math.max(1, n);
+    }
+    invalid(message) {
+        console.warn(`[waica] ${message}`);
+        return INACTIVE_HANDLE;
+    }
+    handleFor(entry) {
+        const time = this;
+        return {
+            cancel() {
+                time.deactivate(entry);
+            },
+            get active() {
+                return entry.active;
+            },
+            get elapsed() {
+                const end = entry.deactivatedAt ?? time.now;
+                return Math.max(0, end - entry.referenceStart);
+            },
+            get remaining() {
+                if (!entry.active)
+                    return 0;
+                return Math.max(0, entry.dueTime - time.now);
+            },
+        };
+    }
+}
+/**
+ * Engine-internal: advances `time` by exactly one Simulation Step (CA-3).
+ * `Game.simulateStep()` calls this as its very first statement, so nothing
+ * advances with `simulate === false`, on a zero-step frame, or while the
+ * Runtime Bridge is paused and not stepping. A standalone `GameTime` — a
+ * behaviors-test stub game, or this package's own game-time.test.ts (CA-14)
+ * — must call this the same way. This is the only way in: the pass itself
+ * lives behind the module-private `ADVANCE` symbol key, unreachable from
+ * outside this file, so project code has no `advanceStep()`-shaped method
+ * to call directly and desynchronize Game Time with.
+ */
+export function advanceGameTime(time) {
+    time[ADVANCE]();
+}

package/dist/game.d.ts

@@ -5,6 +5,7 @@ import { type SceneCameraJson } from './camera.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
+import { GameTime } from './game-time.js';
 import { Input, type InputBindings } from './input.js';
 import { Pointer } from './pointer.js';
 import { type SceneJson, type SceneRegistry, type SceneRenderJson } from './scene.js';
@@ -49,7 +50,7 @@ export interface SceneCatalog {
     registry: SceneRegistry;
 }
 /** Persisted overrides: entity → componentName → prop → value. */
-export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string>>>;
+export type ParamOverrides = Record<string, Record<string, Record<string, number | boolean | string | string[]>>>;
 /**
  * Engine core: loop, unified 2D/3D three scene, orthographic camera,
  * entities with components, and input. See DESIGN.md.
@@ -67,6 +68,8 @@ export declare class Game {
     readonly ui: GameUi;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     readonly audio: AudioSubsystem;
+    /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
+    readonly time: GameTime;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry: SceneRegistry | null;
     paramOverrides: ParamOverrides;
@@ -137,8 +140,8 @@ export declare class Game {
      * 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
+     * next runFrame — dispatchCollisions finishes its frozen pair snapshot for
+     * 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
@@ -209,7 +212,8 @@ export declare class Game {
      */
     private runFrame;
     /**
-     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * One Simulation Step: game.time's start-of-step pass (ADR 0017, CA-3)
+     * first, then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */

package/dist/game.js

@@ -1,13 +1,12 @@
 import * as THREE from 'three';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
-import { collisionBody } from './collision-body.js';
-import { collisionOverlap } from './collision-shape.js';
+import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
-import { Hitbox } from './components/hitbox.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
 import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedToStep, } from './fixed-step.js';
+import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
 import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
@@ -35,6 +34,8 @@ export class Game {
     ui;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     audio;
+    /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
+    time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -150,6 +151,9 @@ export class Game {
     unloadScene() {
         this.ui.unloadScene();
         this.audio.unloadScene();
+        // Scene-scoped timers/tweens die here too (ADR 0017): before entities are
+        // destroyed below, so an owner's own destroy() cancellation is a no-op.
+        this.time.cancelSceneScoped();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -181,8 +185,8 @@ export class Game {
      * 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
+     * next runFrame — dispatchCollisions finishes its frozen pair snapshot for
+     * 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
@@ -341,6 +345,9 @@ export class Game {
         this.resizeObserver.disconnect();
         this.ui.dispose();
         this.audio.dispose();
+        // Cancels both scopes, including session-scoped work no entity owns
+        // (entity.destroy() below only ever reaches owned work) — ADR 0017.
+        this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
         this.renderer.dispose();
@@ -431,11 +438,13 @@ export class Game {
         }
     }
     /**
-     * One Simulation Step: the Component Update Schedule (ADR 0004) in full,
+     * One Simulation Step: game.time's start-of-step pass (ADR 0017, CA-3)
+     * first, then the Component Update Schedule (ADR 0004) in full,
      * collisions, the scene camera and the host's callbacks, every one of
      * them handed exactly SIMULATION_STEP (CA-1); then the input frame ends.
      */
     simulateStep() {
+        advanceGameTime(this.time);
         for (const entity of [...this.entities]) {
             const schedule = this.componentUpdateSchedule(entity);
             if (!schedule)
@@ -595,28 +604,7 @@ export class Game {
         return this.sceneProjection === 'isometric' ? unprojectIsometric(x, y) : { x, y };
     }
     dispatchCollisions() {
-        const boxed = this.entities.filter((e) => e.has(Hitbox));
-        for (let i = 0; i < boxed.length; i++) {
-            for (let j = i + 1; j < boxed.length; j++) {
-                const a = boxed[i];
-                const b = boxed[j];
-                if (!a?.alive || !b?.alive)
-                    continue;
-                const ha = a.get(Hitbox);
-                const hb = b.get(Hitbox);
-                if (!ha || !hb)
-                    continue;
-                const hit = collisionOverlap(collisionBody(ha), collisionBody(hb));
-                if (!hit)
-                    continue;
-                for (const c of [...a.components])
-                    c.onCollide?.(b);
-                if (!a.alive || !b.alive)
-                    continue;
-                for (const c of [...b.components])
-                    c.onCollide?.(a);
-            }
-        }
+        dispatchHitboxCollisions(this);
     }
     resize() {
         const canvas = this.renderer.domElement;

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export { spritePlacement } from './sprite-placement.js';
 export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { GameTime, advanceGameTime } from './game-time.js';
+export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game-time.js';
 export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
@@ -30,7 +32,7 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';

package/dist/index.js

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

package/dist/runtime-inspection.d.ts

@@ -65,6 +65,23 @@ export interface RuntimeSnapshotAudio {
     channels: Record<string, AudioChannelState>;
     playing: LiveSoundInfo[];
 }
+/**
+ * `game.time`'s pending work (CA-10), beside `audio`: `pending` counts
+ * active timers plus active tweens across both scopes; `nextInSteps` is the
+ * smallest positive integer n such that `step { frames: n }` makes an
+ * active timer run or an active tween complete, or null when `pending` is
+ * 0. Emitted unconditionally, like `audio` — never filtered, and never
+ * repeats `now` (metadata already carries `simulationTime`). That promise
+ * holds only while the Game is simulating: `runFrame` runs zero steps with
+ * `simulate === false` (`game.ts`), so on a Game that is paused AND not
+ * simulating, `nextInSteps` is still reported but stepping never consumes
+ * it — a Run Session starts with `simulate === true`, so this only matters
+ * if project code flips it.
+ */
+export interface RuntimeSnapshotTime {
+    pending: number;
+    nextInSteps: number | null;
+}
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
@@ -72,6 +89,7 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
     audio: RuntimeSnapshotAudio;
+    time: RuntimeSnapshotTime;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -87,6 +105,7 @@ export declare class RuntimeInspector {
     constructor(game: Game);
     snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     private audioSnapshot;
+    private timeSnapshot;
     private capSnapshot;
     private idFor;
 }

package/dist/runtime-inspection.js

@@ -238,6 +238,7 @@ export class RuntimeInspector {
             entities,
             projectionIssues,
             audio: this.audioSnapshot(),
+            time: this.timeSnapshot(),
         });
     }
     audioSnapshot() {
@@ -251,6 +252,12 @@ export class RuntimeInspector {
             playing: this.game.audio.liveSounds(),
         };
     }
+    timeSnapshot() {
+        return {
+            pending: this.game.time.pending,
+            nextInSteps: this.game.time.nextInSteps,
+        };
+    }
     capSnapshot(snapshot) {
         if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
             return snapshot;

package/dist/scene.js

@@ -85,8 +85,17 @@ export function spawnFromJson(game, json, registry) {
  * at a time.
  */
 export function loadScene(game, scene, registry) {
-    if (game.registry)
+    if (game.registry) {
         game.unloadScene();
+    }
+    else {
+        // unloadScene() would otherwise be skipped on a Game's first load
+        // (F11), leaving a scene-scoped timer/tween created before it — a boot
+        // clock, say — to survive this load and die only at the next one
+        // instead. Cancel that slice of unloadScene()'s work directly; there is
+        // no scene, UI or audio yet for the rest of it to touch (ADR 0017, CA-4).
+        game.time.cancelSceneScoped();
+    }
     game.registry = registry;
     game.setSceneRender(scene.render);
     for (const entityJson of scene.entities)