@downdraft/engine 0.0.0 → 0.1.0

package/libraries/gamepad/src/hub.ts

@@ -0,0 +1,206 @@
+// ============================================================================
+// GamepadHub — engine-native gamepad device API over the 'gamepad-devices'
+// SAB channel. Runtime-agnostic: reads whatever producer wrote the channel
+// (native downdraft_gamepad cdylib today; other producers possible).
+//
+// This is the object games and UI toolkits consume — an evented, per-device
+// API. Do NOT polyfill navigator.getGamepads() on native; that API can't
+// express hotplug ordering, battery, or device identity.
+// ============================================================================
+
+import {
+  GamepadDevicesChannel,
+  GamepadDevicesReader,
+  GAMEPAD_MAX_SLOTS,
+  PAD_FLAG,
+  PAD_BATTERY_UNKNOWN,
+  PAD_BATTERY_WIRED,
+  type GamepadDeviceSlot,
+  type PadTypeValue,
+  type PadConnTypeValue,
+} from "@downdraft/engine/sab/gamepad-devices";
+import { glyphFor, type GlyphResult } from "./glyphs";
+
+export interface GamepadDeviceInfo {
+  slot: number;
+  name: string;
+  padType: PadTypeValue;
+  connType: PadConnTypeValue;
+  vendorId: number;
+  productId: number;
+  /** Linux /dev/input/eventN index; -1 when unknown. */
+  eventNode: number;
+  ffSupported: boolean;
+}
+
+/** A live view of one device slot. Cheap to construct — wraps the reader. */
+export class GamepadDevice {
+  constructor(
+    private reader: GamepadDevicesReader,
+    private hub: GamepadHub,
+    readonly info: GamepadDeviceInfo,
+  ) {}
+
+  private state(): GamepadDeviceSlot | null {
+    return this.reader.readSlot(this.info.slot);
+  }
+
+  get slot(): number {
+    return this.info.slot;
+  }
+
+  get connected(): boolean {
+    return this.state() !== null;
+  }
+
+  /** Battery 0..100, or null when unknown/wired. */
+  get batteryPercent(): number | null {
+    const s = this.state();
+    if (!s) return null;
+    if (s.battery === PAD_BATTERY_UNKNOWN || s.battery === PAD_BATTERY_WIRED) return null;
+    return s.battery;
+  }
+
+  get charging(): boolean {
+    const s = this.state();
+    return s !== null && (s.flags & PAD_FLAG.CHARGING) !== 0;
+  }
+
+  /** RSSI 0..100 (JS sysfs enrichment), null when unknown. */
+  get signalPercent(): number | null {
+    const s = this.state();
+    if (!s || s.rssi === 0xff) return null;
+    return s.rssi;
+  }
+
+  /** Is a W3C-standard button bit currently held? */
+  pressed(bit: number): boolean {
+    const s = this.state();
+    if (!s) return false;
+    return bit < 32
+      ? (s.buttonsLo & (1 << bit)) !== 0
+      : (s.buttonsHi & (1 << (bit - 32))) !== 0;
+  }
+
+  /** Raw axis value: lx ly rx ry lt rt dpadX dpadY (0..7). */
+  axis(i: number): number {
+    const s = this.state();
+    return s ? s.axes[i] : 0;
+  }
+
+  /** All 8 axes, copied into `out` when provided. */
+  axes(out?: Float32Array): Float32Array {
+    const s = this.state();
+    const dst = out ?? new Float32Array(8);
+    if (s) dst.set(s.axes);
+    else dst.fill(0);
+    return dst;
+  }
+
+  /** Glyph descriptor for a button bit on this pad type. */
+  glyphFor(bit: number): GlyphResult {
+    return glyphFor(this.info.padType, bit);
+  }
+
+  /** Rumble (dual-motor). Requires the host to have provided a rumble hook. */
+  rumble(weak: number, strong: number, ms: number): void {
+    this.hub.rumble(this.info.slot, weak, strong, ms);
+  }
+}
+
+export interface GamepadHubOptions {
+  /**
+   * Host-provided rumble hook (slot, weak 0..65535, strong 0..65535, ms).
+   * On the native runtime platform-native wires this to dd_pad_rumble.
+   */
+  rumble?: (slot: number, weak: number, strong: number, ms: number) => void;
+}
+
+type HubEvent = "connect" | "disconnect";
+
+/**
+ * Device-table facade. Call `poll()` once per frame (or per UI update) — it
+ * diffs the connected mask and emits connect/disconnect events.
+ */
+export class GamepadHub {
+  private reader: GamepadDevicesReader;
+  private devices = new Map<number, GamepadDevice>();
+  private listeners: Record<HubEvent, ((dev: GamepadDevice) => void)[]> = {
+    connect: [],
+    disconnect: [],
+  };
+  private opts: GamepadHubOptions;
+  private lastSeq = -1;
+
+  constructor(sab: SharedArrayBuffer, opts: GamepadHubOptions = {}) {
+    this.reader = new GamepadDevicesReader(sab);
+    this.opts = opts;
+  }
+
+  isValid(): boolean {
+    return this.reader.isValid();
+  }
+
+  on(event: HubEvent, cb: (dev: GamepadDevice) => void): () => void {
+    this.listeners[event].push(cb);
+    return () => {
+      const arr = this.listeners[event];
+      const i = arr.indexOf(cb);
+      if (i >= 0) arr.splice(i, 1);
+    };
+  }
+
+  /** Snapshot the device table; emits connect/disconnect on changes. */
+  poll(): void {
+    const mask = this.reader.getConnectedMask();
+    for (let slot = 0; slot < GAMEPAD_MAX_SLOTS; slot++) {
+      const connected = (mask & (1 << slot)) !== 0;
+      const existing = this.devices.get(slot);
+
+      if (connected && !existing) {
+        const s = this.reader.readSlot(slot);
+        if (!s) continue;
+        const dev = new GamepadDevice(this.reader, this, {
+          slot,
+          name: s.name,
+          padType: s.padType,
+          connType: s.connType,
+          vendorId: s.vendorId,
+          productId: s.productId,
+          eventNode: s.eventNode,
+          ffSupported: (s.flags & PAD_FLAG.FF_SUPPORTED) !== 0,
+        });
+        this.devices.set(slot, dev);
+        for (const cb of this.listeners.connect) cb(dev);
+      } else if (!connected && existing) {
+        this.devices.delete(slot);
+        for (const cb of this.listeners.disconnect) cb(existing);
+      }
+    }
+    this.lastSeq = this.reader.getSequence();
+  }
+
+  /** Sequence counter from the channel header — bumped once per native pass. */
+  get sequence(): number {
+    return this.reader.getSequence();
+  }
+
+  /** Whether new state has been written since the last poll. */
+  hasChanged(): boolean {
+    return this.reader.getSequence() !== this.lastSeq;
+  }
+
+  /** Currently-connected devices, slot order. */
+  list(): GamepadDevice[] {
+    this.poll();
+    return [...this.devices.values()].sort((a, b) => a.slot - b.slot);
+  }
+
+  device(slot: number): GamepadDevice | undefined {
+    return this.devices.get(slot);
+  }
+
+  rumble(slot: number, weak: number, strong: number, ms: number): void {
+    this.opts.rumble?.(slot, weak, strong, ms);
+  }
+}

package/libraries/gamepad/src/index.ts

@@ -0,0 +1,22 @@
+// Public API for @downdraft/engine/libraries/gamepad
+
+export { getHostGamepadReader, writePadToInput } from "./feed-input";
+export type { PadKeyBinding } from "./feed-input";
+export { isAuxDeviceName, isLikelyGamepadName } from "./filters";
+export { glyphFor } from "./glyphs";
+export type { GlyphResult } from "./glyphs";
+export { GamepadDevice, GamepadHub } from "./hub";
+export type { GamepadDeviceInfo, GamepadHubOptions } from "./hub";
+export { GamepadHubTok, GamepadLib, GamepadSourceTok } from "./library";
+export type { GamepadLibConfig } from "./library";
+export { GAMEPAD_DEVICES_SAB_NAME, gamepadDevicesSabSize, SabGamepadSource } from "./source-sab";
+export { SysfsGamepadEnricher } from "./sysfs-enrich";
+export type { EnrichResult } from "./sysfs-enrich";
+
+// Re-export the channel contract for convenience.
+export {
+    GAMEPAD_MAX_SLOTS, GamepadDevicesChannel, GamepadDevicesHostMetaWriter, GamepadDevicesReader, GP_AXIS, GP_BTN, PAD_BATTERY_UNKNOWN,
+    PAD_BATTERY_WIRED, PAD_FLAG, PadConnType, PadType
+} from "@downdraft/engine/sab/gamepad-devices";
+export type { GamepadDeviceSlot, PadConnTypeValue, PadTypeValue } from "@downdraft/engine/sab/gamepad-devices";
+

package/libraries/gamepad/src/library.ts

@@ -0,0 +1,68 @@
+// ============================================================================
+// GamepadLib — declarative engine library descriptor for gamepad support.
+//
+// Games declare `libraries: [GamepadLib]` in their GameModule. The descriptor
+// provides a GamepadHub (device discovery/battery/rumble/glyphs) and a
+// GamepadSource for LocalPlayerManager wiring.
+//
+// SAB resolution order:
+//   1. config.sab — caller-provided 'gamepad-devices' buffer
+//   2. globalThis.__ddGamepad.sab — set by platform-native's host when the
+//      downdraft_gamepad cdylib is loaded (already attached to the native
+//      worker, so reads are live immediately)
+//   3. fresh allocation — tests/browsers without a backend (empty table;
+//      still valid for wiring against future sources)
+// ============================================================================
+
+import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import type { GamepadSource } from "@downdraft/engine/input/local-player-manager";
+import { GamepadDevicesChannel } from "@downdraft/engine/sab/gamepad-devices";
+import { GamepadHub, type GamepadHubOptions } from "./hub";
+import { SabGamepadSource } from "./source-sab";
+
+export interface GamepadLibConfig {
+  /** Pre-attached 'gamepad-devices' SAB (usually supplied by the host). */
+  sab?: SharedArrayBuffer;
+  /** Host rumble hook — defaults to __ddGamepad.rumble on native. */
+  rumble?: GamepadHubOptions["rumble"];
+}
+
+/** Token for the renderer-side GamepadHub (device discovery, battery, rumble). */
+export const GamepadHubTok = resourceToken<GamepadHub>("gamepad:hub");
+/** Token for the GamepadSource to install via LocalPlayerManager.setGamepadSource(). */
+export const GamepadSourceTok = resourceToken<GamepadSource>("gamepad:source");
+
+function resolveSab(config: GamepadLibConfig): SharedArrayBuffer {
+  if (config.sab) return config.sab;
+  const host = (globalThis as { __ddGamepad?: { sab?: SharedArrayBuffer } }).__ddGamepad;
+  if (host?.sab) return host.sab;
+  return GamepadDevicesChannel.allocate();
+}
+
+function resolveRumble(config: GamepadLibConfig): GamepadHubOptions["rumble"] {
+  if (config.rumble) return config.rumble;
+  const host = (globalThis as { __ddGamepad?: { rumble?: GamepadHubOptions["rumble"] } }).__ddGamepad;
+  return host?.rumble?.bind(host);
+}
+
+export const GamepadLib: EngineLibrary<GamepadLibConfig, unknown, { hub: GamepadHub; source: SabGamepadSource }> = {
+  name: "gamepad",
+  version: "1.0.0",
+
+  // The channel buffer is host-supplied (pre-attached to the native worker);
+  // we don't declare it in sabChannels — LibraryHost would allocate a second,
+  // unattached buffer.
+  provides: [GamepadHubTok, GamepadSourceTok],
+
+  renderer: {
+    create(config, ctx) {
+      const sab = resolveSab(config);
+      const hub = new GamepadHub(sab, { rumble: resolveRumble(config) });
+      const source = new SabGamepadSource(sab);
+      ctx.provide(GamepadHubTok, hub);
+      ctx.provide(GamepadSourceTok, source);
+      return { hub, source };
+    },
+    dispose() {},
+  },
+};

package/libraries/gamepad/src/source-sab.ts

@@ -0,0 +1,70 @@
+// ============================================================================
+// SabGamepadSource — core GamepadSource implementation over the
+// 'gamepad-devices' channel. Install via LocalPlayerManager.setGamepadSource()
+// on the native runtime.
+// ============================================================================
+
+import type { GamepadSnapshot, GamepadSource } from "@downdraft/engine/input/local-player-manager";
+import {
+    GAMEPAD_MAX_SLOTS,
+    GamepadDevicesChannel,
+    GamepadDevicesReader,
+} from "@downdraft/engine/sab/gamepad-devices";
+
+export class SabGamepadSource implements GamepadSource {
+  private reader: GamepadDevicesReader;
+  private connectCbs: ((index: number) => void)[] = [];
+  private disconnectCbs: ((index: number) => void)[] = [];
+  private knownMask = 0;
+
+  constructor(sab: SharedArrayBuffer) {
+    this.reader = new GamepadDevicesReader(sab);
+  }
+
+  listConnected(): number[] {
+    const mask = this.reader.getConnectedMask();
+    this.diffAndEmit(mask);
+    const out: number[] = [];
+    for (let i = 0; i < GAMEPAD_MAX_SLOTS; i++) {
+      if (mask & (1 << i)) out.push(i);
+    }
+    return out;
+  }
+
+  read(index: number): GamepadSnapshot | null {
+    const s = this.reader.readSlot(index);
+    if (!s) return null;
+    return { buttonsLo: s.buttonsLo >>> 0, buttonsHi: s.buttonsHi >>> 0, axes: Array.from(s.axes) };
+  }
+
+  onConnect(cb: (index: number) => void): void {
+    this.connectCbs.push(cb);
+  }
+
+  onDisconnect(cb: (index: number) => void): void {
+    this.disconnectCbs.push(cb);
+  }
+
+  /** Poll-driven connect/disconnect: the native writer updates the mask at
+   *  250Hz, so events arrive on the next read/listConnected call. */
+  private diffAndEmit(mask: number): void {
+    const changed = mask ^ this.knownMask;
+    if (changed === 0) return;
+    for (let i = 0; i < GAMEPAD_MAX_SLOTS; i++) {
+      if (!(changed & (1 << i))) continue;
+      if (mask & (1 << i)) {
+        for (const cb of this.connectCbs) cb(i);
+      } else {
+        for (const cb of this.disconnectCbs) cb(i);
+      }
+    }
+    this.knownMask = mask;
+  }
+}
+
+export const GAMEPAD_DEVICES_SAB_NAME = "gamepad-devices";
+
+/** Byte size of a 'gamepad-devices' channel allocation. */
+export function gamepadDevicesSabSize(): number {
+  return GamepadDevicesChannel.allocate().byteLength;
+}

package/libraries/gamepad/src/sysfs-enrich.ts

@@ -0,0 +1,138 @@
+// ============================================================================
+// SysfsGamepadEnricher — Linux sysfs enrichment for the 'gamepad-devices'
+// channel's JS-owned hostMeta field. Ported from Ember's evdev.ts sysfs
+// probing: Bluetooth RSSI (walk up the sysfs tree) + power_supply battery.
+//
+// Host-side only — uses node:fs. Wire in platform-native's host services and
+// call `enrich()` on a ~1Hz timer; it writes rssi into each slot's hostMeta.
+// ============================================================================
+
+import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import {
+  GamepadDevicesHostMetaWriter,
+  PadConnType,
+  type GamepadDeviceSlot,
+} from "@downdraft/engine/sab/gamepad-devices";
+
+const MAC_RE = /^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}/;
+
+async function readSysfsText(path: string): Promise<string | null> {
+  try {
+    if (existsSync(path)) return (await fs.readFile(path, "utf-8")).trim();
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+async function readSysfsInt(path: string): Promise<number | undefined> {
+  const text = await readSysfsText(path);
+  if (text === null) return undefined;
+  const n = parseInt(text, 10);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+/** Walk up the sysfs tree looking for a bluetooth device RSSI (dBm → 0..100). */
+async function findBluetoothRssi(inputSysPath: string): Promise<number | undefined> {
+  try {
+    let cur = await fs.realpath(inputSysPath);
+    for (let depth = 0; depth < 6; depth++) {
+      const rssi = await readSysfsInt(join(cur, "rssi"));
+      if (rssi !== undefined) {
+        const clamped = Math.max(-90, Math.min(-30, rssi));
+        return Math.round(((clamped + 90) / 60) * 100);
+      }
+      cur = await fs.realpath(join(cur, ".."));
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/** Battery % for a Bluetooth MAC-matched /sys/class/power_supply entry. */
+async function findBatteryLevel(macHint: string | null): Promise<number | undefined> {
+  if (!macHint) return undefined;
+  try {
+    const psDir = "/sys/class/power_supply";
+    if (!existsSync(psDir)) return undefined;
+    for (const entry of await fs.readdir(psDir)) {
+      const macPath = join(psDir, entry, "mac");
+      if (existsSync(macPath)) {
+        const mac = (await fs.readFile(macPath, "utf-8")).trim().toLowerCase();
+        if (mac === macHint.toLowerCase()) {
+          return readSysfsInt(join(psDir, entry, "capacity"));
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+export interface EnrichResult {
+  slot: number;
+  rssi?: number;
+  battery?: number;
+  connectionType?: "wired" | "bluetooth" | "dongle";
+  physPath?: string;
+  driverName?: string;
+}
+
+/**
+ * Enriches gamepad-device slots with data gilrs doesn't expose (RSSI) and
+ * refines connection classification via phys-path heuristics. Pure reads +
+ * hostMeta writes; safe to run on a timer.
+ */
+export class SysfsGamepadEnricher {
+  private writer: GamepadDevicesHostMetaWriter;
+
+  constructor(sab: SharedArrayBuffer) {
+    this.writer = new GamepadDevicesHostMetaWriter(sab);
+  }
+
+  /** Enrich a batch of connected slots. */
+  async enrich(slots: GamepadDeviceSlot[]): Promise<EnrichResult[]> {
+    if (process.platform !== "linux") return [];
+    const out: EnrichResult[] = [];
+    for (const s of slots) {
+      if (s.eventNode < 0) continue;
+      const r = await this.enrichSlot(s);
+      out.push(r);
+    }
+    return out;
+  }
+
+  async enrichSlot(s: GamepadDeviceSlot): Promise<EnrichResult> {
+    const sysPath = `/sys/class/input/event${s.eventNode}/device`;
+    const phys = await readSysfsText(join(sysPath, "phys"));
+    const result: EnrichResult = { slot: s.slot, physPath: phys ?? undefined };
+
+    // Connection-type refinement (Ember's detectConnectionType heuristics).
+    const p = (phys ?? "").trim();
+    if (MAC_RE.test(p) || p.toLowerCase().includes("bluetooth")) {
+      result.connectionType = "bluetooth";
+    } else if (s.vendorId === 0x054c && !p.startsWith("usb-")) {
+      result.connectionType = "bluetooth"; // hid-sony non-USB
+    } else if (p.startsWith("usb-")) {
+      result.connectionType = s.connType === PadConnType.DONGLE ? "dongle" : "wired";
+    }
+
+    let rssi: number | undefined;
+    let battery: number | undefined;
+    if (result.connectionType === "bluetooth") {
+      rssi = await findBluetoothRssi(sysPath);
+      if (phys && MAC_RE.test(phys)) battery = await findBatteryLevel(phys);
+    }
+
+    if (rssi !== undefined) {
+      result.rssi = rssi;
+      this.writer.setHostMeta(s.slot, rssi, 0);
+    }
+    if (battery !== undefined) result.battery = battery;
+    return result;
+  }
+}

package/libraries/gaussian-splats/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/libraries/gaussian-splats`
+
+Gaussian splatting renderer — loads and draws .ply/.splat radiance-field captures as a render pass.
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/gaussian-splats
+```
+
+## Key exports
+
+- `DEFAULT_MAX_SPLATS_PER_TILE`
+- `DEFAULT_TILE_SIZE`
+- `GaussianSplatRenderer`
+- `GaussianSplatsLib`
+- `GaussianSplatsTok`
+- `GpuSplatSorter`
+- `MAX_SH_DEGREE`
+- `SH_COEFFS_PER_CHANNEL`
+- `SH_COEFFS_TOTAL`
+- `SH_EVAL_WGSL`
+- …and 11 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.