@downdraft/engine 0.0.0 → 0.1.1

package/core/src/telemetry/reporter.ts

@@ -0,0 +1,62 @@
+import type { DrawStats, SystemTiming, TelemetryCollector, ThreadMetrics } from "./collector";
+
+export class TelemetryReporter {
+  private collector: TelemetryCollector;
+
+  constructor(collector: TelemetryCollector) {
+    this.collector = collector;
+  }
+
+  getSnapshot() {
+    const mem = this.collector.getMemoryUsage();
+    const drawStats = this.collector.getDrawStats();
+    return {
+      threads: this.collector.getThreadMetrics(),
+      systemTimings: this.collector.getSystemTimings(),
+      frameTimes: this.collector.getFrameTimes(),
+      averageFrameTime: this.collector.getAverageFrameTime(),
+      p99FrameTime: this.collector.getFrameTimePercentile(0.99),
+      p95FrameTime: this.collector.getFrameTimePercentile(0.95),
+      fps: this.collector.getFPS(),
+      drawCalls: drawStats.drawCalls,
+      triangles: drawStats.triangles,
+      gpuTimeMs: this.collector.getGpuTime(),
+      memory: mem,
+      timestamp: Date.now(),
+    };
+  }
+
+  toJSON(): string {
+    return JSON.stringify(this.getSnapshot());
+  }
+
+  getMCPFormat() {
+    const snap = this.getSnapshot();
+    return {
+      threads: snap.threads.map((t: ThreadMetrics) => ({
+        thread: t.threadName,
+        gc: { totalMs: t.gcPauseTotal, count: t.gcPauseCount, maxMs: t.gcPauseMax },
+        memory: { heapUsed: t.heapUsed, heapTotal: t.heapTotal, rss: t.rss },
+        cpu: { timeMs: t.cpuTime },
+        tick: t.tick,
+      })),
+      frame: {
+        avgMs: snap.averageFrameTime,
+        p95Ms: snap.p95FrameTime,
+        p99Ms: snap.p99FrameTime,
+        fps: snap.fps,
+        history: snap.frameTimes,
+      },
+      draw: {
+        calls: snap.drawCalls,
+        triangles: snap.triangles,
+        gpuTimeMs: snap.gpuTimeMs,
+      } as unknown as DrawStats & { gpuTimeMs: number },
+      memory: snap.memory,
+      systems: snap.systemTimings.map((s: SystemTiming) => ({
+        name: s.name,
+        durationMs: s.durationMs,
+      })),
+    };
+  }
+}

package/core/src/types/engine-types.ts

@@ -0,0 +1,129 @@
+// ============================================================================
+// Engine-level shared types — math, identifiers, enums, and message protocols
+// Generic types used across engine core and any game implementation.
+// ============================================================================
+
+import { CameraMode } from "../render/camera";
+
+// --- Math ---
+
+export interface Vec2 { x: number; y: number; }
+export interface Vec3 { x: number; y: number; z: number; }
+export interface Vec4 { x: number; y: number; z: number; w: number; }
+export type Quat = Vec4;
+
+export interface Transform {
+  position: Vec3;
+  rotation: Quat;
+  scale: Vec3;
+}
+
+// --- Identifiers ---
+
+export type EntityId = number;
+export type PlayerId = number;
+
+// --- Camera ---
+// CameraMode is exported from ./render/camera — not duplicated here.
+
+// --- Entity Flags (generic engine-level flags) ---
+
+export enum EntityFlags {
+  None = 0,
+  Static = 1 << 0,
+  NoCollision = 1 << 1,
+  Underwater = 1 << 2,
+  Onboard = 1 << 3,
+  Docked = 1 << 4,
+  Sleeping = 1 << 5,
+  Dead = 1 << 6,
+  Hostile = 1 << 7,
+  Tameable = 1 << 8,
+  Bioluminescent = 1 << 9,
+}
+
+// --- Entity Component Data (generic engine-level entity representation) ---
+
+export interface EntityData {
+  id: EntityId;
+  type: number;
+  flags: number;
+  transform: Transform;
+  velocity: Vec3;
+  angularVelocity: Vec3;
+  health: number;
+  maxHealth: number;
+  parentId: EntityId;
+  chunkX: number;
+  chunkZ: number;
+  data: Float32Array;
+}
+
+export interface PlayerState {
+  id: PlayerId;
+  entityId: EntityId;
+  health: number;
+  maxHealth: number;
+  hunger: number;
+  thirst: number;
+  oxygen: number;
+  maxOxygen: number;
+  temperature: number;
+  cameraMode: CameraMode;
+  activeSlot: number;
+  flags: number;
+  viewportX: number;
+  viewportY: number;
+  viewportW: number;
+  viewportH: number;
+}
+
+// --- Message Protocols (generic sim↔renderer↔main message types) ---
+
+export interface SimToRendererMessage {
+  kind: "entity_spawn" | "entity_despawn" | "ui_event" | "state_snapshot" | "weather_update" | "market_update" | "catch_result" | "trade_result" | "notification" | "player_update";
+  data: any;
+}
+
+export interface RendererToSimMessage {
+  kind: "input_action" | "build_request" | "fish_cast" | "fish_reel" | "trade" | "place_item" | "remove_item" | "sleep" | "respawn" | "customization" | "gamemode" | "save" | "load" | "settings";
+  data: any;
+}
+
+export interface MainToSimMessage {
+  kind: "init" | "pause" | "resume" | "save" | "load" | "set_gamemode" | "set_setting" | "add_player" | "remove_player" | "shutdown" | "respawn" | "debug_mode" | "command" | "world_command" | "set_weather" | "set_time_of_day";
+  data: any;
+}
+
+/** Base engine-level event kinds emitted by the sim thread. Games can extend
+ *  this with their own kinds — the `string` fallback allows game-specific event
+ *  names without modifying core. Use `(string & {})` to preserve IDE autocomplete
+ *  for the known base kinds while accepting any string. */
+export type SimToMainKind =
+  | "ready" | "saved" | "loaded" | "error" | "performance"
+  | "player_died" | "weather_changed" | "gc_stats" | "gc_controller_stats"
+  | "perf_stats" | "terrain_deformed" | "terrain_lod_changed"
+  | "sim_speed_changed"
+  | (string & {});
+
+export interface SimToMainMessage {
+  kind: SimToMainKind;
+  data: any;
+}
+
+// --- DB Protocol ---
+
+export interface DbRequest {
+  id: number;
+  type: "init" | "query" | "shutdown";
+  dataDir?: string;
+  sql?: string;
+  params?: Record<string, unknown>;
+}
+
+export interface DbResponse {
+  id: number;
+  type: string;
+  result?: unknown;
+  error?: string;
+}

package/core/src/ui-font-scale.ts

@@ -0,0 +1,112 @@
+// ============================================================================
+// System font-size detection + font-scale utilities.
+//
+// detectSystemFontScale() measures the browser's default font size (1rem in
+// CSS pixels) and returns a scale factor relative to the 16px browser default.
+// If the user has increased their system/browser font size (e.g. for
+// accessibility), the returned scale is > 1.0. It is clamped to a minimum of
+// 1.0 — we never scale text down below the engine's designed sizes.
+//
+// The detected scale is used as the default font scale for game UI. Games
+// can let the user increase it further via a settings control; the effective
+// scale is `max(systemFontScale, userFontScale)`.
+// ============================================================================
+
+let cachedSystemScale: number | null = null;
+
+/**
+ * Detect the system/browser default font size and return a scale factor
+ * relative to 16px (the browser default). Always returns >= 1.0.
+ *
+ * Example: if the user set their browser default font to 20px, this returns
+ * 1.25. If the browser default is 16px (normal), this returns 1.0.
+ *
+ * Must be called on the main thread (requires `document`).
+ */
+export function detectSystemFontScale(): number {
+  if (cachedSystemScale !== null) return cachedSystemScale;
+  // On the native host the document is a canvas-compat facade — there is no
+  // CSS engine and no getComputedStyle, so there is no "system font size"
+  // to measure. Always 1.
+  if (typeof document === "undefined" || !document.body || typeof getComputedStyle !== "function") {
+    cachedSystemScale = 1;
+    return 1;
+  }
+
+  const el = document.createElement("div");
+  el.style.fontSize = "1rem";
+  el.style.position = "absolute";
+  el.style.visibility = "hidden";
+  el.style.lineHeight = "0";
+  el.style.margin = "0";
+  el.style.padding = "0";
+  document.body.appendChild(el);
+
+  let scale = 1;
+  try {
+    const size = parseFloat(getComputedStyle(el).fontSize);
+    // 16px is the browser default. Only scale up (never down).
+    scale = size > 0 ? Math.max(1, size / 16) : 1;
+  } catch {
+    scale = 1;
+  } finally {
+    document.body.removeChild(el);
+  }
+
+  cachedSystemScale = scale;
+  return scale;
+}
+
+/**
+ * Cached accessor for the system font scale. After the first call to
+ * detectSystemFontScale(), subsequent calls return the cached value.
+ */
+export function getSystemFontScale(): number {
+  return cachedSystemScale ?? detectSystemFontScale();
+}
+
+/**
+ * localStorage key for the user's font-scale preference.
+ * Stored as a number (e.g. 1.25). Games read this on startup to set their
+ * UI font scale (`setUIFontScale`).
+ */
+export const FONT_SCALE_STORAGE_KEY = "dd:fontScale";
+
+/**
+ * Load the user's font-scale preference from localStorage. Returns null if
+ * not set (the caller should fall back to the system-detected scale).
+ */
+export function loadUserFontScale(): number | null {
+  if (typeof localStorage === "undefined") return null;
+  try {
+    const raw = localStorage.getItem(FONT_SCALE_STORAGE_KEY);
+    if (raw === null) return null;
+    const val = parseFloat(raw);
+    return isNaN(val) ? null : Math.max(1, val);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save the user's font-scale preference to localStorage.
+ */
+export function saveUserFontScale(scale: number): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(FONT_SCALE_STORAGE_KEY, String(Math.max(1, scale)));
+  } catch {
+    // Ignore storage errors (private mode, quota, etc.)
+  }
+}
+
+/**
+ * Compute the effective font scale: the maximum of the system-detected scale
+ * and the user's preference. This ensures the system accessibility setting is
+ * always respected, even if the user hasn't explicitly set a preference.
+ */
+export function getEffectiveFontScale(userScale: number | null): number {
+  const system = getSystemFontScale();
+  if (userScale === null) return system;
+  return Math.max(system, userScale);
+}

package/core/src/util/broad-phase-grid.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// SpatialGrid — uniform-grid spatial hash for broad-phase collision/AI queries.
+//
+// Inserts 2D points (x, z) into cells of configurable size. queryNeighbors
+// returns all slots in the 3x3 neighborhood around a query point. The grid
+// uses a numeric hash key (no string allocation) and a caller-owned output
+// array to avoid per-query GC pressure.
+//
+// Usage:
+//   const grid = new SpatialGrid(10); // cellSize = 10 units
+//   grid.clear();
+//   grid.insert(slotIndex, x, z);
+//   const neighbors = grid.queryNeighbors(x, z, reusableOutArray);
+//   for (let i = 0; i < neighbors.length; i++) { ... } // neighbors[i] is a slot index
+//
+// The grid is NOT thread-safe. Reuse one instance per system; clear() each tick.
+// ============================================================================
+
+export class BroadPhaseGrid {
+  readonly cellSize: number;
+  private readonly invCellSize: number;
+  private cells: Map<number, number[]>;
+
+  constructor(cellSize: number) {
+    if (cellSize <= 0) throw new Error(`BroadPhaseGrid: cellSize must be > 0, got ${cellSize}`);
+    this.cellSize = cellSize;
+    this.invCellSize = 1 / cellSize;
+    this.cells = new Map();
+  }
+
+  clear(): void {
+    this.cells.clear();
+  }
+
+  insert(slot: number, x: number, z: number): void {
+    const key = this.cellKey(x, z);
+    let bucket = this.cells.get(key);
+    if (!bucket) {
+      bucket = [];
+      this.cells.set(key, bucket);
+    }
+    bucket.push(slot);
+  }
+
+  // Fills `out` with slot indices in the 3x3 neighborhood around (x, z).
+  // Returns `out` (caller-owned, reused across calls to avoid allocation).
+  // The caller must clear `out` before calling if it's a persistent array —
+  // this method appends to whatever is already in `out`.
+  queryNeighbors(x: number, z: number, out: number[]): number[] {
+    const cx = Math.floor(x * this.invCellSize);
+    const cz = Math.floor(z * this.invCellSize);
+    const cells = this.cells;
+    for (let dx = -1; dx <= 1; dx++) {
+      for (let dz = -1; dz <= 1; dz++) {
+        const key = this.hashKey(cx + dx, cz + dz);
+        const bucket = cells.get(key);
+        if (!bucket) continue;
+        for (let i = 0; i < bucket.length; i++) {
+          out.push(bucket[i]);
+        }
+      }
+    }
+    return out;
+  }
+
+  // Returns the count of entries currently in the grid (for debugging/profiling).
+  size(): number {
+    let count = 0;
+    for (const bucket of this.cells.values()) count += bucket.length;
+    return count;
+  }
+
+  private cellKey(x: number, z: number): number {
+    return this.hashKey(Math.floor(x * this.invCellSize), Math.floor(z * this.invCellSize));
+  }
+
+  // Numeric hash: avoids string allocation from template literals like `${cx},${cz}`.
+  // The constants are large primes that mix the bits well for typical world coords.
+  private hashKey(cx: number, cz: number): number {
+    return ((cx * 73856093) ^ (cz * 19349663)) >>> 0;
+  }
+}

package/core/src/util/feature-log.ts

@@ -0,0 +1,220 @@
+// ============================================================================
+// Feature Log — terse, versioned, pipe-delimited startup diagnostics
+// ============================================================================
+//
+// Emits a compact, uniform-across-versions string at engine startup so a user
+// with a problem can paste it and a maintainer gets a diffable summary of the
+// environment (OS, CPU, RAM, GPU, WebGPU features/limits, runtime versions,
+// active plugins, SAB/COOP-COEP/worker status).
+//
+// On the native runtime a single line is emitted (one process):
+//   dd-host|...   — host scope: OS/CPU/RAM/runtime + WebGPU adapter/features/
+//                   limits + display + plugins merged into one record
+// The "render" scope remains for callers that log renderer-side data
+// separately (dd-render|...).
+//
+// ── Backwards-compatibility contract ─────────────────────────────────────────
+//
+// The `FeatureLogData` schema and the encoder's key order are the STABLE
+// contract. Rules:
+//   * New fields are APPENDED at the end of the key-order table.
+//   * Existing fields are NEVER renamed, reordered, or removed.
+//   * The `sv` (schema version) field is the only breaking-change gate;
+//     bumping it signals a new format that old parsers may reject.
+//   * Parsers MUST ignore unknown trailing keys (forward-compatible).
+//
+// Code and logs are free to change; only the data schema is locked.
+// ============================================================================
+
+export const FEATURE_LOG_SCHEMA_VERSION = 1;
+
+/** Short codes for WebGPU features (additive; never reuse a code). */
+const WGPU_FEATURE_CODES: Record<string, string> = {
+  "timestamp-query": "tsq",
+  "timestamp-query-inside-passes": "tsqip",
+  "depth-clip-control": "dclip",
+  "depth32float-stencil8": "d32s8",
+  "texture-compression-bc": "bc",
+  "texture-compression-bc-sliced-3d": "bc3d",
+  "texture-compression-etc2": "etc2",
+  "texture-compression-astc": "astc",
+  "indirect-first-instance": "ifi",
+  "shader-f16": "f16",
+  "rg11b10ufloat-renderable": "rg11b10",
+  "bgra8unorm-storage": "bgras",
+  "float32-filterable": "f32filt",
+  "float32-blendable": "f32blend",
+  "clip-distances": "clipd",
+  "dual-source-blending": "dualsrc",
+  "subgroups": "sub",
+};
+
+/**
+ * Versioned, additive schema. New fields appended; never reorder/rename/remove.
+ *
+ * `?` optional fields are omitted from the encoded line when absent (the
+ * additive schema tolerates missing fields — a parser treats absent keys as
+ * "unknown for this process").
+ */
+export interface FeatureLogData {
+  sv: number; // schema version (always FEATURE_LOG_SCHEMA_VERSION)
+  scope: "render" | "host"; // "host" = single-process (native) merged log
+  v: string; // engine version ("0.1.0")
+  mode: "dev" | "packaged" | "deterministic";
+  // --- main-only ---
+  os?: string; // "linux" | "win32" | "darwin"
+  osRel?: string; // OS release
+  arch?: string; // "x64" | "arm64" | "ia32"
+  cpu?: string; // CPU model (condensed)
+  cpuCores?: number; // logical core count
+  mem?: string; // total RAM, human ("64G")
+  node?: string; // Node version
+  v8?: string; // V8 version
+  gpu?: string; // GPU name (wgpu adapter info / nvidia-smi name)
+  drv?: string; // GPU driver version
+  sw?: string; // applied host flags, comma-sep ("swiftshader,vulkan")
+  // --- render-only ---
+  wgpu?: string; // "vendor=...;dev=...;arch=...;fmt=...;feat=...;lim=..."
+  disp?: string; // "WxH@Hz"
+  sf?: number; // display scale factor
+  sab?: 0 | 1; // SharedArrayBuffer available
+  coi?: 0 | 1; // crossOriginIsolated
+  wk?: "ok" | "fail" | "na"; // worker load status (best-effort)
+  plug?: string; // active plugin names, comma-sep
+  rt?: string; // JS runtime tag — "bun" | "node" | "deno" (appended; sv stays 1)
+}
+
+// ── Key-order table (the stable contract) ───────────────────────────────────
+// Order matters: this is the exact order keys appear in the encoded line.
+// Append new keys at the end; never reorder.
+
+type Formatter = (v: unknown) => string | null;
+
+const IDENTITY: Formatter = (v) => (v === undefined || v === null ? null : String(v));
+const NUM: Formatter = (v) => (v === undefined || v === null ? null : String(v));
+
+const KEY_ORDER: Array<{ key: string; fmt: Formatter }> = [
+  { key: "sv", fmt: NUM },
+  { key: "scope", fmt: IDENTITY },
+  { key: "v", fmt: IDENTITY },
+  { key: "mode", fmt: IDENTITY },
+  { key: "os", fmt: IDENTITY },
+  { key: "osRel", fmt: IDENTITY },
+  { key: "arch", fmt: IDENTITY },
+  { key: "cpu", fmt: IDENTITY },
+  { key: "cpuCores", fmt: NUM },
+  { key: "mem", fmt: IDENTITY },
+  { key: "node", fmt: IDENTITY },
+  { key: "v8", fmt: IDENTITY },
+  { key: "gpu", fmt: IDENTITY },
+  { key: "drv", fmt: IDENTITY },
+  { key: "sw", fmt: IDENTITY },
+  { key: "wgpu", fmt: IDENTITY },
+  { key: "disp", fmt: IDENTITY },
+  { key: "sf", fmt: NUM },
+  { key: "sab", fmt: NUM },
+  { key: "coi", fmt: NUM },
+  { key: "wk", fmt: IDENTITY },
+  { key: "plug", fmt: IDENTITY },
+  { key: "rt", fmt: IDENTITY },
+];
+
+// ── Value condensers ────────────────────────────────────────────────────────
+
+/** Trim whitespace and collapse runs; cap length to keep the line terse. */
+export function condenseText(s: string, max = 48): string {
+  const trimmed = String(s).trim().replace(/\s+/g, " ");
+  if (trimmed.length <= max) return trimmed;
+  return trimmed.slice(0, max - 1) + "\u2026";
+}
+
+/** Format bytes as a short human string (e.g. 68719476736 -> "64G"). */
+export function formatBytesShort(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0";
+  const units = ["B", "K", "M", "G", "T", "P"];
+  let v = bytes;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  // Whole units for K and above; raw bytes stay as-is.
+  if (i === 0) return `${Math.round(v)}B`;
+  return `${Math.round(v)}${units[i]}`;
+}
+
+/** Map a WebGPU feature name to its short code (falls back to the raw name). */
+export function featureCode(name: string): string {
+  return WGPU_FEATURE_CODES[name] ?? name;
+}
+
+/** Encode a set of WebGPU feature names into comma-separated short codes. */
+export function encodeFeatures(features: Iterable<string>): string {
+  const codes: string[] = [];
+  // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<string>; for..of required
+  for (const f of features) {
+    const c = featureCode(f);
+    if (c) codes.push(c);
+  }
+  return codes.join(",");
+}
+
+// ── Encoder ─────────────────────────────────────────────────────────────────
+
+/**
+ * Encode a FeatureLogData into a single pipe-delimited line.
+ * Format: `dd<sv>|key=value|key=value|...` in fixed key order.
+ */
+export function encodeFeatureLogLine(data: FeatureLogData): string {
+  const parts: string[] = [`dd${data.sv ?? FEATURE_LOG_SCHEMA_VERSION}`];
+  for (let _i = 0, _it = KEY_ORDER, _n = _it.length; _i < _n; _i++) { const { key, fmt } = _it[_i];
+    const raw = (data as unknown as Record<string, unknown>)[key];
+    const val = fmt(raw);
+    if (val === null || val === undefined || val === "") continue;
+    parts.push(`${key}=${val}`);
+  }
+  return parts.join("|");
+}
+
+/** Encode a FeatureLogData as minified JSON (for MCP/crash structured payload). */
+export function encodeFeatureLogJSON(data: FeatureLogData): string {
+  return JSON.stringify(data);
+}
+
+// ── Decoder (for round-trip tests + tooling that parses pasted strings) ─────
+
+/**
+ * Parse a `dd<sv>|key=value|...` line back into a partial FeatureLogData.
+ * Unknown keys are ignored (forward-compatible). Returns null if the line
+ * is not a feature-log line.
+ */
+export function decodeFeatureLogLine(line: string): Partial<FeatureLogData> | null {
+  const s = line.trim();
+  if (!/^dd\d+\|/.test(s)) return null;
+  const parts = s.split("|");
+  const head = parts.shift()!;
+  const sv = parseInt(head.slice(2), 10);
+  const out: Record<string, unknown> = { sv };
+  for (let _i = 0, _it = parts, _n = _it.length; _i < _n; _i++) { const part = _it[_i];
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    const key = part.slice(0, eq);
+    const val = part.slice(eq + 1);
+    // Coerce known numeric fields.
+    if (key === "sv" || key === "cpuCores" || key === "sf" || key === "sab" || key === "coi") {
+      const n = Number(val);
+      out[key] = Number.isFinite(n) ? n : val;
+    } else {
+      out[key] = val;
+    }
+  }
+  return out as Partial<FeatureLogData>;
+}
+
+/** Encode host + render lines (newline-separated) for clipboard/MCP. */
+export function encodeFeatureLogLines(host: FeatureLogData | null, render: FeatureLogData | null): string {
+  const lines: string[] = [];
+  if (host) lines.push(encodeFeatureLogLine(host));
+  if (render) lines.push(encodeFeatureLogLine(render));
+  return lines.join("\n");
+}

package/core/src/util/index.ts

@@ -0,0 +1,17 @@
+// Util sub-barrel — re-exports all utility items.
+export { BroadPhaseGrid } from "./broad-phase-grid";
+export {
+    condenseText,
+    decodeFeatureLogLine,
+    encodeFeatureLogJSON,
+    encodeFeatureLogLine,
+    encodeFeatureLogLines,
+    encodeFeatures,
+    FEATURE_LOG_SCHEMA_VERSION,
+    featureCode,
+    formatBytesShort
+} from "./feature-log";
+export type { FeatureLogData } from "./feature-log";
+export { addLogSink, ConsoleLogger, createLogger, getRecentLogs, setThreadTag } from "./logger";
+export type { Logger, LogSink, LogSinkEntry } from "./logger";
+