@waica/engine 0.12.0 → 0.14.0

package/dist/game.js

@@ -1,15 +1,17 @@
 import * as THREE from 'three';
+import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { collisionOverlap } from './collision-shape.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 { Input } from './input.js';
 import { Pointer } from './pointer.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
 import { RuntimeInspector } from './runtime-inspection.js';
-import { projectIsometric } from './projection.js';
+import { projectIsometric, unprojectIsometric } from './projection.js';
 import { isYSortParticipant, ySortZ } from './render-sort.js';
 import { loadScene, registryEntry, spawnFromJson, } from './scene.js';
 import { Stats } from './stats.js';
@@ -28,6 +30,8 @@ export class Game {
     stats;
     /** The HTML UI layer: presentation-only pieces toggled from code. */
     ui;
+    /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
+    audio;
     /** Registry retained by loadScene for runtime prefab spawning. */
     registry = null;
     paramOverrides = {};
@@ -41,6 +45,14 @@ export class Game {
     resizeObserver;
     updateFns = new Set();
     invalidUpdateCompositions = new WeakMap();
+    /**
+     * componentUpdateSchedule's result for the last composition signature seen
+     * per entity: the resolve (Tarjan SCC + Kahn sort) it's built from is pure
+     * for a fixed composition, so a signature match skips it entirely. Only
+     * ever holds a successful resolution — an invalid composition is never
+     * cached, since invalidUpdateCompositions already dedupes its console.error.
+     */
+    updateScheduleCache = new WeakMap();
     resolution;
     /** The constructor's viewHeight — unloadScene() restores it. */
     baseViewHeight;
@@ -48,7 +60,12 @@ export class Game {
     sceneCamera = null;
     renderSort = null;
     sceneProjection = null;
-    lastTime = 0;
+    /** Timestamp of the last animation frame; null until the loop's first frame seeds it. */
+    lastTime = null;
+    /** Seconds of elapsed time not yet worth a whole Simulation Step (ADR 0014). */
+    stepRemainder = 0;
+    /** Seconds discarded by frame-rate snapping, not yet repaid (round 3 correctness). */
+    snapResidual = 0;
     runtimeBridge = null;
     /** Host-registered scenes by name, resolved by loadSceneByName. Session-scoped. */
     sceneCatalog = null;
@@ -66,6 +83,15 @@ export class Game {
         this.input = new Input(options.bindings);
         this.stats = new Stats(options.stats);
         this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
+        this.audio = new AudioSubsystem({
+            canvas,
+            backend: options.audio,
+            // The catalog registered via registerSceneCatalog, never game.registry:
+            // unloadScene() nulls the latter but leaves the catalog (and its
+            // resolver) untouched, which is exactly what a { scope: 'session' }
+            // music bed needs across a scene swap.
+            resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -119,6 +145,7 @@ export class Game {
      */
     unloadScene() {
         this.ui.unloadScene();
+        this.audio.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -204,7 +231,12 @@ export class Game {
         if (override)
             Object.assign(component, override);
     }
-    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    /**
+     * Registers a function that runs once per Simulation Step, with the step
+     * as its dt (ADR 0014). While the Game is not simulating (the editor's edit
+     * mode) it runs once per render frame instead, so a host can keep drawing
+     * its overlays. Returns the unsubscribe.
+     */
     onUpdate(fn) {
         this.updateFns.add(fn);
         return () => this.updateFns.delete(fn);
@@ -252,8 +284,8 @@ export class Game {
             if (!this.runtimeBridge) {
                 const inspector = new RuntimeInspector(this);
                 this.runtimeBridge = new EngineRuntimeBridge(this.renderer.domElement, activation, {
-                    step: (dt) => this.runFrame(dt),
-                    resume: (frame) => this.resumeRuntime(frame),
+                    step: (onStep) => this.runFrame(1, onStep),
+                    resume: (onStep) => this.resumeRuntime(onStep),
                     pause: () => this.stop(),
                     injectAction: (action, operation) => this.input.injectAction(action, operation),
                     availableActions: () => this.input.availableActions(),
@@ -266,11 +298,13 @@ export class Game {
                     availableScenes: () => this.availableScenes,
                 });
                 activation.register(this.runtimeBridge);
+                this.audio.setSilenced(true);
                 window.addEventListener('pagehide', this.unregisterRuntimeBridge);
             }
             this.renderSurface();
             return;
         }
+        this.resetClock();
         this.renderer.setAnimationLoop((time) => this.tick(time));
     }
     stop() {
@@ -302,64 +336,140 @@ export class Game {
         this.pointer.dispose();
         this.resizeObserver.disconnect();
         this.ui.dispose();
+        this.audio.dispose();
         for (const entity of [...this.entities])
             entity.destroy();
         this.renderer.dispose();
     }
-    resumeRuntime(frame) {
-        let previousTime = null;
-        this.renderer.setAnimationLoop((time) => {
-            const dt = previousTime === null ? 0 : Math.min((time - previousTime) / 1000, 0.1);
-            previousTime = time;
-            frame(dt);
-        });
+    /**
+     * Real-time playback for the Runtime Bridge: the same clock-driven loop
+     * as start(), sharing the accumulator, with `onStep` told after every
+     * Simulation Step so the bridge counts frames exactly as paused stepping
+     * does (CA-7). No wall-clock catch-up: the first frame only seeds the
+     * clock (CA-3).
+     */
+    resumeRuntime(onStep) {
+        this.resetClock();
+        this.renderer.setAnimationLoop((time) => this.tick(time, onStep));
     }
-    tick(time) {
-        // Clamp dt: switching tabs or pausing doesn't fast-forward the simulation.
-        const dt = Math.min((time - this.lastTime) / 1000, 0.1);
+    /** Forgets the clock and any partial step, so the next frame runs no burst. */
+    resetClock() {
+        this.lastTime = null;
+        this.stepRemainder = 0;
+        this.snapResidual = 0;
+    }
+    /**
+     * One animation frame (ADR 0014): the elapsed wall-clock time joins the
+     * retained remainder, and as many whole Simulation Steps as it holds run
+     * — capped, with the excess dropped, so a hitch can neither spiral nor
+     * play in slow motion. Not simulating: no time accrues at all. The
+     * measured duration is frame-rate-snapped first (round 2 correctness) so
+     * sub-millisecond timestamp jitter at an exact cadence like 60 Hz can't
+     * flip the whole-steps floor and judder 0/2/0/2.
+     */
+    tick(time, onStep) {
+        const measured = this.lastTime === null ? 0 : (time - this.lastTime) / 1000;
         this.lastTime = time;
-        this.runFrame(dt);
+        if (!this.simulate) {
+            this.stepRemainder = 0;
+            this.snapResidual = 0;
+            this.runFrame(0);
+            return;
+        }
+        const { elapsed, residual } = snapElapsedToStep(measured, this.snapResidual);
+        this.snapResidual = residual;
+        const { steps, remainder } = consumeSimulationSteps(this.stepRemainder, elapsed);
+        this.stepRemainder = remainder;
+        this.runFrame(steps, onStep);
     }
-    runFrame(dt) {
+    /**
+     * Runs `steps` Simulation Steps back to back, then the once-per-frame
+     * tail: audio activity and placements, the UI overlay and the render
+     * (CA-5). A queued scene swap flushes at the very start of the frame —
+     * loadSceneByName's contract — and again before every step after the
+     * first (CA-4), so two steps in one frame never see the same press
+     * twice or the outgoing scene once too often; a frame that runs zero
+     * steps (round 2 correctness) still flushes, so it never renders/
+     * audio-places the outgoing scene one frame longer than it should.
+     */
+    runFrame(steps, onStep) {
         this.insideFrame = true;
         try {
-            // Flushes a scene swap enqueued mid-frame last time (CA-7): applied
-            // before this frame's own simulation, so the incoming scene's
-            // entities are present only from this next frame onward.
             this.flushPendingSceneLoad();
             if (this.simulate) {
-                for (const entity of [...this.entities]) {
-                    const schedule = this.componentUpdateSchedule(entity);
-                    if (!schedule)
-                        continue;
-                    for (const component of schedule)
-                        component.onUpdate?.(dt);
+                // Re-read every iteration, not just once before the loop: a
+                // component or host callback can set `simulate = false` mid-step,
+                // and the remaining steps of this catch-up frame must not run.
+                for (let index = 0; index < steps && this.simulate; index += 1) {
+                    // Step 0 was just flushed above; only later steps need it again.
+                    if (index > 0)
+                        this.flushPendingSceneLoad();
+                    this.simulateStep();
+                    onStep?.();
                 }
-                this.dispatchCollisions();
-                this.updateSceneCamera(dt);
             }
-            // The UI must react to the pause itself (hide until resumed).
-            this.ui.setActive(this.simulate);
-            for (const fn of this.updateFns)
-                fn(dt);
-            this.input.endFrame();
+            else {
+                // [DEVIATION 2026-09-12] The editor draws its edit-mode overlays from
+                // game.onUpdate with simulate = false (Viewport.tsx), exactly as it
+                // did before the fixed step: a non-simulating frame runs no step but
+                // still hands the host one callback and closes the input frame.
+                this.finishStep();
+            }
+            this.audio.setActive(this.simulate);
+            // Positional audio (CA-8): recomputed every frame, on this same pass —
+            // never a second walk of `this.entities`, since `this.audio` already
+            // holds direct references to whichever entities are tracked.
+            this.audio.updatePlacements(this.audioListenerPosition(), (x, y) => this.renderPoint(x, y));
             this.renderSurface();
         }
         finally {
             this.insideFrame = false;
         }
     }
+    /**
+     * One Simulation Step: 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() {
+        for (const entity of [...this.entities]) {
+            const schedule = this.componentUpdateSchedule(entity);
+            if (!schedule)
+                continue;
+            for (const component of schedule)
+                component.onUpdate?.(SIMULATION_STEP);
+        }
+        this.dispatchCollisions();
+        this.updateSceneCamera(SIMULATION_STEP);
+        this.finishStep();
+    }
+    /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
+    finishStep() {
+        this.runHostUpdates();
+        this.input.endFrame();
+    }
+    runHostUpdates() {
+        for (const fn of this.updateFns)
+            fn(SIMULATION_STEP);
+    }
     flushPendingSceneLoad() {
-        const pending = this.pendingSceneLoad;
-        if (!pending)
-            return;
-        this.pendingSceneLoad = null;
-        pending();
+        // Drains the whole chain, not just one level: a loadSceneByName called
+        // from the incoming scene's onReady (still insideFrame) re-queues
+        // pendingSceneLoad, and a frame that runs zero steps never reaches the
+        // per-step flush that would otherwise pick it up next. Capped like the
+        // state machine's chained-transition loop (MAX_CHAINED_HOPS), so a
+        // degenerate scene cycle can't hang here either.
+        for (let hops = 0; hops < MAX_CHAINED_HOPS && this.pendingSceneLoad; hops += 1) {
+            const pending = this.pendingSceneLoad;
+            this.pendingSceneLoad = null;
+            pending();
+        }
     }
     unregisterRuntimeBridge = () => {
         window.removeEventListener('pagehide', this.unregisterRuntimeBridge);
         this.runtimeBridge?.unregister();
         this.runtimeBridge = null;
+        this.audio.setSilenced(false);
     };
     /** Under y-sort, re-derives every participant's z from layer band + entity Y. */
     applyYSort() {
@@ -399,24 +509,36 @@ export class Game {
     }
     componentUpdateSchedule(entity) {
         const components = [...entity.components];
-        const registry = {
-            ...(this.registry?.components ?? {}),
-        };
         const byName = new Map();
         const names = [];
         const signatureParts = [];
         for (const component of components) {
             const Class = component.constructor;
             const name = Class.componentName;
-            registry[name] = Class;
             names.push(name);
             byName.set(name, component);
             signatureParts.push(`${name}:${typeof Class.prototype.onUpdate === 'function' ? 'updates' : 'passive'}:` +
                 [...new Set(Class.updateAfter ?? [])].sort().join(','));
         }
+        const signature = signatureParts.sort().join('|');
+        // The resolve below (duplicate check + Tarjan SCC + Kahn sort) is pure
+        // for a fixed composition, and this method now runs once per entity per
+        // Simulation Step rather than once per rendered frame: skip it entirely
+        // when nothing about this entity's components changed since last time.
+        const cached = this.updateScheduleCache.get(entity);
+        if (cached && cached.signature === signature) {
+            return cached.order.map((name) => byName.get(name));
+        }
+        const registry = {
+            ...(this.registry?.components ?? {}),
+        };
+        for (const component of components) {
+            const Class = component.constructor;
+            registry[Class.componentName] = Class;
+        }
         const result = resolveComponentUpdateSchedule(names, registry);
         if (!result.ok) {
-            const signature = signatureParts.sort().join('|');
+            this.updateScheduleCache.delete(entity);
             if (this.invalidUpdateCompositions.get(entity) !== signature) {
                 this.invalidUpdateCompositions.set(entity, signature);
                 console.error(`[waica] invalid component update schedule for "${entity.name}": ` +
@@ -425,6 +547,7 @@ export class Game {
             return null;
         }
         this.invalidUpdateCompositions.delete(entity);
+        this.updateScheduleCache.set(entity, { signature, order: result.order });
         return result.order.map((name) => byName.get(name));
     }
     updateSceneCamera(dt) {
@@ -456,6 +579,17 @@ export class Game {
     renderPoint(x, y) {
         return this.sceneProjection === 'isometric' ? projectIsometric(x, y) : { x, y };
     }
+    /**
+     * The audio listener's position (CA-8) in logical coordinates. The camera
+     * itself only ever holds render-space coordinates (see `updateSceneCamera`,
+     * `setSceneCamera`), so under `projection: 'isometric'` this is the exact
+     * inverse of `renderPoint` — without it, distance-based attenuation would
+     * measure render-space distance instead of real game distance.
+     */
+    audioListenerPosition() {
+        const { x, y } = this.camera.position;
+        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++) {

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
+export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
+export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
+export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
@@ -9,6 +13,7 @@ export type { ProjectedPoint } from './projection.js';
 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 type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';
@@ -25,7 +30,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, RuntimeSnapshotFilters, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, 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

@@ -1,9 +1,11 @@
 export { Game } from './game.js';
+export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
 export { projectIsometric, screenInputToLogical, unprojectIsometric } from './projection.js';
 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 { Entity } from './entity.js';
 export { Component } from './component.js';
 export { authoringDefaults } from './authoring-defaults.js';

package/dist/runtime-bridge.d.ts

@@ -9,9 +9,10 @@ export type RuntimeMode = 'paused' | 'real-time';
  * pre-CA-10 engine simply lacks this field, which is exactly what callers
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
- * from one that runs it.
+ * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
+ * advances whole 1/60 s Simulation Steps and takes no `dt`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -25,9 +26,10 @@ export type RuntimeControlRequest = {
     action: string;
 } | {
     operation: 'pause' | 'resume';
-} | {
+}
+/** Advances `frames` whole Simulation Steps (1/60 s each, ADR 0014); default 1. */
+ | {
     operation: 'step';
-    dt?: number;
     frames?: number;
 } | {
     operation: 'click';
@@ -62,8 +64,14 @@ export interface RuntimeBridgeActivation {
 }
 export declare function activeRuntimeBridgeHook(): RuntimeBridgeActivation | null;
 export interface RuntimeBridgeHost {
-    step(dt: number): void;
-    resume(frame: (dt: number) => void): void;
+    /**
+     * Runs exactly one Simulation Step and renders; `onStep` is told only if a
+     * step actually ran (the Game may be non-simulating, in which case this
+     * renders a frame but advances nothing).
+     */
+    step(onStep: () => void): void;
+    /** Starts clock-driven playback; `onStep` is told after every Simulation Step. */
+    resume(onStep: () => void): void;
     pause(): void;
     injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
     availableActions(): string[];
@@ -81,12 +89,13 @@ export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly engineVersion: string;
     private registered;
     private mode;
+    /** Simulation Steps advanced since registration, paused or real-time alike. */
     private frame;
-    private simulationTime;
     constructor(surface: HTMLCanvasElement, activation: RuntimeBridgeActivation, host: RuntimeBridgeHost);
     metadata(): RuntimeMetadata;
     inspect(filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     control(request: RuntimeControlRequest): RuntimeControlResult;
+    /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
     private advance;
     unregister(): void;
 }

package/dist/runtime-bridge.js

@@ -1,4 +1,5 @@
 import enginePackage from '../package.json' with { type: 'json' };
+import { SIMULATION_STEP } from './fixed-step.js';
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
 /**
@@ -8,9 +9,10 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * pre-CA-10 engine simply lacks this field, which is exactly what callers
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
- * from one that runs it.
+ * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
+ * advances whole 1/60 s Simulation Steps and takes no `dt`.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene'];
+export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step'];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
@@ -43,8 +45,8 @@ export class EngineRuntimeBridge {
     engineVersion = enginePackage.version;
     registered = true;
     mode = 'paused';
+    /** Simulation Steps advanced since registration, paused or real-time alike. */
     frame = 0;
-    simulationTime = 0;
     constructor(surface, activation, host) {
         this.surface = surface;
         this.activation = activation;
@@ -56,7 +58,8 @@ export class EngineRuntimeBridge {
             engineVersion: this.engineVersion,
             mode: this.mode,
             frame: this.frame,
-            simulationTime: this.simulationTime,
+            // Derived, never summed: 60 steps are exactly 1 s, with no float drift.
+            simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
         };
     }
@@ -74,7 +77,7 @@ export class EngineRuntimeBridge {
             case 'resume':
                 if (this.mode === 'paused') {
                     this.mode = 'real-time';
-                    this.host.resume((dt) => this.advance(dt));
+                    this.host.resume(() => this.advance());
                 }
                 break;
             case 'press':
@@ -89,16 +92,18 @@ export class EngineRuntimeBridge {
                 if (this.mode !== 'paused') {
                     throw new RuntimeBridgeOperationError('runtime-invalid-state', 'step is only available while the Runtime Bridge is paused.');
                 }
-                const dt = request.dt ?? 1 / 60;
-                const frames = request.frames ?? 1;
-                if (!Number.isFinite(dt) || dt <= 0 || dt > 0.1) {
-                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'dt must be finite and greater than 0 and at most 0.1.');
+                // A caller-chosen dt is rejected outright, never ignored: a pre-ADR-0014
+                // client that still sends one would otherwise believe it stepped by it.
+                if ('dt' in request) {
+                    throw new RuntimeBridgeOperationError('runtime-operation-failed', 'step takes no dt: it advances whole Simulation Steps of 1/60 s each; pass frames (1 through 600) instead.');
                 }
+                const frames = request.frames ?? 1;
                 if (!Number.isInteger(frames) || frames < 1 || frames > 600) {
                     throw new RuntimeBridgeOperationError('runtime-operation-failed', 'frames must be an integer from 1 through 600.');
                 }
-                for (let index = 0; index < frames; index += 1)
-                    this.advance(dt);
+                for (let index = 0; index < frames; index += 1) {
+                    this.host.step(() => this.advance());
+                }
                 break;
             }
             case 'click': {
@@ -122,10 +127,9 @@ export class EngineRuntimeBridge {
         }
         return { ...this.metadata(), heldActions: this.host.heldActions() };
     }
-    advance(dt) {
-        this.host.step(dt);
+    /** Counts one Simulation Step, whoever ran it (paused stepping or real-time playback). */
+    advance() {
         this.frame += 1;
-        this.simulationTime += dt;
     }
     unregister() {
         if (!this.registered)

package/dist/runtime-inspection.d.ts

@@ -1,3 +1,4 @@
+import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
@@ -48,12 +49,29 @@ export interface RuntimeEntitySnapshot {
     transform: RuntimeTransformSnapshot;
     components: RuntimeComponentSnapshot[];
 }
+/**
+ * The mixer's state (CA-15): `master` and every channel's volume/mute,
+ * sorted by name, plus `playing` — `game.audio.liveSounds()` verbatim,
+ * already sorted (by uri then channel). Despite the name, `playing` is not
+ * "every currently-audible sound": per `liveSounds()`'s own docstring it
+ * also carries a loop retained before the autoplay unlock, a sound still
+ * loading, and even one about to fail to load (gone a tick later). Emitted
+ * unconditionally, like every other snapshot section —
+ * `[DEVIATION 2026-09-08]` in the spec: no section of RuntimeSnapshot is
+ * filterable today, so audio does not invent the first one.
+ */
+export interface RuntimeSnapshotAudio {
+    master: number;
+    channels: Record<string, AudioChannelState>;
+    playing: LiveSoundInfo[];
+}
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
     scene: string | null;
     entities: RuntimeEntitySnapshot[];
     projectionIssues: ProjectionIssue[];
+    audio: RuntimeSnapshotAudio;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;
@@ -68,6 +86,7 @@ export declare class RuntimeInspector {
     private nextId;
     constructor(game: Game);
     snapshot(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
+    private audioSnapshot;
     private capSnapshot;
     private idFor;
 }

package/dist/runtime-inspection.js

@@ -237,8 +237,20 @@ export class RuntimeInspector {
             scene: this.game.sceneName,
             entities,
             projectionIssues,
+            audio: this.audioSnapshot(),
         });
     }
+    audioSnapshot() {
+        const channels = {};
+        for (const name of this.game.audio.channels().sort()) {
+            channels[name] = this.game.audio.channelState(name);
+        }
+        return {
+            master: this.game.audio.master,
+            channels,
+            playing: this.game.audio.liveSounds(),
+        };
+    }
     capSnapshot(snapshot) {
         if (utf8Bytes(JSON.stringify(snapshot)) <= RUNTIME_PROJECTION_LIMITS.snapshotBytes) {
             return snapshot;

package/dist/state/state-machine.js

@@ -1,6 +1,7 @@
 import { installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from '../animation/directional.js';
 import { Component } from '../component.js';
 import { AnimatedSprite } from '../components/animated-sprite.js';
+import { MAX_CHAINED_HOPS, SIMULATION_TIME_EPSILON } from '../fixed-step.js';
 import { closestLogicSet, logicSet, registeredLogicSets, } from './hooks.js';
 /** Whether one trigger fires. Unknown or malformed triggers never fire. */
 export function evaluateTrigger(on, env) {
@@ -11,8 +12,15 @@ export function evaluateTrigger(on, env) {
     const arg = on.slice(sep + 1);
     if (kind === 'input')
         return env.justPressed(arg);
+    // A float epsilon of tolerance, not half a Simulation Step: `elapsed` is
+    // a sum of many SIMULATION_STEP-sized dts, and float error can leave it a
+    // hair under an exact multiple (15 additions of 1/60 give
+    // 0.24999999999999997, not 0.25), which a bare `>=` would fire one whole
+    // step late. A tolerance as wide as half a step instead fired non-multiple
+    // durations one whole step early, since a target can sit closer to the
+    // step below than to the one it truly belongs to.
     if (kind === 'timer')
-        return env.elapsed >= Number(arg);
+        return env.elapsed + SIMULATION_TIME_EPSILON >= Number(arg);
     if (kind === 'signal')
         return env.signals.has(arg);
     return false;
@@ -105,7 +113,7 @@ export class StateMachine extends Component {
         this.elapsed += dt;
         // Chained transitions settle within the frame (e.g. land → idle → run),
         // capped so a degenerate cyclic graph can't hang the loop.
-        for (let hops = 0; hops < 8; hops++) {
+        for (let hops = 0; hops < MAX_CHAINED_HOPS; hops++) {
             const edge = nextTransition(this.states, this.current, this.env());
             // A '*' edge is re-merged against whatever state the loop just
             // entered, so a still-queued signal (signals.clear() only runs after

package/package.json

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