@vgai/engine 0.5.5 → 0.5.7

package/dist/dev/debug-draw.js

@@ -0,0 +1,73 @@
+import * as THREE from 'three';
+/**
+ * Debug drawing utilities for development.
+ *
+ * Draw lines, spheres, boxes, and arrows for visualizing
+ * physics colliders, raycasts, AI paths, etc.
+ *
+ * All debug objects are added to a dedicated group that can be toggled.
+ */
+export function createDebugDraw(scene) {
+    const group = new THREE.Group();
+    group.name = 'debug-draw';
+    scene.add(group);
+    return {
+        /** Draw a line between two points */
+        line(from, to, color = 0x00ff00) {
+            const geometry = new THREE.BufferGeometry().setFromPoints([from, to]);
+            const material = new THREE.LineBasicMaterial({ color });
+            const line = new THREE.Line(geometry, material);
+            group.add(line);
+            return line;
+        },
+        /** Draw a wireframe sphere at a position */
+        sphere(center, radius = 0.1, color = 0xff0000) {
+            const geo = new THREE.SphereGeometry(radius, 8, 8);
+            const mat = new THREE.MeshBasicMaterial({ color, wireframe: true });
+            const mesh = new THREE.Mesh(geo, mat);
+            mesh.position.copy(center);
+            group.add(mesh);
+            return mesh;
+        },
+        /** Draw a wireframe box */
+        box(center, size, color = 0x00ffff) {
+            const geo = new THREE.BoxGeometry(size.x, size.y, size.z);
+            const mat = new THREE.MeshBasicMaterial({ color, wireframe: true });
+            const mesh = new THREE.Mesh(geo, mat);
+            mesh.position.copy(center);
+            group.add(mesh);
+            return mesh;
+        },
+        /** Draw an arrow (direction indicator) */
+        arrow(origin, direction, length = 1, color = 0xffff00) {
+            // Clone before normalize() — never mutate the caller's vector.
+            const dir = direction.clone().normalize();
+            const arrow = new THREE.ArrowHelper(dir, origin, length, color);
+            group.add(arrow);
+            return arrow;
+        },
+        /** Clear all debug drawings */
+        clear() {
+            while (group.children.length > 0) {
+                const child = group.children[0];
+                group.remove(child);
+                if (child instanceof THREE.Mesh || child instanceof THREE.Line) {
+                    // Mesh, Line and LineSegments all own geometry + material.
+                    child.geometry.dispose();
+                    child.material.dispose();
+                }
+                else if (child instanceof THREE.ArrowHelper) {
+                    // ArrowHelper owns a line + cone; dispose() frees both.
+                    child.dispose();
+                }
+            }
+        },
+        /** Toggle debug draw visibility */
+        set visible(v) {
+            group.visible = v;
+        },
+        get visible() {
+            return group.visible;
+        },
+    };
+}

package/dist/dev/instruments.d.ts

@@ -0,0 +1,133 @@
+/**
+ * THE UNIVERSAL INSTRUMENTS — time scale, pause/frame-step, collider draw and
+ * frame time, furnished by the ENGINE for every game before it has written a
+ * line.
+ *
+ * These are physics of the medium, not genre ontology. Time runs; it can run
+ * slower or stop; a frame can be stepped; colliders can be drawn; frames take
+ * time. None of that is a decision any particular game makes, so none of it
+ * belongs in a game's own declarations — and none of it belongs on the game's
+ * own dev panel either, which shows ONLY what the game itself declared
+ * (`stat()`, `cheat()`). They publish as DOORS: an agent drives them through
+ * `game.state()`/`game.command()`, and a human drives the same controls from
+ * the editor chrome that already owns them — pause and frame-step on the
+ * transport, frame time on the stats overlay, colliders in the play-adopted
+ * Scene viewport.
+ *
+ * WHAT IS NOT HERE, and why: a FREE CAMERA. The editor already ships one
+ * (owner, 2026-08-10): play adoption swaps the live game scene into the editor
+ * viewport (`enterPlayScene`), so the Scene view during play IS a free orbit
+ * camera over the running game — no game-side camera override needed, and the
+ * game's own camera writes never fight it because the game keeps rendering
+ * through its own canvas untouched. Per the non-redundancy rule that governs
+ * this list, a control the editor's own chrome furnishes gets no instrument;
+ * agents reach that camera through the editor half of `vgai eval`, not the
+ * game registry.
+ *
+ * ── THE DOOR ────────────────────────────────────────────────────────────────
+ * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-menu
+ * capability's own registry adopts this list (`installDevMenuInstruments`) and
+ * publishes each instrument through the SAME door every declaration in that
+ * capability uses — one provider per reading (`instrument.timescale`), one
+ * command per action (`instrument.timescale.set`), plus the `dev-menu` index
+ * provider. That is deliberate and load-bearing: the registry IS the product,
+ * so every reader of an instrument reaches the SAME registration.
+ *
+ * ── DEGRADING ───────────────────────────────────────────────────────────────
+ * An instrument whose subject this game does not have (no physics adapter ⇒ no
+ * colliders) READS `null` — honest emptiness rather than a fabricated value.
+ * Its ACTION, invoked anyway, THROWS and names what is missing. Silence is the
+ * one thing forbidden: an agent that calls `instrument.colliders.toggle` and
+ * gets `undefined` back learns nothing.
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * {@link createDevInstruments} owns everything it allocates: the frame-time
+ * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
+ * dev-menu capability's `DevMenuBridge`, which creates one set per mounted
+ * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
+ * that ends it. Nothing else here holds a resource; the time-scale, pause and
+ * collider instruments only drive state that `Game` already owns.
+ */
+import { z } from 'zod';
+import type { Game } from '../runtime/game';
+/** What shape an instrument's reading is, and what drives it. Data, not
+ *  layout: a reader learns how to interpret and actuate an instrument without
+ *  having to recognise it by name. */
+export type DevInstrumentControl = 
+/** A value only. */
+{
+    readonly kind: 'reading';
+}
+/** On/off, driven by the named action. */
+ | {
+    readonly kind: 'toggle';
+    readonly action: string;
+}
+/** A continuous value, driven by the named action (one numeric argument). */
+ | {
+    readonly kind: 'scale';
+    readonly action: string;
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+}
+/** A {@link FrameTimeReading} — a window of samples, not a scalar. */
+ | {
+    readonly kind: 'plot';
+};
+/** One instrument verb. Every action declares an args tuple — `z.tuple([])`
+ *  for a verb that takes none — so the debug registry REJECTS an unexpected
+ *  argument at the door instead of passing it through to a handler that
+ *  ignores it. */
+export interface DevInstrumentAction {
+    /** Second half of the command name: `instrument.<id>.<this>`. */
+    readonly id: string;
+    readonly label: string;
+    readonly hint: string;
+    readonly args: z.ZodTuple;
+    run(values: readonly unknown[]): unknown;
+}
+export interface DevInstrument {
+    /** Second half of the provider name: `instrument.<this>`. */
+    readonly id: string;
+    readonly label: string;
+    readonly hint: string;
+    /** Trailing unit for a scalar reading (`x`, `ms`). */
+    readonly unit?: string;
+    readonly control: DevInstrumentControl;
+    readonly actions: readonly DevInstrumentAction[];
+    /** This instant's value, or `null` when this game has no such subject. */
+    read(): unknown;
+}
+export interface DevInstrumentSet {
+    readonly instruments: readonly DevInstrument[];
+    /** See the ownership note above — the ONE teardown path. */
+    dispose(): void;
+}
+/**
+ * How many display frames the frame-time reading keeps. ~1 second at 60 Hz —
+ * long enough that a hitch is still in the window when you look, short enough
+ * that the mean tracks what the game is doing NOW.
+ */
+export declare const FRAME_TIME_WINDOW = 60;
+/** What `instrument.frame-time` reads. `null`s (rather than zeros) before the
+ *  first sampled frame: a stopped game has no frame time, and `0 ms / 0 fps`
+ *  would read as a measurement. */
+export interface FrameTimeReading {
+    /** Mean wall-clock milliseconds per display frame over the window. */
+    readonly ms: number | null;
+    /** Frames per second implied by {@link ms}. */
+    readonly fps: number | null;
+    /** The worst single frame in the window — the hitch the mean hides. */
+    readonly worstMs: number | null;
+    /** Oldest first, for the plot. */
+    readonly samples: readonly number[];
+}
+/** Pure: the whole frame-time reading from a window of samples. */
+export declare function summarizeFrameTimes(samples: readonly number[]): FrameTimeReading;
+/**
+ * Build this game's universal instrument set. One call per mounted game; the
+ * caller owns the returned {@link DevInstrumentSet.dispose}.
+ */
+export declare function createDevInstruments(game: Game): DevInstrumentSet;
+//# sourceMappingURL=instruments.d.ts.map

package/dist/dev/instruments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruments.d.ts","sourceRoot":"","sources":["../../src/dev/instruments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;sCAEsC;AACtC,MAAM,MAAM,oBAAoB;AAC9B,oBAAoB;AAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,0CAA0C;GACxC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACtD,6EAA6E;GAC3E;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACH,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9B;;;kBAGkB;AAClB,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC1B,GAAG,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACjD,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,4DAA4D;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC;;mCAEmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAehF;AAcD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,gBAAgB,CAwIjE"}

package/dist/dev/instruments.js

@@ -0,0 +1,231 @@
+/**
+ * THE UNIVERSAL INSTRUMENTS — time scale, pause/frame-step, collider draw and
+ * frame time, furnished by the ENGINE for every game before it has written a
+ * line.
+ *
+ * These are physics of the medium, not genre ontology. Time runs; it can run
+ * slower or stop; a frame can be stepped; colliders can be drawn; frames take
+ * time. None of that is a decision any particular game makes, so none of it
+ * belongs in a game's own declarations — and none of it belongs on the game's
+ * own dev panel either, which shows ONLY what the game itself declared
+ * (`stat()`, `cheat()`). They publish as DOORS: an agent drives them through
+ * `game.state()`/`game.command()`, and a human drives the same controls from
+ * the editor chrome that already owns them — pause and frame-step on the
+ * transport, frame time on the stats overlay, colliders in the play-adopted
+ * Scene viewport.
+ *
+ * WHAT IS NOT HERE, and why: a FREE CAMERA. The editor already ships one
+ * (owner, 2026-08-10): play adoption swaps the live game scene into the editor
+ * viewport (`enterPlayScene`), so the Scene view during play IS a free orbit
+ * camera over the running game — no game-side camera override needed, and the
+ * game's own camera writes never fight it because the game keeps rendering
+ * through its own canvas untouched. Per the non-redundancy rule that governs
+ * this list, a control the editor's own chrome furnishes gets no instrument;
+ * agents reach that camera through the editor half of `vgai eval`, not the
+ * game registry.
+ *
+ * ── THE DOOR ────────────────────────────────────────────────────────────────
+ * This module is IMPLEMENTATION ONLY. It publishes nothing itself: the dev-menu
+ * capability's own registry adopts this list (`installDevMenuInstruments`) and
+ * publishes each instrument through the SAME door every declaration in that
+ * capability uses — one provider per reading (`instrument.timescale`), one
+ * command per action (`instrument.timescale.set`), plus the `dev-menu` index
+ * provider. That is deliberate and load-bearing: the registry IS the product,
+ * so every reader of an instrument reaches the SAME registration.
+ *
+ * ── DEGRADING ───────────────────────────────────────────────────────────────
+ * An instrument whose subject this game does not have (no physics adapter ⇒ no
+ * colliders) READS `null` — honest emptiness rather than a fabricated value.
+ * Its ACTION, invoked anyway, THROWS and names what is missing. Silence is the
+ * one thing forbidden: an agent that calls `instrument.colliders.toggle` and
+ * gets `undefined` back learns nothing.
+ *
+ * ── RESOURCE OWNERSHIP, STATED ONCE ─────────────────────────────────────────
+ * {@link createDevInstruments} owns everything it allocates: the frame-time
+ * ring buffer and its ONE `game.onRenderStep` subscription. SHARER: the
+ * dev-menu capability's `DevMenuBridge`, which creates one set per mounted
+ * game. TEARDOWN: the returned {@link DevInstrumentSet.dispose} — the ONE path
+ * that ends it. Nothing else here holds a resource; the time-scale, pause and
+ * collider instruments only drive state that `Game` already owns.
+ */
+import { z } from 'zod';
+import { clampTimeScale, TIME_SCALE_RANGE } from '../core/frame-pacing';
+/**
+ * How many display frames the frame-time reading keeps. ~1 second at 60 Hz —
+ * long enough that a hitch is still in the window when you look, short enough
+ * that the mean tracks what the game is doing NOW.
+ */
+export const FRAME_TIME_WINDOW = 60;
+/** Pure: the whole frame-time reading from a window of samples. */
+export function summarizeFrameTimes(samples) {
+    if (samples.length === 0)
+        return { ms: null, fps: null, worstMs: null, samples: [] };
+    let total = 0;
+    let worst = 0;
+    for (const sample of samples) {
+        total += sample;
+        if (sample > worst)
+            worst = sample;
+    }
+    const ms = total / samples.length;
+    return {
+        ms: round(ms, 2),
+        fps: ms > 0 ? round(1000 / ms, 1) : null,
+        worstMs: round(worst, 2),
+        samples: samples.map((sample) => round(sample, 2)),
+    };
+}
+function round(value, places) {
+    const factor = 10 ** places;
+    return Math.round(value * factor) / factor;
+}
+const NO_COLLIDERS = 'No physics adapter on this game implements setDebugDrawEnabled, so nothing can draw its ' +
+    'colliders. A first-party three root with Rapier physics registers one; a game with no ' +
+    'physics has no colliders to draw.';
+const NO_ARGS = z.tuple([]);
+/**
+ * Build this game's universal instrument set. One call per mounted game; the
+ * caller owns the returned {@link DevInstrumentSet.dispose}.
+ */
+export function createDevInstruments(game) {
+    // --- Frame time: one subscription, one ring buffer ------------------------
+    const samples = [];
+    let previousFrameAt = now();
+    const stopSampling = game.onRenderStep(() => {
+        const at = now();
+        samples.push(at - previousFrameAt);
+        previousFrameAt = at;
+        if (samples.length > FRAME_TIME_WINDOW)
+            samples.shift();
+    });
+    // --- Collider draw: the adapter has a setter and no getter, so the ON/OFF
+    // state is ours to remember. It is only ever written through the one action
+    // below, which is also the only thing that calls the adapter.
+    let collidersDrawn = false;
+    const colliderDraw = () => {
+        const adapter = game.systemAdapters.physics;
+        return adapter?.setDebugDrawEnabled ? adapter : null;
+    };
+    const instruments = [
+        {
+            id: 'timescale',
+            label: 'Time scale',
+            hint: 'Sim speed multiplier. 1 is real time, 0 freezes the simulation while the game keeps drawing.',
+            unit: 'x',
+            control: {
+                kind: 'scale',
+                action: 'set',
+                min: TIME_SCALE_RANGE.min,
+                max: TIME_SCALE_RANGE.max,
+                step: 0.05,
+            },
+            actions: [
+                {
+                    id: 'set',
+                    label: 'Set',
+                    hint: `Set the sim speed multiplier (${TIME_SCALE_RANGE.min}–${TIME_SCALE_RANGE.max}).`,
+                    args: z.tuple([z.number()]),
+                    run: (values) => {
+                        // The LOOP clamps and warns; asking for the clamp here too would
+                        // be a second opinion about the same range. It reads back the
+                        // value that actually took effect, never the one requested.
+                        game.loop.timeScale = clampTimeScale(values[0]);
+                        return game.loop.timeScale;
+                    },
+                },
+            ],
+            read: () => game.loop.timeScale,
+        },
+        {
+            id: 'paused',
+            label: 'Paused',
+            hint: 'Freeze the simulation. The game keeps drawing, so you can look at a frozen frame.',
+            control: { kind: 'toggle', action: 'toggle' },
+            actions: [
+                {
+                    id: 'toggle',
+                    label: 'Toggle',
+                    hint: 'Pause or resume the simulation.',
+                    args: NO_ARGS,
+                    run: () => {
+                        if (game.play.paused)
+                            game.play.resume();
+                        else
+                            game.play.pause();
+                        return game.play.paused;
+                    },
+                },
+                {
+                    id: 'step',
+                    label: 'Step',
+                    hint: 'Advance exactly one fixed substep. Pauses first if the game is running.',
+                    args: NO_ARGS,
+                    run: () => {
+                        // Frame advance implies pause — `Game.play.step()` is a
+                        // deliberate whole-call no-op while running, and a button that
+                        // silently does nothing is the failure this instrument exists to
+                        // avoid.
+                        if (!game.play.paused)
+                            game.play.pause();
+                        game.play.step();
+                        return game.play.paused;
+                    },
+                },
+            ],
+            read: () => game.play.paused,
+        },
+        {
+            id: 'colliders',
+            label: 'Colliders drawn',
+            hint: "Draw the physics colliders over the world, through the game's own physics adapter.",
+            control: { kind: 'toggle', action: 'toggle' },
+            actions: [
+                {
+                    id: 'toggle',
+                    label: 'Toggle',
+                    hint: 'Turn collider wireframes on or off.',
+                    args: NO_ARGS,
+                    run: () => {
+                        const adapter = colliderDraw();
+                        if (!adapter)
+                            throw new Error(NO_COLLIDERS);
+                        collidersDrawn = !collidersDrawn;
+                        adapter.setDebugDrawEnabled?.(collidersDrawn);
+                        return collidersDrawn;
+                    },
+                },
+            ],
+            read: () => (colliderDraw() === null ? null : collidersDrawn),
+        },
+        {
+            id: 'frame-time',
+            label: 'Frame time',
+            hint: 'Wall-clock milliseconds per display frame, newest last. The window is where a hitch shows; the mean hides it.',
+            unit: 'ms',
+            control: { kind: 'plot' },
+            actions: [
+                {
+                    id: 'clear',
+                    label: 'Clear',
+                    hint: 'Forget the sampled window and start measuring again.',
+                    args: NO_ARGS,
+                    run: () => {
+                        samples.length = 0;
+                        return null;
+                    },
+                },
+            ],
+            read: () => summarizeFrameTimes(samples),
+        },
+    ];
+    return {
+        instruments,
+        dispose() {
+            stopSampling();
+            samples.length = 0;
+        },
+    };
+}
+function now() {
+    return typeof performance === 'undefined' ? Date.now() : performance.now();
+}

package/dist/dev/logger.d.ts

@@ -0,0 +1,30 @@
+import { LogLayer } from 'loglayer';
+/**
+ * Flag set while the engine logger is calling console.* so that the
+ * console-bridge and play-mode patches can skip re-forwarding.
+ * JS is single-threaded so this is safe.
+ */
+export declare let _engineLogActive: boolean;
+declare const engineLog: LogLayer;
+export interface LogMeta {
+    entityId?: string | number | undefined;
+    [key: string]: unknown;
+}
+interface SubsystemLogger {
+    debug(msg: string, meta?: LogMeta): void;
+    info(msg: string, meta?: LogMeta): void;
+    warn(msg: string, meta?: LogMeta): void;
+    error(msg: string, meta?: LogMeta): void;
+}
+export declare const log: {
+    scene: SubsystemLogger;
+    physics: SubsystemLogger;
+    animation: SubsystemLogger;
+    network: SubsystemLogger;
+    audio: SubsystemLogger;
+    ai: SubsystemLogger;
+    input: SubsystemLogger;
+    core: SubsystemLogger;
+};
+export { engineLog };
+//# sourceMappingURL=logger.d.ts.map

package/dist/dev/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/dev/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,QAAQ,EAAY,MAAM,UAAU,CAAC;AAE9D;;;;GAIG;AACH,eAAO,IAAI,gBAAgB,SAAQ,CAAC;AAWpC,QAAA,MAAM,SAAS,UA4Cb,CAAC;AAKH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1C;AAiBD,eAAO,MAAM,GAAG;;;;;;;;;CASf,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/dev/logger.js

@@ -0,0 +1,90 @@
+import { BlankTransport, LogLayer, LogLevel } from 'loglayer';
+/**
+ * Flag set while the engine logger is calling console.* so that the
+ * console-bridge and play-mode patches can skip re-forwarding.
+ * JS is single-threaded so this is safe.
+ */
+export let _engineLogActive = false;
+const CONSOLE_MAP = {
+    trace: 'log',
+    debug: 'log',
+    info: 'log',
+    warn: 'warn',
+    error: 'error',
+    fatal: 'error',
+};
+const engineLog = new LogLayer({
+    transport: new BlankTransport({
+        shipToLogger: ({ logLevel, messages, data, hasData }) => {
+            const method = CONSOLE_MAP[logLevel] ?? 'log';
+            // Extract _sub (subsystem tag) from data, pass the rest as metadata
+            let subsystem;
+            let metadata;
+            if (hasData && data) {
+                const { _sub, ...rest } = data;
+                subsystem = _sub ? String(_sub) : undefined;
+                if (Object.keys(rest).length > 0)
+                    metadata = rest;
+            }
+            // Call console for browser devtools
+            _engineLogActive = true;
+            if (metadata) {
+                // biome-ignore lint/suspicious/noConsole: intentional — this IS the logger
+                console[method](...messages, metadata);
+            }
+            else {
+                // biome-ignore lint/suspicious/noConsole: intentional — this IS the logger
+                console[method](...messages);
+            }
+            _engineLogActive = false;
+            // Post structured message for editor console
+            if (typeof window !== 'undefined') {
+                window.postMessage({
+                    type: 'engine-log',
+                    level: logLevel,
+                    message: messages.join(' '),
+                    subsystem,
+                    metadata,
+                    timestamp: Date.now(),
+                }, '*');
+            }
+            return messages;
+        },
+    }),
+    prefix: '[engine]',
+});
+// Default to 'info' — debug/trace are off unless explicitly enabled
+engineLog.setLevel(LogLevel.info);
+function createSubsystemLogger(subsystem) {
+    return {
+        debug: (msg, meta) => engineLog.withMetadata({ ...meta, _sub: subsystem }).debug(`[${subsystem}] ${msg}`),
+        info: (msg, meta) => engineLog.withMetadata({ ...meta, _sub: subsystem }).info(`[${subsystem}] ${msg}`),
+        warn: (msg, meta) => engineLog.withMetadata({ ...meta, _sub: subsystem }).warn(`[${subsystem}] ${msg}`),
+        error: (msg, meta) => engineLog.withMetadata({ ...meta, _sub: subsystem }).error(`[${subsystem}] ${msg}`),
+    };
+}
+// Pre-built subsystem loggers — all share the same LogLayer instance
+// so setLevel() on engineLog affects all of them.
+export const log = {
+    scene: createSubsystemLogger('scene'),
+    physics: createSubsystemLogger('physics'),
+    animation: createSubsystemLogger('animation'),
+    network: createSubsystemLogger('network'),
+    audio: createSubsystemLogger('audio'),
+    ai: createSubsystemLogger('ai'),
+    input: createSubsystemLogger('input'),
+    core: createSubsystemLogger('core'),
+};
+export { engineLog };
+// Expose to browser devtools: type setEngineLogLevel('debug') in console
+if (typeof window !== 'undefined') {
+    window['setEngineLogLevel'] = (level) => {
+        engineLog.setLevel(level);
+    };
+}
+// URL param override: ?engineLogLevel=debug
+if (typeof window !== 'undefined') {
+    const level = new URLSearchParams(window.location.search).get('engineLogLevel');
+    if (level)
+        engineLog.setLevel(level);
+}

package/dist/dev/performance-profiler.d.ts

@@ -0,0 +1,111 @@
+export interface PerformanceTiming {
+    readonly name: string;
+    readonly ms: number;
+    /**
+     * Offset (ms) from THIS frame's start (`frameStart`) at which the timing
+     * began — a MEASURED value (e.g. a phase's `phaseStart - frameStart`), never
+     * synthesized. Present on per-frame phase timings (W4b, so a Chrome trace
+     * can place each phase span under its frame at the real offset). OMITTED on
+     * cross-frame aggregate rollups (`PerformanceSnapshot.phases`/`systems`/
+     * `components`), where no single start point exists — absent, never a
+     * fabricated 0.
+     */
+    readonly startMs?: number;
+}
+/**
+ * One MEASURED span within a frame (W4b) — a system or component invocation,
+ * with the phase it ran in and its measured start offset from `frameStart`.
+ * Distinct from {@link PerformanceTiming}: a span is a single timed
+ * invocation carrying `phase` + always-present `startMs` (the trace/flame
+ * unit), whereas a `PerformanceTiming` may be a cross-frame rollup.
+ */
+export interface PerformanceSpan {
+    readonly name: string;
+    readonly phase: string;
+    /** Measured offset (ms) from `frameStart` at which this span began. */
+    readonly startMs: number;
+    readonly ms: number;
+}
+/** Renderer counters accumulated over a frame (from `renderer.info`). */
+export interface PerformanceRenderStats {
+    readonly gpuMs: number | null;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly geometries: number;
+    readonly textures: number;
+}
+export interface PerformanceFrame {
+    readonly id: number;
+    readonly timestamp: number;
+    readonly intervalMs: number;
+    readonly cpuMs: number;
+    readonly phases: readonly PerformanceTiming[];
+    /**
+     * Per-invocation system spans measured this frame (W4b). Ordered by
+     * `startMs` (execution order), NOT accumulated — a system that ran twice
+     * (two substeps) appears twice. Empty when the profiler saw no named
+     * systems this frame.
+     */
+    readonly systems: readonly PerformanceSpan[];
+    /**
+     * Per-invocation component spans measured this frame (W4b) — populated ONLY
+     * while `recording` (component timing is gated on recording, matching
+     * `beginComponent`/`endComponent`). Empty otherwise.
+     */
+    readonly components: readonly PerformanceSpan[];
+    /**
+     * Renderer counters reported during this frame (W4b) — a snapshot of the
+     * accumulated `reportRender` totals taken at `endFrame`. `gpuMs` is `null`
+     * when no GPU timer reported (headless/SwiftShader), never a fabricated 0.
+     */
+    readonly render: PerformanceRenderStats;
+}
+export interface PerformanceSnapshot {
+    readonly enabled: boolean;
+    readonly recording: boolean;
+    readonly fps: number;
+    readonly cpuMs: number;
+    readonly p95Ms: number;
+    readonly p99Ms: number;
+    readonly frames: readonly PerformanceFrame[];
+    readonly phases: readonly PerformanceTiming[];
+    readonly systems: readonly PerformanceTiming[];
+    readonly components: readonly PerformanceTiming[];
+    readonly render: {
+        readonly gpuMs: number | null;
+        readonly drawCalls: number;
+        readonly triangles: number;
+        readonly geometries: number;
+        readonly textures: number;
+    };
+}
+/** Game-owned, bounded external store for browser-native performance diagnostics. */
+export declare function createPerformanceProfiler(initiallyEnabled?: boolean): {
+    enabled: boolean;
+    readonly recording: boolean;
+    startRecording(): void;
+    stopRecording(): void;
+    clear(): void;
+    beginFrame(): void;
+    beginPhase(): void;
+    endPhase(name: string): void;
+    systemObserver: {
+        beginSystem(): void;
+        endSystem(scope: string, phase: string, name: string): void;
+    };
+    beginComponent(): void;
+    endComponent(name: string, phase?: string): void;
+    reportRender(stats: {
+        gpuMs: number | null;
+        drawCalls: number;
+        triangles: number;
+        geometries: number;
+        textures: number;
+    }): void;
+    endFrame(): void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): PerformanceSnapshot;
+    exportJSON(): string;
+};
+export type PerformanceProfiler = ReturnType<typeof createPerformanceProfiler>;
+//# sourceMappingURL=performance-profiler.d.ts.map