@downdraft/engine 0.0.0 → 0.1.0

package/mcp/src/undo-redo.ts

@@ -0,0 +1,77 @@
+import { createLogger } from "@downdraft/engine";
+import type { EngineContext } from "./engine-context";
+
+const log = createLogger();
+
+export interface UndoAction {
+  description: string;
+  undo: () => void;
+  redo: () => void;
+}
+
+export class UndoRedoManager {
+  private undoStack: UndoAction[] = [];
+  private redoStack: UndoAction[] = [];
+  private maxStack: number = 100;
+  private ctx: EngineContext;
+
+  constructor(ctx: EngineContext) {
+    this.ctx = ctx;
+  }
+
+  execute(action: UndoAction): void {
+    this.undoStack.push(action);
+    if (this.undoStack.length > this.maxStack) {
+      this.undoStack.shift();
+    }
+    this.redoStack.length = 0;
+  }
+
+  undo(): boolean {
+    const action = this.undoStack.pop();
+    if (!action) return false;
+    try {
+      action.undo();
+      this.redoStack.push(action);
+      return true;
+    } catch (e) {
+      log.error("UndoRedo", `Undo failed: ${e}`);
+      this.undoStack.push(action);
+      return false;
+    }
+  }
+
+  redo(): boolean {
+    const action = this.redoStack.pop();
+    if (!action) return false;
+    try {
+      action.redo();
+      this.undoStack.push(action);
+      return true;
+    } catch (e) {
+      log.error("UndoRedo", `Redo failed: ${e}`);
+      this.redoStack.push(action);
+      return false;
+    }
+  }
+
+  canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  getHistory(): { undo: string[]; redo: string[] } {
+    return {
+      undo: this.undoStack.map((a) => a.description),
+      redo: this.redoStack.map((a) => a.description),
+    };
+  }
+
+  clear(): void {
+    this.undoStack.length = 0;
+    this.redoStack.length = 0;
+  }
+}

package/modules/camera-controls/README.md

@@ -0,0 +1,20 @@
+# `@downdraft/engine/modules/camera-controls`
+
+Camera control module — orbit/fly/follow controllers with input binding and typed DI tokens.
+
+## Install
+
+```sh
+bun add @downdraft/engine/modules/camera-controls
+```
+
+## Key exports
+
+- `Camera`
+- `CameraController`
+- `CameraControlsModule`
+- `CameraControlsOptions`
+- `createCameraController`
+- `createCameraControlsModule`
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/modules/camera-controls/src/index.ts

@@ -0,0 +1,161 @@
+// ============================================================================
+// Camera Controls Module — orbit/pan/zoom camera controller as a renderer plugin
+//
+// Registers a `CameraController` as the active camera provider on the
+// `RendererModuleContext`, wires orbit/pan/zoom input from the shared input
+// bus, and disposes cleanly on unload. This is the engine-builtin replacement
+// for game-local `OrbitCamera` classes.
+//
+// For games with bespoke render loops (no `GameRenderer`), use
+// `createCameraController(inputBus, opts)` instead — it returns a bare
+// `CameraController` wired to a `RendererInputBus` without the plugin wrapper.
+// ============================================================================
+
+import {
+    Camera,
+    CameraController,
+    type CameraControllerOptions,
+    type OrbitInputOptions,
+    type RendererInputBus,
+    type RendererModule,
+} from "@downdraft/engine";
+
+export interface CameraControlsOptions {
+  /** Camera controller options (lerp, default camera id). */
+  controller?: CameraControllerOptions;
+  /** Orbit input sensitivity / clamps. */
+  orbit?: OrbitInputOptions;
+  /** Initial camera setup (applied to the default camera on registration). */
+  initialCamera?: {
+    /** Camera id; defaults to "main". */
+    id?: string;
+    position?: [number, number, number];
+    target?: [number, number, number];
+    fov?: number;
+    near?: number;
+    far?: number;
+  };
+}
+
+/**
+ * Creates a configured `CameraController` and wires it to a
+ * `RendererInputBus` for orbit/pan/zoom input. For games that use
+ * `GameRenderer` + `RendererModuleHost`, prefer `createCameraControlsModule`
+ * instead — it handles registration and disposal automatically.
+ *
+ * The caller is responsible for:
+ *  - calling `controller.setAspect(w, h)` on resize
+ *  - calling `controller.update(dt)` each frame (if lerp is enabled)
+ *  - calling `controller.unbindOrbit()` + `controller.dispose()` on teardown
+ *
+ * @example
+ * ```ts
+ * const inputBus = new RendererInputBusImpl(canvas);
+ * const controller = createCameraController(inputBus, {
+ *   initialCamera: { position: [0, 5, 10], target: [0, 0, 0], fov: 45 },
+ *   orbit: { minDistance: 0.1, maxDistance: 500 },
+ * });
+ * ```
+ */
+export function createCameraController(
+  inputBus: RendererInputBus,
+  opts: CameraControlsOptions = {},
+): CameraController {
+  const camId = opts.initialCamera?.id ?? "main";
+  const cam = new Camera();
+  if (opts.initialCamera) {
+    const ic = opts.initialCamera;
+    if (ic.position) {
+      if (ic.position.length !== 3) {
+        throw new RangeError(`initialCamera.position must have length 3, got ${ic.position.length}`);
+      }
+      cam.setPosition(...ic.position);
+    }
+    if (ic.target) {
+      if (ic.target.length !== 3) {
+        throw new RangeError(`initialCamera.target must have length 3, got ${ic.target.length}`);
+      }
+      cam.setTarget(...ic.target);
+    }
+    if (ic.fov !== undefined) {
+      if (!(ic.fov > 0)) {
+        throw new RangeError(`initialCamera.fov must be > 0, got ${ic.fov}`);
+      }
+      cam.setFov(ic.fov);
+    }
+    if (ic.near !== undefined) {
+      if (!(ic.near > 0)) {
+        throw new RangeError(`initialCamera.near must be > 0, got ${ic.near}`);
+      }
+      cam.near = ic.near;
+    }
+    if (ic.far !== undefined) {
+      if (ic.near !== undefined && !(ic.far > ic.near)) {
+        throw new RangeError(`initialCamera.far (${ic.far}) must be > near (${ic.near})`);
+      }
+      cam.far = ic.far;
+    }
+  }
+
+  const controller = new CameraController({
+    ...opts.controller,
+    defaultCameraId: camId,
+  });
+  // The constructor's defaultCameraId creates its own Camera; replace it
+  // with our configured one.
+  controller.removeCamera(camId);
+  controller.addCamera(camId, cam);
+  controller.setActive(camId);
+
+  // Wire orbit/pan/zoom input from the supplied input bus.
+  controller.bindOrbit(inputBus, opts.orbit);
+
+  return controller;
+}
+
+/**
+ * Creates a `RendererModule` that registers an orbit camera controller.
+ * The controller is accessible via `ctx.getCameraController()` after
+ * registration, or by capturing the return value of `createCameraControlsModule`.
+ */
+export function createCameraControlsModule(
+  opts: CameraControlsOptions = {},
+): RendererModule & { getController: () => CameraController | null } {
+  let controller: CameraController | null = null;
+
+  const plugin: RendererModule & { getController: () => CameraController | null } = {
+    name: "camera-controls",
+    version: "0.1.0",
+
+    register(ctx) {
+      controller = createCameraController(ctx.getInputBus(), opts);
+
+      // Register as the active camera provider.
+      ctx.setCameraController(controller);
+
+      // Clean up on dispose.
+      ctx.onDispose(() => {
+        controller?.unbindOrbit();
+        controller?.dispose();
+        controller = null;
+        ctx.setCameraController(null);
+      });
+    },
+
+    getController() {
+      return controller;
+    },
+  };
+
+  return plugin;
+}
+
+/**
+ * Convenience default instance with sensible orbit defaults. Games that need
+ * custom sensitivity/lerp should use `createCameraControlsModule(opts)`.
+ */
+export const CameraControlsModule: RendererModule = createCameraControlsModule();
+
+export { Camera, CameraController } from "@downdraft/engine";
+export type { CameraControllerOptions, OrbitInputOptions } from "@downdraft/engine";
+

package/modules/controller-ui/src/index.ts

@@ -0,0 +1,164 @@
+// ============================================================================
+// controller-ui — engine-provided controller settings screen.
+//
+//   renderer.useRendererModule(createHtmlUi({ build(ui) { ... } }));
+//   renderer.useRendererModule(createControllerUi());
+//   // game code: ui.open() from a menu action, or bind to START+SELECT, etc.
+//
+// A full "Controllers" settings panel built on html-ui + html-ui-kit:
+// device list (name, pad type, battery), a live button/axis test diagram,
+// and per-device rumble test. Because it mounts through HtmlUiContext.mount,
+// controller nav + OSK + focus zones come free — this module is also the
+// dogfood proof for the nav stack.
+// ============================================================================
+
+import { createLogger, resourceToken, type RendererModule } from "@downdraft/engine";
+import { GamepadHubTok, type GamepadDevice } from "@downdraft/engine/libraries/gamepad";
+import { esc, kitStyleTag, tvCss } from "@downdraft/engine/libraries/html-ui-kit";
+import { HtmlUiTok, type UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+
+const log = createLogger("info");
+
+export interface ControllerUi {
+  open(): void;
+  close(): void;
+  readonly isOpen: boolean;
+  readonly panel: UiPanelHandle | null;
+}
+export const ControllerUiTok = resourceToken<ControllerUi>("controller-ui");
+
+const BTN_LABELS: Array<[bit: number, label: string]> = [
+  [GP_BTN.SOUTH, "A"], [GP_BTN.EAST, "B"], [GP_BTN.WEST, "X"], [GP_BTN.NORTH, "Y"],
+  [GP_BTN.LEFT_SHOULDER, "LB"], [GP_BTN.RIGHT_SHOULDER, "RB"],
+  [GP_BTN.LEFT_TRIGGER_BTN, "LT"], [GP_BTN.RIGHT_TRIGGER_BTN, "RT"],
+  [GP_BTN.SELECT, "SEL"], [GP_BTN.START, "STR"], [GP_BTN.HOME, "HOME"],
+  [GP_BTN.LEFT_STICK, "L3"], [GP_BTN.RIGHT_STICK, "R3"],
+  [GP_BTN.DPAD_UP, "▲"], [GP_BTN.DPAD_DOWN, "▼"], [GP_BTN.DPAD_LEFT, "◀"], [GP_BTN.DPAD_RIGHT, "▶"],
+];
+const AXIS_LABELS = ["LX", "LY", "RX", "RY", "LT", "RT", "DX", "DY"];
+
+function screenMarkup(): string {
+  const btns = BTN_LABELS.map(([bit, lbl]) =>
+    `<div class="dd-btn ctl-btn" id="ctl-btn-${bit}" data-nav data-i="${bit}">${lbl}</div>`).join("");
+  const axes = AXIS_LABELS.map((lbl, i) =>
+    `<div class="ctl-axis"><div class="dd-label">${lbl}</div>` +
+    `<div class="dd-progress" style="flex:1"><div class="dd-pfill" id="ctl-ax-${i}" data-part="fill" style="width:0%"></div></div>` +
+    `<div class="dd-label" id="ctl-av-${i}" style="width:44px;text-align:right">0.00</div></div>`).join("");
+  return `
+<div style="height:100%;display:flex;flex-direction:column;background:var(--dd-bg)">
+  <div class="dd-row" style="padding:18px 22px 10px">
+    <div style="font-size:22px;flex:1">Controllers</div>
+    <div class="dd-btn" data-nav data-action="ctlui:close">Close</div>
+  </div>
+  <div id="ctl-devs" class="dd-col" style="padding:0 22px 12px;gap:6px"></div>
+  <div class="dd-panel" style="margin:0 22px 12px;flex:0 0 auto">
+    <div class="dd-section">BUTTON TEST</div>
+    <div style="display:flex;flex-wrap:wrap;gap:8px">${btns}</div>
+  </div>
+  <div class="dd-panel" style="margin:0 22px 12px;flex:1;display:flex;flex-direction:column;gap:8px">
+    <div class="dd-row"><div class="dd-section" style="flex:1">AXES</div>
+      <div class="dd-btn" data-nav data-action="ctlui:rumble">Rumble test</div></div>
+    ${axes}
+  </div>
+</div>`;
+}
+
+const CSS = `
+.ctl-dev-row { display:flex; align-items:center; gap:12px; padding:10px 12px;
+  border:1px solid var(--dd-line); border-radius:6px; background:var(--dd-panel); }
+.ctl-dev-row[data-nav-focus="1"] { border-color:var(--dd-accent); background:var(--dd-panel2); }
+.ctl-dev-name { flex:1; font-size:15px; }
+.ctl-axis { display:flex; align-items:center; gap:10px; }
+.ctl-btn[data-on="true"] { background:var(--dd-accent-bg); color:var(--dd-accent); border-color:var(--dd-accent); }
+`;
+
+export function createControllerUi(): RendererModule {
+  return {
+    name: "controller-ui",
+    version: "1.0.0",
+    requires: [HtmlUiTok],
+    provides: [ControllerUiTok],
+    register(ctx) {
+      const ui = ctx.inject(HtmlUiTok);
+      const hub = ctx.injectOptional(GamepadHubTok);
+      let panel: UiPanelHandle | null = null;
+      const api: ControllerUi = {
+        get panel() { return panel; },
+        get isOpen() { return panel !== null; },
+        open() {
+          if (panel) return;
+          const w = ctx.getSurface().clientWidth, h = ctx.getSurface().clientHeight;
+          const pw = Math.min(720, w - 80), ph = Math.min(760, h - 80);
+          panel = ui.mount(`${kitStyleTag()}<style>${tvCss()}${CSS}</style>${screenMarkup()}`, {
+            id: "controller-ui",
+            rect: { x: (w - pw) / 2, y: (h - ph) / 2, w: pw, h: ph },
+            z: 50,
+          });
+          refreshDevices();
+          ui.onAction("ctlui:close", () => api.close());
+          ui.onAction("ctlui:rumble", () => {
+            const dev = selected();
+            if (dev) dev.rumble(32768, 65535, 300);
+          });
+        },
+        close() {
+          panel?.dispose();
+          panel = null;
+        },
+      };
+
+      let sel = 0;
+      function selected(): GamepadDevice | null {
+        const devs = hub?.list() ?? [];
+        return devs[Math.min(sel, Math.max(0, devs.length - 1))] ?? null;
+      }
+      function refreshDevices() {
+        if (!panel) return;
+        const devs = hub?.list() ?? [];
+        const rows = devs.length
+          ? devs.map((d, i) => {
+              const bat = d.batteryPercent;
+              const meta = [
+                d.info.padType ?? "gamepad",
+                bat !== null ? `${bat}%${d.charging ? " ⚡" : ""}` : "wired",
+              ].join(" · ");
+              return `<div class="ctl-dev-row" data-nav data-action="ctlui:sel" data-i="${i}">` +
+                `<div class="ctl-dev-name">${esc(d.info.name)}</div>` +
+                `<div class="dd-label">${esc(meta)}</div></div>`;
+            }).join("")
+          : `<div class="dd-label" style="padding:8px 4px">No controllers connected</div>`;
+        panel.mutate([{ op: "innerHtml", sel: "#ctl-devs", html: rows }]);
+        ui.nav?.invalidate(panel);
+      }
+      ui.onAction?.("ctlui:sel", (d) => { sel = Number(d.i ?? 0); });
+
+      ui.onUpdate(() => {
+        const p = panel;
+        const dev = selected();
+        if (!p || !dev) return;
+        const ops = [];
+        for (const [bit] of BTN_LABELS) {
+          ops.push({ op: "attr", sel: `#ctl-btn-${bit}`, name: "data-on",
+            value: dev.pressed(bit) ? "true" : "false" } as const);
+        }
+        const ax = dev.axes();
+        for (let i = 0; i < AXIS_LABELS.length; i++) {
+          const v = ax[i] ?? 0;
+          const isTrigger = i === GP_AXIS.LEFT_TRIGGER || i === GP_AXIS.RIGHT_TRIGGER;
+          const pct = Math.round((isTrigger ? v : (v + 1) / 2) * 100);
+          ops.push({ op: "style", sel: `#ctl-ax-${i}`, prop: "width", value: `${pct}%` } as const);
+          ops.push({ op: "text", sel: `#ctl-av-${i}`, text: v.toFixed(2) } as const);
+        }
+        p.mutate(ops);
+      });
+
+      hub?.on("connect", refreshDevices);
+      hub?.on("disconnect", refreshDevices);
+
+      ctx.provide(ControllerUiTok, api);
+      ctx.onDispose(() => api.close());
+      log.info("controller-ui", hub ? "ready" : "ready (no gamepad source — screen will show 'No controllers')");
+    },
+  };
+}

package/modules/devtools/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/modules/devtools`
+
+In-engine devtools module — scene inspector, profiling hooks, and the `downdraft doctor` diagnostics panel.
+
+## Install
+
+```sh
+bun add @downdraft/engine/modules/devtools
+```
+
+## Key exports
+
+- `BUILTIN_VIEW_DESCRIPTORS`
+- `BaseSceneInspector`
+- `DEVTOOLS_REALM`
+- `DEVTOOLS_SAB_MAX_FEEDS`
+- `DebugOverlay`
+- `DebugRaycast`
+- `DevToolsDataBridge`
+- `GridRenderer`
+- `HeightRulerRenderer`
+- `LabelOverlay`
+- …and 29 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.