@downdraft/engine 0.0.0 → 0.1.1

package/modules/terrain/src/index.ts

@@ -0,0 +1,78 @@
+// ============================================================================
+// @downdraft/engine/modules/terrain — composable terrain plugin
+//
+// Composes @downdraft/engine/libraries/marching-cubes (mesh extraction + chunked voxel
+// fields) with LOD management, streaming, and deformation broadcasting into a
+// single Module with typed DI. Games register this plugin instead of manually
+// wiring TerrainSystem + TerrainLODManager + mesh worker pools.
+//
+// Provides:
+//   - TerrainStreamingTok — the terrain streaming config (LOD levels, voxel sizes)
+//
+// The actual TerrainSystem and TerrainLODManager are game-specific (they need
+// a game-provided DensityField), so games create them in onReady and inject
+// TerrainStreamingTok for the config.
+//
+// Requires:
+//   - (none — terrain is self-contained; physics integration is optional)
+// ============================================================================
+
+import {
+    resourceToken,
+    type Module,
+    type ModuleContext,
+} from "@downdraft/engine";
+import {
+    DEFAULT_STREAMING_CONFIG,
+    type TerrainStreamingConfig,
+} from "@downdraft/engine/libraries/marching-cubes";
+
+// ── Config ──
+
+export interface TerrainModuleConfig {
+  /** Streaming config (LOD levels, voxel sizes, time budgets). */
+  streaming?: Partial<TerrainStreamingConfig>;
+  /** Max physics field generations per tick. Default: 1. */
+  physFieldGenMaxPerTick?: number;
+  /** Time budget for physics field generation (ms). Default: 8. */
+  physFieldGenTimeBudgetMs?: number;
+  /** Voxel size multiplier for physics field generation. Default: 1. */
+  physVoxelSizeMultiplier?: number;
+  /** Worker count for mesh generation pool. Default: 4. */
+  meshWorkerCount?: number;
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the terrain streaming config. Inject to read LOD/streaming config. */
+export const TerrainStreamingTok = resourceToken<TerrainStreamingConfig>("terrain:streaming");
+
+// ── Module factory ──
+
+export function createTerrainModule(config: TerrainModuleConfig = {}): Module {
+  const streamingConfig: TerrainStreamingConfig = {
+    ...DEFAULT_STREAMING_CONFIG,
+    ...config.streaming,
+  };
+
+  return {
+    name: "terrain",
+    version: "1.0.0",
+
+    provides: [TerrainStreamingTok],
+
+    register(ctx: ModuleContext) {
+      // Provide the streaming config so other systems/plugins can read it.
+      ctx.provide(TerrainStreamingTok, streamingConfig);
+
+      // The actual terrain system (chunk gen, LOD, deform) and LOD manager
+      // are game-specific — they need a game-provided DensityField. Games
+      // create them in onReady and inject TerrainStreamingTok for the config.
+    },
+  };
+}
+
+// Re-export library types for convenience
+export { DEFAULT_STREAMING_CONFIG } from "@downdraft/engine/libraries/marching-cubes";
+export type { TerrainStreamingConfig } from "@downdraft/engine/libraries/marching-cubes";
+

package/modules/vitals/README.md

@@ -0,0 +1,17 @@
+# `@downdraft/engine/modules/vitals`
+
+Vitals module — health/stamina/hunger-style stat systems with decay, regen, and DI tokens.
+
+## Install
+
+```sh
+bun add @downdraft/engine/modules/vitals
+```
+
+## Key exports
+
+- `Vitals`
+- `VitalsFactoryTok`
+- `createVitalsModule`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/modules/vitals/src/index.ts

@@ -0,0 +1,43 @@
+// ============================================================================
+// @downdraft/engine/modules/vitals — shared health / damage / death / respawn / meters
+//
+// `Vitals` tracks health, damage (with overkill + last-damage-time), death,
+// respawn, delayed regen, and secondary meters (oxygen, energy, hunger, ...)
+// against a caller-supplied host object so `p.health` stays a plain save
+// field. Games wire death/damage UI through the config callbacks.
+//
+// The module wrapper provides a configured factory via DI for module-host
+// games; hand-rolled sims can use `new Vitals(config, host)` directly.
+// ============================================================================
+
+import { resourceToken, type Module, type ModuleContext } from "@downdraft/engine";
+import { Vitals, type VitalsConfig, type VitalsHost } from "./vitals";
+
+export { Vitals } from "./vitals";
+export type {
+    DamageEvent,
+    MeterConfig,
+    VitalsConfig,
+    VitalsHost,
+    VitalsSnapshot
+} from "./vitals";
+
+export type VitalsFactory<Cause = unknown, Host extends VitalsHost = VitalsHost> = (
+  host: Host,
+  overrides?: Partial<VitalsConfig<Cause, Host>>,
+) => Vitals<Cause, Host>;
+
+export const VitalsFactoryTok = resourceToken<VitalsFactory>("vitals:factory");
+
+export function createVitalsModule<Cause = unknown, Host extends VitalsHost = VitalsHost>(
+  config: VitalsConfig<Cause, Host>,
+): Module {
+  return {
+    name: "vitals",
+    version: "1.0.0",
+    provides: [VitalsFactoryTok],
+    register(ctx: ModuleContext) {
+      ctx.provide(VitalsFactoryTok, (host, overrides) => new Vitals({ ...config, ...overrides } as VitalsConfig<Cause, Host>, host));
+    },
+  };
+}

package/modules/vitals/src/vitals.ts

@@ -0,0 +1,265 @@
+// ============================================================================
+// Vitals — shared health / damage / regen / death / respawn / meter tracking
+//
+// Every game in the repo used to hand-roll the same bookkeeping: clamp health
+// on damage, track overkill + last-damage time, transition to a dead state,
+// emit damaged/died/respawned events, regenerate after a damage-free delay,
+// and tick secondary meters (oxygen / air / energy / hunger / thirst) that
+// drain under a condition and deal damage while depleted.
+//
+// `Vitals` owns that bookkeeping while writing through to a caller-supplied
+// host object (e.g. the game's player state struct) so `p.health` stays a
+// plain field that saves, SAB writers, and HUDs can keep reading directly.
+// ============================================================================
+
+/** Minimal shape the host state object must expose. */
+export interface VitalsHost {
+  health: number;
+  dead?: boolean;
+}
+
+export interface DamageEvent<Cause = unknown> {
+  health: number;
+  maxHealth: number;
+  amount: number;
+  cause: Cause | undefined;
+  /** Damage beyond what was needed to reach 0 (gibbing/armor hooks). */
+  overkill: number;
+  died: boolean;
+}
+
+export interface MeterConfig<Cause = unknown> {
+  max: number;
+  /** Initial value (default: `max`). */
+  initial?: number;
+  /**
+   * Host field the meter is bound to (e.g. `"oxygen"`). When set, the meter
+   * reads/writes `host[field]` so save data and HUD reads keep working on the
+   * plain field. When absent, the value is stored inside the Vitals instance.
+   */
+  field?: string;
+  /** Units per `dt` drained while the `drainWhen` condition is true. */
+  drainRate?: number;
+  /** Units per `dt` recovered while the drain condition is false. */
+  recoverRate?: number;
+  /**
+   * Condition key gating the drain. Absent = drains every update.
+   * Condition keys are supplied per-update via `update(dt, conditions)`.
+   */
+  drainWhen?: string;
+  /** Health damage per `dt` applied while the meter is at 0. */
+  depleteDamageRate?: number;
+  depleteDamageCause?: Cause;
+  /**
+   * Condition key gating depletion damage; defaults to `drainWhen` (e.g. a
+   * player with 0 oxygen only drowns while still submerged). Set to `""` to
+   * apply depletion damage unconditionally (starvation keeps hurting on land).
+   */
+  depleteWhen?: string;
+  onChange?(value: number, previous: number): void;
+}
+
+export interface VitalsConfig<Cause = unknown, Host extends VitalsHost = VitalsHost> {
+  maxHealth: number;
+  /**
+   * Health regeneration: `rate` hp per `dt` once `delay` seconds have passed
+   * without damage. Absent = no regen.
+   */
+  regen?: { delay: number; rate: number };
+  meters?: Record<string, MeterConfig<Cause>>;
+  /**
+   * Dead-state accessors. Defaults: `isDead` reads `host.dead ?? host.health <= 0`,
+   * `setDead` writes `host.dead` (when the host has the field).
+   */
+  isDead?(host: Host): boolean;
+  setDead?(host: Host, dead: boolean): void;
+  onDamage?(event: DamageEvent<Cause>, host: Host): void;
+  onDeath?(event: { cause: Cause | undefined; overkill: number }, host: Host): void;
+  onRespawn?(host: Host): void;
+}
+
+export interface VitalsSnapshot {
+  health: number;
+  dead: boolean;
+  meters?: Record<string, number>;
+}
+
+export class Vitals<Cause = unknown, Host extends VitalsHost = VitalsHost> {
+  private meterValues = new Map<string, number>();
+  private timeSinceDamage = Infinity;
+
+  constructor(
+    private readonly cfg: VitalsConfig<Cause, Host>,
+    readonly host: Host,
+  ) {}
+
+  get health(): number {
+    return this.host.health;
+  }
+
+  get maxHealth(): number {
+    return this.cfg.maxHealth;
+  }
+
+  get dead(): boolean {
+    return this.cfg.isDead ? this.cfg.isDead(this.host) : (this.host.dead ?? this.host.health <= 0);
+  }
+
+  private setDead(dead: boolean): void {
+    if (this.cfg.setDead) this.cfg.setDead(this.host, dead);
+    else if ("dead" in this.host) this.host.dead = dead;
+  }
+
+  /**
+   * Apply `amount` damage. No-op (returns null) while dead or when amount <= 0.
+   * Clamps health at 0, tracks overkill, resets the regen-delay timer, fires
+   * `onDamage` always and `onDeath` on the killing blow.
+   */
+  damage(amount: number, cause?: Cause): DamageEvent<Cause> | null {
+    if (this.dead || amount <= 0) return null;
+    const overkill = Math.max(0, amount - this.host.health);
+    this.host.health = Math.max(0, this.host.health - amount);
+    this.timeSinceDamage = 0;
+    const died = this.host.health <= 0;
+    if (died) this.setDead(true);
+    const event: DamageEvent<Cause> = {
+      health: this.host.health,
+      maxHealth: this.cfg.maxHealth,
+      amount,
+      cause,
+      overkill,
+      died,
+    };
+    this.cfg.onDamage?.(event, this.host);
+    if (died) this.cfg.onDeath?.({ cause, overkill }, this.host);
+    return event;
+  }
+
+  /** Heal up to `maxHealth`. Returns the amount actually applied. */
+  heal(amount: number): number {
+    const next = Math.min(this.cfg.maxHealth, this.host.health + Math.max(0, amount));
+    const applied = next - this.host.health;
+    this.host.health = next;
+    return applied;
+  }
+
+  /** Kill outright (lethal damage path that bypasses the dead guard). */
+  kill(cause?: Cause): void {
+    if (this.dead) return;
+    const overkill = 0;
+    this.host.health = 0;
+    this.setDead(true);
+    this.cfg.onDeath?.({ cause, overkill }, this.host);
+  }
+
+  /** Restore full health (+ all meters unless `restoreMeters: false`) and clear dead. */
+  respawn(opts?: { restoreMeters?: boolean }): void {
+    this.host.health = this.cfg.maxHealth;
+    this.setDead(false);
+    this.timeSinceDamage = 0;
+    if (opts?.restoreMeters !== false) {
+      for (const [name, m] of Object.entries(this.cfg.meters ?? {})) {
+        this.writeMeter(name, m.initial ?? m.max, m);
+      }
+    }
+    this.cfg.onRespawn?.(this.host);
+  }
+
+  // ── Meters ──
+
+  meter(name: string): number {
+    const m = this.cfg.meters?.[name];
+    if (!m) throw new Error(`Vitals: unknown meter "${name}"`);
+    if (m.field) return (this.host as unknown as Record<string, number>)[m.field] ?? (m.initial ?? m.max);
+    return this.meterValues.get(name) ?? (m.initial ?? m.max);
+  }
+
+  setMeter(name: string, value: number): void {
+    const m = this.cfg.meters?.[name];
+    if (!m) throw new Error(`Vitals: unknown meter "${name}"`);
+    this.writeMeter(name, value, m);
+  }
+
+  meterMax(name: string): number {
+    const m = this.cfg.meters?.[name];
+    if (!m) throw new Error(`Vitals: unknown meter "${name}"`);
+    return m.max;
+  }
+
+  /** Imperative drain (e.g. an action tax like sprint/climb energy). */
+  drainMeter(name: string, amount: number): void {
+    this.setMeter(name, this.meter(name) - Math.max(0, amount));
+  }
+
+  private writeMeter(name: string, value: number, m: MeterConfig<Cause>): void {
+    const clamped = Math.max(0, Math.min(m.max, value));
+    const prev = this.meter(name);
+    if (m.field) (this.host as unknown as Record<string, number>)[m.field] = clamped;
+    else this.meterValues.set(name, clamped);
+    if (clamped !== prev) m.onChange?.(clamped, prev);
+  }
+
+  /**
+   * Advance meters + health regen by `dt`. `dt` is in whatever unit the rates
+   * use — seconds for per-second rates, or 1 per fixed tick for per-tick rates.
+   *
+   * Condition values may be `boolean | number`: a number > 0 counts as active
+   * and multiplies the meter's `drainRate` (e.g. a biome's oxygen drain
+   * multiplier); depletion gates only check truthiness.
+   *
+   * Meter rules per update:
+   *  - drains at `drainRate × conditionValue` while `conditions[drainWhen]` is
+   *    truthy (or always at `drainRate` when no `drainWhen` is set)
+   *  - recovers at `recoverRate` while the drain condition is falsy
+   *  - while at 0, applies `depleteDamageRate` health damage gated by
+   *    `conditions[depleteWhen ?? drainWhen]` (or unconditional when neither set)
+   */
+  update(dt: number, conditions: Record<string, boolean | number> = {}): void {
+    this.timeSinceDamage += dt;
+    for (const [name, m] of Object.entries(this.cfg.meters ?? {})) {
+      const cond = m.drainWhen === undefined ? true : conditions[m.drainWhen];
+      const drainMul = cond === true ? 1 : cond || 0;
+      if (drainMul > 0) {
+        if (m.drainRate) this.writeMeter(name, this.meter(name) - m.drainRate * drainMul * dt, m);
+      } else if (m.recoverRate) {
+        this.writeMeter(name, this.meter(name) + m.recoverRate * dt, m);
+      }
+      if (m.depleteDamageRate && this.meter(name) <= 0) {
+        const gate = m.depleteWhen ?? m.drainWhen;
+        if (gate === undefined || gate === "" || conditions[gate]) {
+          this.damage(m.depleteDamageRate * dt, m.depleteDamageCause);
+        }
+      }
+    }
+    const regen = this.cfg.regen;
+    if (regen && !this.dead && this.host.health < this.cfg.maxHealth && this.timeSinceDamage >= regen.delay) {
+      this.heal(regen.rate * dt);
+    }
+  }
+
+  // ── Save / load ──
+
+  serialize(): VitalsSnapshot {
+    const snap: VitalsSnapshot = { health: this.host.health, dead: this.dead };
+    const meters = this.cfg.meters;
+    if (meters && Object.keys(meters).length > 0) {
+      snap.meters = {};
+      for (const name of Object.keys(meters)) snap.meters[name] = this.meter(name);
+    }
+    return snap;
+  }
+
+  restore(snap: Partial<VitalsSnapshot> | undefined): void {
+    if (!snap) return;
+    if (typeof snap.health === "number") this.host.health = Math.min(this.cfg.maxHealth, snap.health);
+    if (typeof snap.dead === "boolean") this.setDead(snap.dead);
+    if (snap.meters) {
+      for (const [name, v] of Object.entries(snap.meters)) {
+        if (this.cfg.meters?.[name]) this.setMeter(name, v);
+      }
+    }
+    // Restart the regen-delay window — a restored player waits for the delay
+    // before regenerating, same as one that just took damage.
+    this.timeSinceDamage = 0;
+  }
+}

package/modules/xr/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/modules/xr`
+
+XR/WebXR module — camera rig, frame loop, input mapping, and support detection for VR/AR.
+
+## Install
+
+```sh
+bun add @downdraft/engine/modules/xr
+```
+
+## Key exports
+
+- `DEFAULT_XR_CONFIG`
+- `XRCameraRig`
+- `XRFrameLoop`
+- `XRInputMapper`
+- `XRLayerManager`
+- `XRModule`
+- `XRSessionManager`
+- `checkXRSupport`
+- `formatXRDebugInfo`
+- `getXRDebugInfo`
+- …and 4 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/modules/xr/src/camera-rig.ts

@@ -0,0 +1,146 @@
+import type { CameraViewportInfo } from "@downdraft/engine";
+import type { ViewportRect } from "@downdraft/engine";
+import type { XREye } from "./layer";
+import type { XRLayerManager } from "./layer";
+import type { XRWorldOrigin } from "./types";
+
+const DEFAULT_VIEWPORT: ViewportRect = { x: 0, y: 0, w: 1, h: 1 };
+
+export class XRCameraRig {
+  private layerManager: XRLayerManager;
+  private getWorldOrigin: () => XRWorldOrigin;
+
+  private headPosition: [number, number, number] = [0, 0, 0];
+  private headQuaternion: [number, number, number, number] = [0, 0, 0, 1];
+
+  constructor(layerManager: XRLayerManager, getWorldOrigin: () => XRWorldOrigin) {
+    this.layerManager = layerManager;
+    this.getWorldOrigin = getWorldOrigin;
+  }
+
+  computeEyeCameras(
+    screenW: number,
+    screenH: number,
+  ): [CameraViewportInfo | null, CameraViewportInfo | null] {
+    const left = this.computeEyeCamera("left", screenW, screenH);
+    const right = this.computeEyeCamera("right", screenW, screenH);
+    return [left, right];
+  }
+
+  private computeEyeCamera(eye: XREye, screenW: number, screenH: number): CameraViewportInfo | null {
+    const projMatrix = this.layerManager.getProjectionMatrix(eye);
+    const viewMatrix = this.layerManager.getViewMatrix(eye);
+    const viewport = this.layerManager.getViewport(eye);
+
+    if (!projMatrix || !viewMatrix) return null;
+
+    const vp: ViewportRect = viewport
+      ? { x: viewport.x, y: viewport.y, w: viewport.width, h: viewport.height }
+      : DEFAULT_VIEWPORT;
+
+    const aspect = vp.w > 0 && vp.h > 0 ? vp.w / vp.h : 1;
+
+    const worldOrigin = this.getWorldOrigin();
+    const worldMatrix = composeWorldMatrix(worldOrigin);
+    const finalViewMatrix = multiplyMat4(worldMatrix, viewMatrix);
+
+    const position = extractPosition(finalViewMatrix);
+
+    return {
+      camera: {
+        position,
+        target: [position[0], position[1] - 1, position[2]],
+        up: [0, 1, 0],
+        fov: 90,
+        near: 0.05,
+        far: 1000,
+        aspect,
+        projectionMatrix: projMatrix,
+        viewMatrix: finalViewMatrix,
+      },
+      viewport: vp,
+    };
+  }
+
+  updateHeadPose(pose: XRViewerPose, referenceSpace: XRReferenceSpace): void {
+    const matrix = pose.transform.matrix;
+    const worldOrigin = this.getWorldOrigin();
+    const worldMatrix = composeWorldMatrix(worldOrigin);
+    const headMatrix = multiplyMat4(worldMatrix, matrix);
+
+    this.headPosition = extractPosition(headMatrix);
+    this.headQuaternion = extractQuaternion(headMatrix);
+  }
+
+  getHeadPose(): { position: [number, number, number]; quaternion: [number, number, number, number] } {
+    return { position: this.headPosition, quaternion: this.headQuaternion };
+  }
+}
+
+function composeWorldMatrix(origin: XRWorldOrigin): Float32Array {
+  const [px, py, pz] = origin.position;
+  const [qx, qy, qz, qw] = origin.quaternion;
+
+  const x2 = qx + qx, y2 = qy + qy, z2 = qz + qz;
+  const xx = qx * x2, xy = qx * y2, xz = qx * z2;
+  const yy = qy * y2, yz = qy * z2, zz = qz * z2;
+  const wx = qw * x2, wy = qw * y2, wz = qw * z2;
+
+  return new Float32Array([
+    1 - (yy + zz), xy + wz, xz - wy, 0,
+    xy - wz, 1 - (xx + zz), yz + wx, 0,
+    xz + wy, yz - wx, 1 - (xx + yy), 0,
+    px, py, pz, 1,
+  ]);
+}
+
+function multiplyMat4(a: Float32Array, b: Float32Array): Float32Array {
+  const result = new Float32Array(16);
+  for (let i = 0; i < 4; i++) {
+    for (let j = 0; j < 4; j++) {
+      let sum = 0;
+      for (let k = 0; k < 4; k++) {
+        sum += a[i * 4 + k] * b[k * 4 + j];
+      }
+      result[i * 4 + j] = sum;
+    }
+  }
+  return result;
+}
+
+function extractPosition(m: Float32Array): [number, number, number] {
+  return [m[12], m[13], m[14]];
+}
+
+function extractQuaternion(m: Float32Array): [number, number, number, number] {
+  const trace = m[0] + m[5] + m[10];
+  let qw: number, qx: number, qy: number, qz: number;
+
+  if (trace > 0) {
+    const s = 0.5 / Math.sqrt(trace + 1);
+    qw = 0.25 / s;
+    qx = (m[6] - m[9]) * s;
+    qy = (m[8] - m[2]) * s;
+    qz = (m[1] - m[4]) * s;
+  } else if (m[0] > m[5] && m[0] > m[10]) {
+    const s = 2 * Math.sqrt(1 + m[0] - m[5] - m[10]);
+    qw = (m[6] - m[9]) / s;
+    qx = 0.25 * s;
+    qy = (m[4] + m[1]) / s;
+    qz = (m[8] + m[2]) / s;
+  } else if (m[5] > m[10]) {
+    const s = 2 * Math.sqrt(1 + m[5] - m[0] - m[10]);
+    qw = (m[8] - m[2]) / s;
+    qx = (m[4] + m[1]) / s;
+    qy = 0.25 * s;
+    qz = (m[9] + m[6]) / s;
+  } else {
+    const s = 2 * Math.sqrt(1 + m[10] - m[0] - m[5]);
+    qw = (m[1] - m[4]) / s;
+    qx = (m[8] + m[2]) / s;
+    qy = (m[9] + m[6]) / s;
+    qz = 0.25 * s;
+  }
+
+  return [qx, qy, qz, qw];
+}

package/modules/xr/src/debug.ts

@@ -0,0 +1,59 @@
+import { isXRAvailable, isXRGPUBindingAvailable, isVRSupported } from "./session";
+import type { XRModule } from "./xr-module";
+
+export interface XRDebugInfo {
+  xrAvailable: boolean;
+  xrGPUBindingAvailable: boolean;
+  vrSupported: boolean;
+  sessionState: string;
+  active: boolean;
+  controllerCount: number;
+  headPosition: [number, number, number];
+  headQuaternion: [number, number, number, number];
+}
+
+export function getXRDebugInfo(plugin: XRModule): XRDebugInfo {
+  return {
+    xrAvailable: isXRAvailable(),
+    xrGPUBindingAvailable: isXRGPUBindingAvailable(),
+    vrSupported: false,
+    sessionState: plugin.getSessionManager().getState(),
+    active: plugin.isActive(),
+    controllerCount: plugin.getInputMapper().getControllerCount(),
+    headPosition: plugin.getHeadPose().position,
+    headQuaternion: plugin.getHeadPose().quaternion,
+  };
+}
+
+export async function checkXRSupport(): Promise<{ available: boolean; vrSupported: boolean; gpuBinding: boolean; message: string }> {
+  const available = isXRAvailable();
+  const gpuBinding = isXRGPUBindingAvailable();
+  const vrSupported = available ? await isVRSupported() : false;
+
+  let message: string;
+  if (!available) {
+    message = "WebXR API not available. Use a WebXR-compatible browser (Chrome/Edge with WebXR support).";
+  } else if (!gpuBinding) {
+    message = "XRGPUBinding not available. Enable chrome://flags/#webxr-incubations for WebGPU-native XR rendering.";
+  } else if (!vrSupported) {
+    message = "Immersive VR not supported. Connect a VR headset or use a WebXR emulator.";
+  } else {
+    message = "WebXR VR is ready.";
+  }
+
+  return { available, vrSupported, gpuBinding, message };
+}
+
+export function formatXRDebugInfo(info: XRDebugInfo): string {
+  const lines = [
+    `XR Available: ${info.xrAvailable ? "YES" : "NO"}`,
+    `XRGPU Binding: ${info.xrGPUBindingAvailable ? "YES" : "NO"}`,
+    `VR Supported: ${info.vrSupported ? "YES" : "NO"}`,
+    `Session State: ${info.sessionState}`,
+    `Active: ${info.active ? "YES" : "NO"}`,
+    `Controllers: ${info.controllerCount}`,
+    `Head Pos: [${info.headPosition[0].toFixed(3)}, ${info.headPosition[1].toFixed(3)}, ${info.headPosition[2].toFixed(3)}]`,
+    `Head Quat: [${info.headQuaternion[0].toFixed(3)}, ${info.headQuaternion[1].toFixed(3)}, ${info.headQuaternion[2].toFixed(3)}, ${info.headQuaternion[3].toFixed(3)}]`,
+  ];
+  return lines.join("\n");
+}