@vgai/engine 0.2.0

package/src/dev/console-bridge.ts

@@ -0,0 +1,83 @@
+/**
+ * Dev-mode console bridge.
+ *
+ * Monkey-patches console.log / warn / error to also broadcast each message
+ * via `window.postMessage`. Any parent frame (IDE, editor, test harness) can
+ * listen for these messages — if nobody is listening they simply go nowhere.
+ *
+ * Also captures unhandled errors and promise rejections.
+ *
+ * Call once, as early as possible in the entry point:
+ *
+ *   import { installConsoleBridge } from '@engine/dev/console-bridge';
+ *   if (import.meta.env.DEV) installConsoleBridge();
+ */
+
+export interface ConsoleBridgeMessage {
+  type: 'console-bridge';
+  level: 'log' | 'warn' | 'error';
+  message: string;
+  timestamp: number;
+}
+
+const LEVELS = ['log', 'warn', 'error'] as const;
+
+function post(level: ConsoleBridgeMessage['level'], message: string): void {
+  const msg: ConsoleBridgeMessage = {
+    type: 'console-bridge',
+    level,
+    message,
+    timestamp: Date.now(),
+  };
+  window.postMessage(msg, '*');
+}
+
+function stringify(args: unknown[]): string {
+  return args
+    .map((a) => {
+      if (typeof a === 'string') return a;
+      try {
+        return JSON.stringify(a);
+      } catch {
+        return String(a);
+      }
+    })
+    .join(' ');
+}
+
+let installed = false;
+
+export function installConsoleBridge(): void {
+  // Idempotent: a second call must not double-patch console (which would
+  // double-post every message) nor add duplicate window listeners.
+  if (installed) return;
+  installed = true;
+
+  // Lazy import — avoid hard dep; if logger.ts isn't bundled the flag stays false
+  let getFlag: () => boolean = () => false;
+  import('./logger')
+    .then((m) => {
+      getFlag = () => m._engineLogActive;
+    })
+    .catch(() => {});
+
+  // Patch console methods
+  for (const level of LEVELS) {
+    const original = console[level].bind(console);
+    console[level] = (...args: unknown[]) => {
+      original(...args);
+      // Skip bridge posting when the engine logger is handling the message
+      // (it posts its own structured 'engine-log' message instead)
+      if (!getFlag()) post(level, stringify(args));
+    };
+  }
+
+  // Capture unhandled errors
+  window.addEventListener('error', (e) => {
+    post('error', e.message || String(e.error));
+  });
+
+  window.addEventListener('unhandledrejection', (e) => {
+    post('error', `Unhandled promise rejection: ${e.reason}`);
+  });
+}

package/src/dev/debug-draw.ts

@@ -0,0 +1,80 @@
+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: THREE.Scene) {
+  const group = new THREE.Group();
+  group.name = 'debug-draw';
+  scene.add(group);
+
+  return {
+    /** Draw a line between two points */
+    line(from: THREE.Vector3, to: THREE.Vector3, 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: THREE.Vector3, 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: THREE.Vector3, size: THREE.Vector3, 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: THREE.Vector3, direction: THREE.Vector3, 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 as THREE.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: boolean) {
+      group.visible = v;
+    },
+
+    get visible() {
+      return group.visible;
+    },
+  };
+}

package/src/dev/logger.ts

@@ -0,0 +1,119 @@
+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: Record<string, 'log' | 'warn' | 'error'> = {
+  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: string | undefined;
+      let metadata: Record<string, unknown> | undefined;
+      if (hasData && data) {
+        const { _sub, ...rest } = data as Record<string, unknown>;
+        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);
+
+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;
+}
+
+function createSubsystemLogger(subsystem: string): SubsystemLogger {
+  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 as unknown as Record<string, unknown>)['setEngineLogLevel'] = (level: string) => {
+    engineLog.setLevel(level as LogLevel);
+  };
+}
+
+// URL param override: ?engineLogLevel=debug
+if (typeof window !== 'undefined') {
+  const level = new URLSearchParams(window.location.search).get('engineLogLevel');
+  if (level) engineLog.setLevel(level as LogLevel);
+}