@waica/engine 0.15.0 → 0.16.0

package/README.md

@@ -170,3 +170,26 @@ class PathFinder extends Component {
 ```
 
 The return value still passes through the bounded safe projector; it is not serialized with arbitrary `toJSON()`. The package root exports the Runtime Snapshot, projection marker, metadata, control and activation types plus `RUNTIME_BRIDGE_PROTOCOL_VERSION` and `RUNTIME_PROJECTION_LIMITS`.
+
+## game.time: simulated timers and tweens
+
+Every `Game` owns a `time: GameTime` service — `after`, `every`, a single-number `tween`, and a `now` reader — advanced only by Simulation Steps (ADR 0014), never by the wall clock:
+
+```ts
+const stun = game.time.after(0.3, () => fsm.goto('idle'), { owner: entity })
+game.time.every(1, () => game.stats.set('clock', game.time.now), { scope: 'session' })
+game.time.tween({
+  from: 0, to: 1, seconds: 0.5, easing: 'quadOut',
+  onUpdate: (v) => { overlay.opacity = v },
+  onComplete: () => game.loadSceneByName('b'),
+  owner: entity,
+})
+stun.remaining // seconds left, counting down
+game.time.now  // seconds of Game Time since the Game started
+```
+
+- **`after(seconds, callback, options?)`** runs `callback` once, `seconds` of Game Time later (0 or a negative duration: the start of the next step). **`every(seconds, callback, options?)`** runs it every `max(seconds, 1/60)`, first one interval after creation, with no drift. **`tween(options)`** carries `from` to `to` over `seconds`, calling `onUpdate(value)` synchronously on creation and again on every later step, finishing with exactly `to` then `onComplete()`. Easing is `'linear'` (default), `'quadIn'`/`'quadOut'`/`'quadInOut'`, `'cubicIn'`/`'cubicOut'`/`'cubicInOut'`, `'sineInOut'`, or a custom `(t) => number`.
+- All three return a `TimerHandle`: `cancel()`, `active`, `elapsed`, `remaining` (seconds of Game Time). `cancel()` — and owner/scene cancellation — leaves a tween's last applied value in place and never calls `onComplete`.
+- **Step placement.** At the start of every Simulation Step, before the Component Update Schedule, `game.time` advances `now`, runs every due timer (due time, then creation order), then advances every tween that existed before that step (creation order). Work a callback creates is never run or advanced in that same step.
+- **Scope.** A timer or tween is scene-scoped by default: `unloadScene()` and every scene load — including a Game's first — cancel it, running no callback. `{ scope: 'session' }` survives a scene change. `{ owner: entity }` cancels it immediately when that entity is destroyed, whatever its scope; an owner already dead at scheduling time yields an inactive handle. `game.dispose()` cancels everything in both scopes. This is the opposite default from `game.onUpdate`/`game.events` (ADR 0011), which survive a scene change by construction, and the same one `game.audio.play()` uses (ADR 0012) — see ADR 0017 for why timers follow audio's rule rather than the host-subscription one: a timer's callback almost always closes over the scene that scheduled it.
+- **No Promises.** Nothing here returns one, and nothing is async — a `.then` continuation is not step-exact (it runs after the whole synchronous frame), which is exactly what `game.time` exists to avoid. Compose delays with `after`, not `await`.

package/dist/entity.js

@@ -55,6 +55,10 @@ export class Entity {
         if (this.destroyed)
             return;
         this.destroyed = true;
+        // Immediately, before any onDestroy hook runs, whatever the scope
+        // (ADR 0017, CA-5) — `alive` is already false by the time any of this
+        // entity's own timers/tweens could observe it.
+        this.game.time.cancelOwnedBy(this);
         for (const c of [...this.components])
             c.onDestroy?.();
         this.components.length = 0;

package/dist/game-time.d.ts

@@ -0,0 +1,189 @@
+/** The closed set of named Penner curves a Tween can ease through. */
+export type EasingName = 'linear' | 'quadIn' | 'quadOut' | 'quadInOut' | 'cubicIn' | 'cubicOut' | 'cubicInOut' | 'sineInOut';
+/** What `after`/`every`/`tween` hand back: see CA-6. */
+export interface TimerHandle {
+    /** Idempotent and silent, even on an already-inactive handle. */
+    cancel(): void;
+    readonly active: boolean;
+    /** Seconds of Game Time, per-kind semantics in CA-6. Frozen once inactive. */
+    readonly elapsed: number;
+    /** Seconds of Game Time until the next due time; 0 once inactive. */
+    readonly remaining: number;
+}
+export interface TimerOptions {
+    /**
+     * Structural, not `instanceof Entity` (spec inference 19) — an object with
+     * a boolean `alive` qualifies, whatever else it is, so behaviors-test stub
+     * entities do too. An owner already dead at scheduling time yields an
+     * inactive handle that never runs, silently (CA-5) — a real Entity's
+     * `destroy()` cancels a live one the same way, whatever its scope.
+     * `alive` is read exactly once, right here at scheduling time; nothing
+     * polls it afterwards. Automatic cancellation of a live handle is driven
+     * entirely by `Entity.destroy()` calling `cancelOwnedBy()`, so an owner
+     * that is not a real `Entity` (never calls `destroy()`) only ever gets
+     * this one dead-at-scheduling check — its handle keeps firing even if
+     * something later flips its `alive` to false by hand.
+     */
+    owner?: {
+        readonly alive: boolean;
+    };
+    /**
+     * `'session'` survives a scene change; anything else — including leaving
+     * it unset — means scene-scoped (ADR 0017), the opposite default from
+     * `game.onUpdate`/`game.events` (ADR 0011). Narrowed to the two literal
+     * values (mirroring `AudioPlayOptions.scope` in `audio/types.ts`) so a
+     * typo is a compile error instead of a silent downgrade to scene scope.
+     */
+    scope?: 'scene' | 'session';
+}
+export interface TweenOptions {
+    from: number;
+    to: number;
+    /** <= 0 (a negative clamped to 0) or below one step: `from` on creation, `to` + onComplete next step. */
+    seconds: number;
+    /** A known name (default `'linear'`) or a custom `(t) => number`. */
+    easing?: EasingName | ((t: number) => number);
+    onUpdate: (value: number) => void;
+    onComplete?: () => void;
+    /**
+     * Structural, not `instanceof Entity` (spec inference 19) — an object with
+     * a boolean `alive` qualifies. `alive` is read once, at scheduling time,
+     * to reject an owner already dead; automatic cancellation afterwards is
+     * driven entirely by `Entity.destroy()` calling `cancelOwnedBy()`, never
+     * by polling `alive` again, so a non-`Entity` owner only ever gets that
+     * one dead-at-scheduling check.
+     */
+    owner?: {
+        readonly alive: boolean;
+    };
+    /** Same as `TimerOptions.scope`: `'session'` survives a scene change, anything else means scene. */
+    scope?: 'scene' | 'session';
+}
+/**
+ * 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.
+ */
+declare const ADVANCE: unique symbol;
+/**
+ * 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 declare class GameTime {
+    private stepCount;
+    private nextId;
+    private timers;
+    private 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.
+     */
+    private timersDirty;
+    private tweensDirty;
+    /** 0 on a new GameTime; `N * SIMULATION_STEP` exactly after N steps — computed, never summed (CA-9). */
+    get now(): number;
+    /** Active timers plus active tweens across both scopes (CA-10). */
+    get pending(): number;
+    /** Smallest positive integer n s.t. n more steps fires/completes something; null when nothing is pending (CA-10). */
+    get nextInSteps(): number | null;
+    /** Shared traversal for `pending`: how many entries in `entries` are active. */
+    private countActive;
+    /** Shared traversal for `nextInSteps`: folds `stepsUntilDue` over every active entry, starting from `min`. */
+    private minStepsUntilDue;
+    /**
+     * 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: number, callback: () => void, options?: TimerOptions): TimerHandle;
+    /**
+     * 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: number, callback: () => void, options?: TimerOptions): TimerHandle;
+    /**
+     * 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: TweenOptions): TimerHandle;
+    /**
+     * 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](): void;
+    /**
+     * 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(): void;
+    /**
+     * 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: {
+        readonly alive: boolean;
+    }): void;
+    /**
+     * Engine-internal by convention, like `Game.removeEntity`: a public
+     * method, not access-controlled, that `Game.dispose()` is expected to
+     * call (CA-4).
+     */
+    cancelAll(): void;
+    /**
+     * 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.
+     */
+    private reclaim;
+    private runDueTimers;
+    private advanceTweens;
+    private deactivate;
+    /** Smallest n >= 1 such that `n` more steps reaches `dueTime`, guarding against float noise near a step boundary. */
+    private stepsUntilDue;
+    private invalid;
+    private handleFor;
+}
+/**
+ * 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 declare function advanceGameTime(time: GameTime): void;
+export {};

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';
@@ -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;
@@ -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

@@ -6,6 +6,7 @@ import { resolveComponentUpdateSchedule } from './component-update-schedule.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';
@@ -33,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 = {};
@@ -148,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;
@@ -339,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();
@@ -429,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)

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)

package/package.json

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