@downdraft/engine 0.0.0 → 0.1.1

package/core/src/render/tracked-render-pass.ts

@@ -0,0 +1,158 @@
+export interface ITrackedRenderPass {
+  readonly drawCalls: number;
+  readonly triangles: number;
+  readonly pipelineSwitches: number;
+  readonly bindGroupChanges: number;
+  readonly bufferRebinds: number;
+  resetStats(): void;
+  setPipeline(pipeline: GPURenderPipeline | unknown): void;
+  setBindGroup(index: number, group: GPUBindGroup | unknown, dynamicOffsets?: number[]): void;
+  setVertexBuffer(slot: number, buffer: GPUBuffer | unknown, offset?: number): void;
+  setIndexBuffer(buffer: GPUBuffer | unknown, format: GPUIndexFormat | unknown, offset?: number): void;
+  draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
+  drawIndexed(indexCount: number, instanceCount?: number, firstIndex?: number, baseVertex?: number, firstInstance?: number): void;
+  drawIndirect(indirectBuffer: GPUBuffer | unknown, indirectOffset?: number): void;
+  drawIndexedIndirect(indirectBuffer: GPUBuffer | unknown, indirectOffset?: number): void;
+  end(): void;
+  getRawPass(): GPURenderPassEncoder | unknown;
+}
+
+export class TrackedRenderPass implements ITrackedRenderPass {
+  private state: {
+    pipeline: GPURenderPipeline | null;
+    bindGroups: Map<number, GPUBindGroup>;
+    vertexBuffers: Map<number, GPUBuffer>;
+    indexBuffer: GPUBuffer | null;
+    indexFormat: GPUIndexFormat | null;
+  } = {
+    pipeline: null,
+    bindGroups: new Map(),
+    vertexBuffers: new Map(),
+    indexBuffer: null,
+    indexFormat: null,
+  };
+  private pass: GPURenderPassEncoder;
+  private _drawCalls: number = 0;
+  private _triangles: number = 0;
+  private _pipelineSwitches: number = 0;
+  private _bindGroupChanges: number = 0;
+  private _bufferRebinds: number = 0;
+
+  constructor(pass: GPURenderPassEncoder) {
+    this.pass = pass;
+  }
+
+  /**
+   * Rebind to a fresh GPURenderPassEncoder and clear stats/state so this
+   * wrapper can be reused instead of allocating one per pass per frame.
+   * (FrameGraph keeps a per-slot pool.)
+   */
+  resetForReuse(pass: GPURenderPassEncoder): void {
+    this.pass = pass;
+    this.state.pipeline = null;
+    this.state.bindGroups.clear();
+    this.state.vertexBuffers.clear();
+    this.state.indexBuffer = null;
+    this.state.indexFormat = null;
+    this._drawCalls = 0;
+    this._triangles = 0;
+    this._pipelineSwitches = 0;
+    this._bindGroupChanges = 0;
+    this._bufferRebinds = 0;
+  }
+
+  get drawCalls(): number {
+    return this._drawCalls;
+  }
+
+  get triangles(): number {
+    return this._triangles;
+  }
+
+  get pipelineSwitches(): number {
+    return this._pipelineSwitches;
+  }
+
+  get bindGroupChanges(): number {
+    return this._bindGroupChanges;
+  }
+
+  get bufferRebinds(): number {
+    return this._bufferRebinds;
+  }
+
+  resetStats(): void {
+    this._drawCalls = 0;
+    this._triangles = 0;
+    this._pipelineSwitches = 0;
+    this._bindGroupChanges = 0;
+    this._bufferRebinds = 0;
+  }
+
+  setPipeline(pipeline: GPURenderPipeline): void {
+    if (this.state.pipeline !== pipeline) {
+      this.pass.setPipeline(pipeline);
+      this.state.pipeline = pipeline;
+      this._pipelineSwitches++;
+    }
+  }
+
+  setBindGroup(index: number, group: GPUBindGroup, dynamicOffsets?: number[]): void {
+    const existing = this.state.bindGroups.get(index);
+    if (existing !== group) {
+      this.pass.setBindGroup(index, group, dynamicOffsets ?? []);
+      this.state.bindGroups.set(index, group);
+      this._bindGroupChanges++;
+    }
+  }
+
+  setVertexBuffer(slot: number, buffer: GPUBuffer, offset: number = 0): void {
+    const existing = this.state.vertexBuffers.get(slot);
+    if (existing !== buffer) {
+      this.pass.setVertexBuffer(slot, buffer, offset);
+      this.state.vertexBuffers.set(slot, buffer);
+      this._bufferRebinds++;
+    }
+  }
+
+  setIndexBuffer(buffer: GPUBuffer, format: GPUIndexFormat, offset: number = 0): void {
+    if (this.state.indexBuffer !== buffer || this.state.indexFormat !== format) {
+      this.pass.setIndexBuffer(buffer, format, offset);
+      this.state.indexBuffer = buffer;
+      this.state.indexFormat = format;
+      this._bufferRebinds++;
+    }
+  }
+
+  draw(vertexCount: number, instanceCount: number = 1, firstVertex: number = 0, firstInstance: number = 0): void {
+    this.pass.draw(vertexCount, instanceCount, firstVertex, firstInstance);
+    this._drawCalls++;
+    this._triangles += Math.floor(vertexCount / 3) * instanceCount;
+  }
+
+  drawIndexed(indexCount: number, instanceCount: number = 1, firstIndex: number = 0, baseVertex: number = 0, firstInstance: number = 0): void {
+    this.pass.drawIndexed(indexCount, instanceCount, firstIndex, baseVertex, firstInstance);
+    this._drawCalls++;
+    this._triangles += Math.floor(indexCount / 3) * instanceCount;
+  }
+
+  drawIndirect(indirectBuffer: GPUBuffer, indirectOffset: number = 0): void {
+    this.pass.drawIndirect(indirectBuffer, indirectOffset);
+    this._drawCalls++;
+    // Indirect arg counts are on the GPU; triangle count is not available synchronously.
+  }
+
+  drawIndexedIndirect(indirectBuffer: GPUBuffer, indirectOffset: number = 0): void {
+    this.pass.drawIndexedIndirect(indirectBuffer, indirectOffset);
+    this._drawCalls++;
+    // Indirect arg counts are on the GPU; triangle count is not available synchronously.
+  }
+
+  end(): void {
+    this.pass.end();
+  }
+
+  getRawPass(): GPURenderPassEncoder {
+    return this.pass;
+  }
+}

package/core/src/render/viewport.ts

@@ -0,0 +1,109 @@
+export interface ViewportRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export type ViewportMode = "split" | "shared";
+
+export class ViewportLayout {
+  static compute(
+    playerCount: number,
+    screenW: number,
+    screenH: number,
+    mode: ViewportMode = "split",
+  ): ViewportRect[] {
+    if (playerCount <= 0) return [];
+    if (mode === "shared" || playerCount === 1) {
+      return fullScreen(playerCount);
+    }
+
+    if (playerCount === 2) {
+      return split2(screenW, screenH);
+    }
+
+    if (playerCount <= 4) {
+      return grid4(screenW, screenH, playerCount);
+    }
+
+    return gridDynamic(screenW, screenH, playerCount);
+  }
+}
+
+function fullScreen(count: number): ViewportRect[] {
+  const rects: ViewportRect[] = [];
+  for (let i = 0; i < count; i++) {
+    rects.push({ x: 0, y: 0, w: 1, h: 1 });
+  }
+  return rects;
+}
+
+function split2(w: number, h: number): ViewportRect[] {
+  if (w >= h) {
+    return [
+      { x: 0, y: 0, w: 0.5, h: 1 },
+      { x: 0.5, y: 0, w: 0.5, h: 1 },
+    ];
+  }
+  return [
+    { x: 0, y: 0, w: 1, h: 0.5 },
+    { x: 0, y: 0.5, w: 1, h: 0.5 },
+  ];
+}
+
+function grid4(w: number, h: number, count: number): ViewportRect[] {
+  const rects: ViewportRect[] = [];
+  const halfW = 0.5;
+  const halfH = 0.5;
+
+  const positions = [
+    { x: 0, y: 0 },
+    { x: halfW, y: 0 },
+    { x: 0, y: halfH },
+    { x: halfW, y: halfH },
+  ];
+
+  for (let i = 0; i < count; i++) {
+    rects.push({
+      x: positions[i].x,
+      y: positions[i].y,
+      w: halfW,
+      h: halfH,
+    });
+  }
+  return rects;
+}
+
+function gridDynamic(w: number, h: number, count: number): ViewportRect[] {
+  const cols = Math.ceil(Math.sqrt(count));
+  const rows = Math.ceil(count / cols);
+  const cellW = 1 / cols;
+  const cellH = 1 / rows;
+
+  const rects: ViewportRect[] = [];
+  for (let i = 0; i < count; i++) {
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    rects.push({
+      x: col * cellW,
+      y: row * cellH,
+      w: cellW,
+      h: cellH,
+    });
+  }
+  return rects;
+}
+
+export function viewportRectToPixels(
+  rect: ViewportRect,
+  screenW: number,
+  screenH: number,
+): { x: number; y: number; w: number; h: number } {
+  return {
+    x: Math.floor(rect.x * screenW),
+    y: Math.floor(rect.y * screenH),
+    w: Math.floor(rect.w * screenW),
+    h: Math.floor(rect.h * screenH),
+  };
+}

package/core/src/render/wgsl-hmr.ts

@@ -0,0 +1,70 @@
+// ============================================================================
+// wgslHotReload — shader source registry for fine-grained WGSL HMR
+// ============================================================================
+//
+// Zero-dependency module (no imports) to avoid circular dependency concerns.
+// The wgslHmrPlugin (vite) registers shader sources at module-load time and
+// calls reload() when a `*.wgsl?raw` module is hot-updated. Consumers
+// (MaterialLibrary, game pass classes, entity-shaders) subscribe to be
+// notified of changes so they can rebuild GPU pipelines without a full page
+// reload. When there are no subscribers for a given shader, reload() falls
+// back to a full page reload so edits always take effect.
+//
+// In production builds this registry is inert: register() still runs (harmless
+// Map insert) but reload() is never called because import.meta.hot is absent.
+
+export type WgslReloadFn = (newSource: string) => void;
+
+class WgslHotReloadRegistry {
+  private sources = new Map<string, string>();
+  private listeners = new Map<string, Set<WgslReloadFn>>();
+
+  /** Register a shader source by its absolute file path. */
+  register(id: string, source: string): void {
+    this.sources.set(id, source);
+  }
+
+  /** Get the most recently registered source for a shader. */
+  get(id: string): string | undefined {
+    return this.sources.get(id);
+  }
+
+  /**
+   * Subscribe to reload notifications for a shader id.
+   * Returns an unsubscribe function.
+   */
+  subscribe(id: string, fn: WgslReloadFn): () => void {
+    let set = this.listeners.get(id);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(id, set);
+    }
+    set.add(fn);
+    return () => {
+      set!.delete(fn);
+      if (set!.size === 0) this.listeners.delete(id);
+    };
+  }
+
+  /**
+   * Notify subscribers that a shader was reloaded. If there are no
+   * subscribers, fall back to a full page reload so the edit always
+   * takes effect.
+   */
+  reload(id: string, newSource: string): void {
+    this.sources.set(id, newSource);
+    const set = this.listeners.get(id);
+    if (set && set.size > 0) {
+      set.forEach((fn) => fn(newSource));
+    } else {
+      // No fine-grained subscriber — restart so the change is visible. The
+      // host's requestRestart handles native (self-respawn); DOM hosts
+      // fall back to a page reload.
+      const req = (globalThis as any).downdraft?.requestRestart;
+      if (typeof req === "function" && req("WGSL reload — no subscriber")) return;
+      if (typeof window !== "undefined") window.location.reload();
+    }
+  }
+}
+
+export const wgslHotReload = new WgslHotReloadRegistry();

package/core/src/sab/core-input-channel.ts

@@ -0,0 +1,23 @@
+import { defineChannel } from "./define";
+
+export const CoreInputChannel = defineChannel({
+  name: "core-input",
+  magic: 0x434f4950,
+  // v2: gamepadButtons → u32 bitmask pair [lo, hi] (W3C standard order,
+  // GP_BTN_* in gamepad-devices.ts); gamepadAxes → 8 (lx ly rx ry lt rt
+  // dpadX dpadY). Mirrors the multi-input v2 upgrade.
+  version: 2,
+  mode: "record",
+  header: { size: 64, fields: {} },
+  fields: {
+    keys: { type: "i32", count: 8 },
+    mouseX: { type: "f32" },
+    mouseY: { type: "f32" },
+    mouseDeltaX: { type: "f32" },
+    mouseDeltaY: { type: "f32" },
+    mouseButtons: { type: "i32", count: 3 },
+    wheelDelta: { type: "f32" },
+    gamepadButtons: { type: "u32", count: 2 },
+    gamepadAxes: { type: "f32", count: 8 },
+  },
+});

package/core/src/sab/define.ts

@@ -0,0 +1,239 @@
+import { GridReader, GridWriter } from "./grid-buffer";
+import { computeLayout } from "./layout";
+import { RecordReader, RecordWriter } from "./record-buffer";
+import { SlotReader, SlotWriter } from "./slot-buffer";
+import type {
+    ChannelDef,
+    ChannelInstance,
+    ChannelLayout,
+    ChannelReader,
+    ChannelWriter,
+    FieldMap,
+    SlotSectionDef,
+} from "./types";
+
+// ============================================================================
+// Single-writer constraint
+// ============================================================================
+//
+// All SAB channels in the Downdraft engine follow a single-writer-per-region
+// constraint: each buffer region (header, slots, records, grids, input, stats,
+// board) has exactly ONE thread that writes to it. The other thread only reads.
+//
+// This constraint is critical for the SAB polyfill (sab-polyfill.ts), which
+// replaces SharedArrayBuffer with an ArrayBuffer subclass when it is unavailable.
+// The polyfill uses a copy-based buffer-sync protocol (buffer-sync.ts) that
+// copies each side's written regions to the other side via postMessage. If
+// both sides write to the same region, the sync will overwrite one side's
+// writes with stale data from the other, causing unpredictable behavior.
+//
+// When adding a new channel or buffer region:
+//   1. Document which thread writes (sim worker vs main/renderer).
+//   2. Ensure the other thread only reads (use Reader classes, not Writer).
+//   3. Declare the region in the BufferSyncConfig (see buffer-sync.ts).
+//
+// Current channel ownership:
+//   - SimChannel: worker writes (entities, players, header), main reads
+//   - InputChannel: main writes (input), worker reads
+//   - WaterChannel: worker writes, renderer reads
+//   - BoatChannel: worker writes, renderer reads
+//   - GridSimBuffer (sand): worker writes (grid, fields, stats, board),
+//     main writes (input region only — embedded at INPUT_OFFSET)
+//
+// ============================================================================
+
+// --- Type-level inference helpers ---
+
+type HeaderOffsets<Def extends ChannelDef> = {
+  magic: number;
+  version: number;
+  sequence: number;
+} & {
+  [K in keyof Def["header"]["fields"] & string]: number;
+};
+
+type SectionFieldOffsets<S extends SlotSectionDef> = {
+  [K in keyof S["fields"] & string]: number;
+};
+
+type SectionsOffsets<Def extends ChannelDef> =
+  Def extends { sections: infer S extends SlotSectionDef[] }
+    ? {
+        [Section in S[number] as Section["name"]]: {
+          sectionByteOffset: number;
+          slotStride: number;
+          fields: SectionFieldOffsets<Section>;
+        };
+      }
+    : never;
+
+type GridLayerOffsets<Def extends ChannelDef> =
+  Def extends { grid: { layers: infer L } }
+    ? { [K in keyof L & string]: { byteOffset: number; length: number } }
+    : never;
+
+type RecordFieldOffsets<Def extends ChannelDef> =
+  Def extends { fields: infer F extends FieldMap }
+    ? { [K in keyof F & string]: number }
+    : never;
+
+export type ChannelOffsets<Def extends ChannelDef> = {
+  header: HeaderOffsets<Def>;
+} & (Def["mode"] extends "record" ? { fields: RecordFieldOffsets<Def> } : {}) &
+  (Def["mode"] extends "slots" ? { sections: SectionsOffsets<Def> } : {}) &
+  (Def["mode"] extends "grid" ? { grid: GridLayerOffsets<Def> } : {});
+
+type TypedReader<Def extends ChannelDef> = Omit<ChannelReader, "sections" | "layers" | "fields"> &
+  (Def["mode"] extends "slots" ? { sections: Record<string, import("./types").SlotAccessor> } : {}) &
+  (Def["mode"] extends "grid" ? { layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array> } : {}) &
+  (Def["mode"] extends "record" ? { fields: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array> } : {});
+
+type TypedWriter<Def extends ChannelDef> = Omit<ChannelWriter, "sections" | "layers" | "fields"> &
+  (Def["mode"] extends "slots" ? { sections: Record<string, import("./types").SlotAccessor> } : {}) &
+  (Def["mode"] extends "grid" ? { layers: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array> } : {}) &
+  (Def["mode"] extends "record" ? { fields: Record<string, Float32Array | Int32Array | Uint32Array | Float64Array> } : {});
+
+export interface ChannelInstanceTyped<Def extends ChannelDef> extends ChannelInstance {
+  offsets: ChannelOffsets<Def>;
+  reader(sab: SharedArrayBuffer): TypedReader<Def>;
+  writer(sab: SharedArrayBuffer): TypedWriter<Def>;
+}
+
+// --- Runtime implementation ---
+
+function buildOffsets(layout: ChannelLayout): Record<string, unknown> {
+  const headerOffsets: Record<string, number> = {
+    magic: layout.header.magicIndex,
+    version: layout.header.versionIndex,
+    sequence: layout.header.sequenceIndex,
+  };
+  for (const [name, field] of Object.entries(layout.header.fields)) {
+    if (name === "magic" || name === "version" || name === "sequence") continue;
+    headerOffsets[name] = field.index;
+  }
+
+  if (layout.mode === "record" && layout.fields) {
+    const fieldOffsets: Record<string, number> = {};
+    for (const [name, field] of Object.entries(layout.fields)) {
+      fieldOffsets[name] = field.index;
+    }
+    return { header: headerOffsets, fields: fieldOffsets };
+  }
+
+  if (layout.mode === "slots" && layout.sections) {
+    const sections: Record<string, unknown> = {};
+    layout.sections.forEach((section) => {
+      const fieldOffsets: Record<string, number> = {};
+      for (const [name, field] of Object.entries(section.fields)) {
+        fieldOffsets[name] = field.index;
+      }
+      sections[section.name] = {
+        sectionByteOffset: section.byteOffset,
+        slotStride: section.slotStride,
+        fields: fieldOffsets,
+      };
+    });
+    return { header: headerOffsets, sections };
+  }
+
+  if (layout.mode === "grid" && layout.grid) {
+    const grid: Record<string, { byteOffset: number; length: number }> = {};
+    for (const [name, layer] of Object.entries(layout.grid.layers)) {
+      grid[name] = { byteOffset: layer.byteOffset, length: layer.length };
+    }
+    return { header: headerOffsets, grid };
+  }
+
+  return { header: headerOffsets };
+}
+
+function createReader(sab: SharedArrayBuffer, layout: ChannelLayout): ChannelReader {
+  switch (layout.mode) {
+    case "record": return new RecordReader(sab, layout);
+    case "slots": return new SlotReader(sab, layout);
+    case "grid": return new GridReader(sab, layout);
+  }
+}
+
+function createWriter(sab: SharedArrayBuffer, layout: ChannelLayout): ChannelWriter {
+  switch (layout.mode) {
+    case "record": {
+      const w = new RecordWriter(sab, layout);
+      w.init();
+      return w;
+    }
+    case "slots": {
+      const w = new SlotWriter(sab, layout);
+      w.init();
+      return w;
+    }
+    case "grid": {
+      const w = new GridWriter(sab, layout);
+      w.init();
+      return w;
+    }
+  }
+}
+
+export function defineChannel<const Def extends ChannelDef>(def: Def): ChannelInstanceTyped<Def> {
+  const layout = computeLayout(def);
+  const offsets = buildOffsets(layout);
+
+  const instance: ChannelInstance = {
+    def,
+    layout,
+    byteLength: layout.byteLength,
+    offsets,
+    allocate(): SharedArrayBuffer {
+      const sab = new SharedArrayBuffer(layout.byteLength);
+      const u32 = new Uint32Array(sab);
+      u32[layout.header.magicIndex] = layout.magic;
+      u32[layout.header.versionIndex] = layout.version;
+      return sab;
+    },
+    reader(sab: SharedArrayBuffer): ChannelReader {
+      return createReader(sab, layout);
+    },
+    writer(sab: SharedArrayBuffer): ChannelWriter {
+      return createWriter(sab, layout);
+    },
+  };
+
+  return instance as ChannelInstanceTyped<Def>;
+}
+
+// --- Manifest ---
+
+export function defineManifest<const M extends Record<string, ChannelInstance>>(
+  channels: M,
+): import("./types").ManifestInstance {
+  return {
+    channels: channels as Record<string, ChannelInstance>,
+    allocate(): Record<string, SharedArrayBuffer> {
+      const buffers: Record<string, SharedArrayBuffer> = {};
+      for (const [name, ch] of Object.entries(channels)) {
+        buffers[name] = ch.allocate();
+      }
+      return buffers;
+    },
+    attach(buffers: Record<string, SharedArrayBuffer>): Record<string, { reader: ChannelReader; writer: ChannelWriter }> {
+      const result: Record<string, { reader: ChannelReader; writer: ChannelWriter }> = {};
+      for (const [name, ch] of Object.entries(channels)) {
+        const sab = buffers[name];
+        if (!sab) {
+          throw new Error(`[SAB] Manifest attach: no buffer provided for channel "${name}"`);
+        }
+        if (sab.byteLength < ch.byteLength) {
+          throw new Error(
+            `[SAB] Manifest attach: buffer for channel "${name}" is ${sab.byteLength} bytes, need ${ch.byteLength}`,
+          );
+        }
+        result[name] = {
+          reader: ch.reader(sab),
+          writer: ch.writer(sab),
+        };
+      }
+      return result;
+    },
+  };
+}

package/core/src/sab/errors.ts

@@ -0,0 +1,76 @@
+import { createLogger } from "../util/logger";
+
+const log = createLogger();
+
+const warned = new Set<string>();
+
+let debugMode = false;
+
+export function setDebug(enabled: boolean): void {
+  debugMode = enabled;
+}
+
+export function isDebug(): boolean {
+  return debugMode;
+}
+
+export function warnOnce(key: string, msg: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  log.warn("SAB", msg);
+}
+
+export function resetWarnings(): void {
+  warned.clear();
+}
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(`[SAB] ${message}`);
+    this.name = "ValidationError";
+  }
+}
+
+/**
+ * Human-readable reason a SAB header fails validation, or `null` when valid.
+ * Distinguishes "not stamped yet" (readiness) from layout drift — callers
+ * polling `isValid()` would otherwise wait forever on a mismatched buffer.
+ */
+export function describeHeaderValidation(
+  u32: Uint32Array,
+  magicIndex: number,
+  versionIndex: number,
+  expectedMagic: number,
+  expectedVersion: number,
+): string | null {
+  const magic = u32[magicIndex];
+  const version = u32[versionIndex];
+  if (magic === 0) return "buffer not initialized (writer has not stamped the header)";
+  if (magic !== expectedMagic) {
+    return `bad magic 0x${magic.toString(16)} (expected 0x${expectedMagic.toString(16)})`;
+  }
+  if (version !== expectedVersion) {
+    return `version mismatch (got ${version}, expected ${expectedVersion})`;
+  }
+  return null;
+}
+
+const TYPE_SIZES: Record<string, number> = {
+  f32: 4,
+  f64: 8,
+  i32: 4,
+  u32: 4,
+  bool: 4,
+};
+
+export function typeSize(type: string): number {
+  const size = TYPE_SIZES[type];
+  if (size === undefined) {
+    throw new ValidationError(`Unknown field type: "${type}"`);
+  }
+  return size;
+}
+
+export function alignUp(offset: number, alignment: number): number {
+  return (offset + alignment - 1) & ~(alignment - 1);
+}