@downdraft/engine 0.0.0 → 0.1.1

package/libraries/marching-cubes/src/library.ts

@@ -0,0 +1,80 @@
+// ============================================================================
+// MarchingCubesLib — declarative engine library descriptor for @downdraft/engine/libraries/marching-cubes
+//
+// Games declare `libraries: [MarchingCubesLib]` (or with config override)
+// in their GameModule. The host allocates the terrain SAB (if used —
+// to-the-ocean currently uses RPC events instead), and provides the
+// TerrainLODManager + streaming config via typed tokens.
+//
+// Games that need full control can still import the mesh extraction
+// functions and ChunkedVoxelField directly (escape hatch).
+// ============================================================================
+
+import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import { TerrainChannel } from "./sab";
+import { DEFAULT_STREAMING_CONFIG, type TerrainStreamingConfig } from "./streaming-config";
+
+// ── Config ──
+
+export interface MarchingCubesLibConfig {
+  /** Terrain streaming config (LOD levels, voxel sizes, etc.). */
+  streaming?: Partial<TerrainStreamingConfig>;
+  /** Whether to allocate a terrain SAB channel. Default: false (use RPC events). */
+  useSAB?: boolean;
+  /** Voxel size multiplier for physics field generation. Default: 1. */
+  physVoxelSizeMultiplier?: number;
+  /** Max physics field generations per tick. Default: 1. */
+  physFieldGenMaxPerTick?: number;
+  /** Time budget for physics field generation (ms). Default: 8. */
+  physFieldGenTimeBudgetMs?: number;
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the terrain streaming config. */
+export const TerrainStreamingConfigTok = resourceToken<TerrainStreamingConfig>("terrain:streaming-config");
+
+// ── Descriptor ──
+
+export const MarchingCubesLib: EngineLibrary<MarchingCubesLibConfig> = {
+  name: "marching-cubes",
+  version: "1.0.0",
+
+  // SAB channel for zero-copy terrain deformation broadcast.
+  // Allocated using TerrainChannel's layout. Games that prefer RPC events
+  // can ignore this channel (it's allocated but not required to be used).
+  sabChannels: [
+    { name: "terrain", size: TerrainChannel.byteLength },
+  ],
+
+  provides: [TerrainStreamingConfigTok],
+
+  sim: {
+    create(config, ctx) {
+      const streamingConfig = { ...DEFAULT_STREAMING_CONFIG, ...config.streaming };
+      ctx.provide(TerrainStreamingConfigTok, streamingConfig);
+      // TerrainLODManager needs a DensityField (game-specific), so we just
+      // provide the streaming config here. Games create the LOD manager
+      // in onReady with their density field and inject TerrainStreamingConfigTok.
+      return { streamingConfig };
+    },
+    dispose(_system) {
+      // The system is a plain config object — no resources to free.
+    },
+    // tick is game-specific (calls lodManager.updateLOD(), processDeformations(),
+    // queueNearbyChunksForGeneration(), etc.) — games wire this via onReady.
+  },
+
+  tickPhase: "terrain",
+
+  // No renderer setup — terrain mesh generation is handled by the game's
+  // TerrainMeshPool worker pool, not by the library descriptor. The library
+  // provides the mesh extraction functions; the game orchestrates the workers.
+
+  defaultConfig: {
+    useSAB: false,
+    physVoxelSizeMultiplier: 1,
+    physFieldGenMaxPerTick: 1,
+    physFieldGenTimeBudgetMs: 8,
+  },
+};

package/libraries/marching-cubes/src/lod.ts

@@ -0,0 +1,122 @@
+import type { MCMesh, MCChunkConfig, DensityField } from "./generator";
+import { generateChunk } from "./generator";
+
+export interface LODLevel {
+  chunkSize: number;
+  scale: number;
+  distance: number;
+}
+
+export const DEFAULT_LOD_LEVELS: LODLevel[] = [
+  { chunkSize: 32, scale: 1.0, distance: 0 },
+  { chunkSize: 32, scale: 2.0, distance: 64 },
+  { chunkSize: 16, scale: 4.0, distance: 128 },
+  { chunkSize: 16, scale: 8.0, distance: 256 },
+];
+
+export interface ChunkLODEntry {
+  coord: { x: number; z: number };
+  lod: number;
+  mesh: MCMesh | null;
+  dirty: boolean;
+}
+
+export class TerrainLODManager {
+  private field: DensityField;
+  private levels: LODLevel[];
+  private chunks: Map<string, ChunkLODEntry> = new Map();
+  private cameraPos: [number, number, number] = [0, 0, 0];
+  private originY: number;
+
+  constructor(field: DensityField, levels?: LODLevel[], originY: number = 0) {
+    this.field = field;
+    this.levels = levels ?? DEFAULT_LOD_LEVELS;
+    this.originY = originY;
+  }
+
+  setCamera(pos: [number, number, number]): void {
+    this.cameraPos = pos;
+  }
+
+  selectLOD(chunkX: number, chunkZ: number): number {
+    const cx = chunkX * this.levels[0].chunkSize * this.levels[0].scale;
+    const cz = chunkZ * this.levels[0].chunkSize * this.levels[0].scale;
+    const dx = cx - this.cameraPos[0];
+    const dz = cz - this.cameraPos[2];
+    const dist = Math.sqrt(dx * dx + dz * dz);
+
+    for (let i = this.levels.length - 1; i >= 0; i--) {
+      if (dist >= this.levels[i].distance) return i;
+    }
+    return 0;
+  }
+
+  getOrCreateChunk(chunkX: number, chunkZ: number): ChunkLODEntry {
+    const key = `${chunkX}:${chunkZ}`;
+    let entry = this.chunks.get(key);
+    if (!entry) {
+      const lod = this.selectLOD(chunkX, chunkZ);
+      entry = { coord: { x: chunkX, z: chunkZ }, lod, mesh: null, dirty: true };
+      this.chunks.set(key, entry);
+    }
+    return entry;
+  }
+
+  generateChunk(chunkX: number, chunkZ: number): MCMesh {
+    const entry = this.getOrCreateChunk(chunkX, chunkZ);
+    const level = this.levels[entry.lod];
+    const config: MCChunkConfig = {
+      chunkSize: level.chunkSize,
+      isoLevel: 0.5,
+      scale: level.scale,
+    };
+    const originX = chunkX * level.chunkSize * level.scale;
+    const originZ = chunkZ * level.chunkSize * level.scale;
+    const mesh = generateChunk(originX, this.originY, originZ, this.field, config);
+    entry.mesh = mesh;
+    entry.dirty = false;
+    return mesh;
+  }
+
+  updateLOD(): { toGenerate: Array<{ x: number; z: number; lod: number }>; toUnload: string[] } {
+    const toGenerate: Array<{ x: number; z: number; lod: number }> = [];
+    const toUnload: string[] = [];
+
+    for (const [key, entry] of this.chunks.entries()) {
+      const newLOD = this.selectLOD(entry.coord.x, entry.coord.z);
+      if (newLOD !== entry.lod) {
+        entry.lod = newLOD;
+        entry.dirty = true;
+        toGenerate.push({ x: entry.coord.x, z: entry.coord.z, lod: newLOD });
+      }
+    }
+
+    return { toGenerate, toUnload };
+  }
+
+  getChunk(key: string): ChunkLODEntry | undefined {
+    return this.chunks.get(key);
+  }
+
+  getAllChunks(): ChunkLODEntry[] {
+    return [...this.chunks.values()];
+  }
+
+  removeChunk(chunkX: number, chunkZ: number): void {
+    this.chunks.delete(`${chunkX}:${chunkZ}`);
+  }
+
+  clear(): void {
+    this.chunks.clear();
+  }
+
+  getStats(): { total: number; dirty: number; generated: number } {
+    let dirty = 0;
+    let generated = 0;
+    for (const entry of this.chunks.values()) {
+      if (entry.dirty) dirty++;
+      if (entry.mesh) generated++;
+    }
+    return { total: this.chunks.size, dirty, generated };
+  }
+}

package/libraries/marching-cubes/src/marching-tetrahedra.ts

@@ -0,0 +1,252 @@
+import type { ExtractMeshOptions } from "./generator";
+import type { ExtractedMesh, VoxelField } from "./types";
+
+const CORNER_OFFSET = [
+  [0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1],
+  [0, 1, 0], [1, 1, 0], [1, 1, 1], [0, 1, 1],
+];
+
+// 5-tet decomposition of a cube — two alternating configs for crack-free
+// tiling between adjacent cubes (toggled by (x+y+z)&1).
+// Derived from d3x0r's MarchingTetrahedra2, remapped to engine corner order.
+const TET_TABLE_A = [
+  [0, 4, 3, 1],
+  [5, 1, 6, 4],
+  [2, 6, 1, 3],
+  [7, 6, 3, 4],
+  [3, 6, 1, 4],
+];
+
+const TET_TABLE_B = [
+  [1, 0, 2, 5],
+  [4, 5, 7, 0],
+  [3, 2, 0, 7],
+  [6, 5, 2, 7],
+  [0, 7, 2, 5],
+];
+
+// Edges of a tetrahedron (local corner indices 0-3)
+const TET_EDGE_CORNERS = [
+  [0, 1], [0, 2], [0, 3], [1, 2], [1, 3], [2, 3],
+];
+
+// Triangle lookup for 16 tetrahedra cases (4-bit: bit i = corner i inside)
+// Edges: e0=0-1, e1=0-2, e2=0-3, e3=1-2, e4=1-3, e5=2-3
+// Winding: normals point outward (from inside/solid toward outside/empty)
+const MT_TRI_TABLE: Int8Array = new Int8Array([
+  -1,-1,-1,-1,-1,-1,
+   2, 0, 1,-1,-1,-1,
+   0, 4, 3,-1,-1,-1,
+   1, 2, 4, 1, 4, 3,
+   3, 5, 1,-1,-1,-1,
+   0, 3, 5, 0, 5, 2,
+   1, 0, 4, 1, 4, 5,
+   2, 4, 5,-1,-1,-1,
+   5, 4, 2,-1,-1,-1,
+   4, 0, 1, 5, 4, 1,
+   5, 3, 0, 2, 5, 0,
+   1, 5, 3,-1,-1,-1,
+   4, 2, 1, 3, 4, 1,
+   3, 4, 0,-1,-1,-1,
+   1, 0, 2,-1,-1,-1,
+  -1,-1,-1,-1,-1,-1,
+]);
+
+const SCRATCH_D = new Float32Array(8);
+const SCRATCH_TET_D = new Float32Array(4);
+const SCRATCH_EDGE_VERTS = new Float32Array(6 * 3);
+
+function ensureCapacity(arr: Float32Array, needed: number): Float32Array {
+  if (arr.length >= needed) return arr;
+  let n = arr.length;
+  while (n < needed) n *= 2;
+  const r = new Float32Array(n);
+  r.set(arr);
+  return r;
+}
+
+function ensureCapacityU32(arr: Uint32Array, needed: number): Uint32Array {
+  if (arr.length >= needed) return arr;
+  let n = arr.length;
+  while (n < needed) n *= 2;
+  const r = new Uint32Array(n);
+  r.set(arr);
+  return r;
+}
+
+function ensureCapacityU16(arr: Uint16Array, needed: number): Uint16Array {
+  if (arr.length >= needed) return arr;
+  let n = arr.length;
+  while (n < needed) n *= 2;
+  const r = new Uint16Array(n);
+  r.set(arr);
+  return r;
+}
+
+export function extractMeshFromFieldTetra(
+  field: VoxelField,
+  options: ExtractMeshOptions = {},
+): ExtractedMesh {
+  const iso = field.isoLevel;
+  const vs = field.voxelSize;
+  const dimYDimZ = field.dimY * field.dimZ;
+  const dimZ = field.dimZ;
+  const ox = field.originX, oy = field.originY, oz = field.originZ;
+  const colorFn = options.colorFn;
+  const flipDown = options.flipDownNormals !== false;
+
+  let verts: Float32Array = new Float32Array(65536);
+  let vertCount = 0;
+  let indices32: Uint32Array = new Uint32Array(32768);
+  let indices16: Uint16Array = new Uint16Array(32768);
+  let indexCount = 0;
+  let useUint32 = false;
+
+  const xStart = options.x0 !== undefined ? Math.max(0, options.x0) : 0;
+  const yStart = options.y0 !== undefined ? Math.max(0, options.y0) : 0;
+  const zStart = options.z0 !== undefined ? Math.max(0, options.z0) : 0;
+  const xEnd = options.x1 !== undefined ? Math.min(field.dimX - 1, options.x1) : field.dimX - 1;
+  const yEnd = options.y1 !== undefined ? Math.min(field.dimY - 1, options.y1) : field.dimY - 1;
+  const zEnd = options.z1 !== undefined ? Math.min(field.dimZ - 1, options.z1) : field.dimZ - 1;
+
+  for (let x = xStart; x < xEnd; x++) {
+    for (let y = yStart; y < yEnd; y++) {
+      for (let z = zStart; z < zEnd; z++) {
+        for (let c = 0; c < 8; c++) {
+          const co = CORNER_OFFSET[c];
+          const cx = x + co[0], cy = y + co[1], cz = z + co[2];
+          if (cx < 0 || cx >= field.dimX || cy < 0 || cy >= field.dimY || cz < 0 || cz >= field.dimZ) {
+            SCRATCH_D[c] = -1.0;
+          } else {
+            SCRATCH_D[c] = field.data[cx * dimYDimZ + cy * dimZ + cz];
+          }
+        }
+
+        const tets = ((x + y + z) & 1) ? TET_TABLE_B : TET_TABLE_A;
+
+        for (let ti = 0; ti < 5; ti++) {
+          const tet = tets[ti];
+          const d = SCRATCH_TET_D;
+          d[0] = SCRATCH_D[tet[0]];
+          d[1] = SCRATCH_D[tet[1]];
+          d[2] = SCRATCH_D[tet[2]];
+          d[3] = SCRATCH_D[tet[3]];
+
+          let caseIdx = 0;
+          for (let i = 0; i < 4; i++) {
+            if (d[i] < iso) caseIdx |= (1 << i);
+          }
+
+          const triBase = caseIdx * 6;
+          if (MT_TRI_TABLE[triBase] < 0) continue;
+
+          const ev = SCRATCH_EDGE_VERTS;
+          for (let e = 0; e < 6; e++) {
+            const ec = TET_EDGE_CORNERS[e];
+            const c0 = ec[0], c1 = ec[1];
+            const inside0 = d[c0] >= iso;
+            const inside1 = d[c1] >= iso;
+            if (inside0 === inside1) continue;
+
+            const cubeC0 = tet[c0], cubeC1 = tet[c1];
+            const co0 = CORNER_OFFSET[cubeC0], co1 = CORNER_OFFSET[cubeC1];
+            const p0x = (x + co0[0]) * vs + ox, p0y = (y + co0[1]) * vs + oy, p0z = (z + co0[2]) * vs + oz;
+            const p1x = (x + co1[0]) * vs + ox, p1y = (y + co1[1]) * vs + oy, p1z = (z + co1[2]) * vs + oz;
+            const d0 = d[c0], d1 = d[c1];
+
+            let t: number;
+            if (Math.abs(iso - d0) < 1e-10) t = 0;
+            else if (Math.abs(iso - d1) < 1e-10) t = 1;
+            else if (Math.abs(d0 - d1) < 1e-10) t = 0;
+            else t = (iso - d0) / (d1 - d0);
+
+            const eo = e * 3;
+            ev[eo] = p0x + t * (p1x - p0x);
+            ev[eo + 1] = p0y + t * (p1y - p0y);
+            ev[eo + 2] = p0z + t * (p1z - p0z);
+          }
+
+          for (let t = 0; t < 6; t += 3) {
+            const e0 = MT_TRI_TABLE[triBase + t];
+            if (e0 < 0) break;
+            const e1 = MT_TRI_TABLE[triBase + t + 1];
+            const e2 = MT_TRI_TABLE[triBase + t + 2];
+
+            const ev0o = e0 * 3, ev1o = e1 * 3, ev2o = e2 * 3;
+            const v0x = ev[ev0o], v0y = ev[ev0o + 1], v0z = ev[ev0o + 2];
+            const v1x = ev[ev1o], v1y = ev[ev1o + 1], v1z = ev[ev1o + 2];
+            const v2x = ev[ev2o], v2y = ev[ev2o + 1], v2z = ev[ev2o + 2];
+
+            const e1x = v1x - v0x, e1y = v1y - v0y, e1z = v1z - v0z;
+            const e2x = v2x - v0x, e2y = v2y - v0y, e2z = v2z - v0z;
+            let nx = e1y * e2z - e1z * e2y;
+            let ny = e1z * e2x - e1x * e2z;
+            let nz = e1x * e2y - e1y * e2x;
+            const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz);
+            if (nlen > 1e-10) { nx /= nlen; ny /= nlen; nz /= nlen; }
+            else { nx = 0; ny = 1; nz = 0; }
+            if (flipDown && ny < 0) { nx = -nx; ny = -ny; nz = -nz; }
+
+            const cx = (v0x + v1x + v2x) / 3;
+            const cy = (v0y + v1y + v2y) / 3;
+            const cz = (v0z + v1z + v2z) / 3;
+
+            const col = colorFn ? colorFn(cx, cy, cz, nx, ny, nz, field) : [1, 1, 1] as [number, number, number];
+
+            if (vertCount + 27 > verts.length) {
+              verts = ensureCapacity(verts, vertCount + 27);
+            }
+            verts[vertCount++] = v0x; verts[vertCount++] = v0y; verts[vertCount++] = v0z;
+            verts[vertCount++] = nx; verts[vertCount++] = ny; verts[vertCount++] = nz;
+            verts[vertCount++] = col[0]; verts[vertCount++] = col[1]; verts[vertCount++] = col[2];
+            verts[vertCount++] = v1x; verts[vertCount++] = v1y; verts[vertCount++] = v1z;
+            verts[vertCount++] = nx; verts[vertCount++] = ny; verts[vertCount++] = nz;
+            verts[vertCount++] = col[0]; verts[vertCount++] = col[1]; verts[vertCount++] = col[2];
+            verts[vertCount++] = v2x; verts[vertCount++] = v2y; verts[vertCount++] = v2z;
+            verts[vertCount++] = nx; verts[vertCount++] = ny; verts[vertCount++] = nz;
+            verts[vertCount++] = col[0]; verts[vertCount++] = col[1]; verts[vertCount++] = col[2];
+
+            const baseIdx = (vertCount - 27) / 9;
+
+            if (!useUint32 && baseIdx + 2 > 65535) {
+              useUint32 = true;
+              if (indexCount > indices32.length) {
+                indices32 = ensureCapacityU32(indices32, indexCount);
+              }
+              for (let ci = 0; ci < indexCount; ci++) {
+                indices32[ci] = indices16[ci];
+              }
+            }
+
+            if (useUint32) {
+              if (indexCount + 3 > indices32.length) {
+                indices32 = ensureCapacityU32(indices32, indexCount + 3);
+              }
+              indices32[indexCount++] = baseIdx;
+              indices32[indexCount++] = baseIdx + 1;
+              indices32[indexCount++] = baseIdx + 2;
+            } else {
+              if (indexCount + 3 > indices16.length) {
+                indices16 = ensureCapacityU16(indices16, indexCount + 3);
+              }
+              indices16[indexCount++] = baseIdx;
+              indices16[indexCount++] = baseIdx + 1;
+              indices16[indexCount++] = baseIdx + 2;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  const finalVerts = verts.subarray(0, vertCount);
+  const finalIndices = useUint32
+    ? indices32.subarray(0, indexCount)
+    : indices16.subarray(0, indexCount);
+
+  return {
+    verts: finalVerts,
+    indices: finalIndices as Uint16Array | Uint32Array,
+    useUint32,
+  };
+}

package/libraries/marching-cubes/src/sab.ts

@@ -0,0 +1,45 @@
+import type { SABChannel } from "@downdraft/engine";
+import { defineChannel } from "@downdraft/engine/sab/define";
+
+export const TerrainChannel = defineChannel({
+  name: "terrain",
+  magic: 0x54455252,
+  version: 1,
+  mode: "record",
+  header: { size: 64, fields: {} },
+  fields: {
+    heightmap: { type: "f32", count: 64 },
+    chunkX: { type: "i32" },
+    chunkZ: { type: "i32" },
+  },
+});
+
+export class TerrainSABChannel {
+  private writer: ReturnType<typeof TerrainChannel.writer>;
+  private reader: ReturnType<typeof TerrainChannel.reader>;
+
+  constructor(channel: SABChannel) {
+    this.writer = TerrainChannel.writer(channel.buffer);
+    this.reader = TerrainChannel.reader(channel.buffer);
+  }
+
+  write(heightmap: Float32Array, chunkX: number, chunkZ: number): void {
+    const w = this.writer;
+    for (let i = 0; i < Math.min(heightmap.length, 64); i++) {
+      (w.fields.heightmap as Float32Array)[i] = heightmap[i];
+    }
+    (w.fields.chunkX as Int32Array)[0] = chunkX;
+    (w.fields.chunkZ as Int32Array)[0] = chunkZ;
+    w.bumpSequence();
+  }
+
+  read(): { heightmap: Float32Array; chunkX: number; chunkZ: number } | null {
+    const data = this.reader.snapshot();
+    if (!data) return null;
+    return {
+      heightmap: new Float32Array(data.heightmap as number[]),
+      chunkX: data.chunkX as number,
+      chunkZ: data.chunkZ as number,
+    };
+  }
+}

package/libraries/marching-cubes/src/streaming-config.ts

@@ -0,0 +1,48 @@
+// ============================================================================
+// TerrainLODConfig — distance-based LOD configuration with hysteresis
+// ============================================================================
+
+export interface LODLevelConfig {
+  maxDistance: number;
+  voxelSize: number;
+}
+
+export function getLODVoxelSize(distance: number, levels: readonly LODLevelConfig[]): number {
+  for (let i = 0; i < levels.length; i++) {
+    if (distance <= levels[i].maxDistance) {
+      return levels[i].voxelSize;
+    }
+  }
+  return levels[levels.length - 1].voxelSize;
+}
+
+export interface TerrainStreamingConfig {
+  lodLevels: readonly LODLevelConfig[];
+  baseVoxelSize: number;
+  lodHysteresisTicks: number;
+  chunkGenTimeBudgetMs: number;
+  chunkGenMaxPerTick: number;
+  physFieldGenTimeBudgetMs: number;
+  physFieldGenMaxPerTick: number;
+  maxChunksToScan: number;
+  generationRange: number;
+  lodCheckRange: number;
+}
+
+export const DEFAULT_STREAMING_CONFIG: TerrainStreamingConfig = {
+  lodLevels: [
+    { maxDistance: 150, voxelSize: 0 },
+    { maxDistance: 350, voxelSize: 5.0 },
+    { maxDistance: 700, voxelSize: 10.0 },
+    { maxDistance: 1500, voxelSize: 20.0 },
+  ],
+  baseVoxelSize: 2.5,
+  lodHysteresisTicks: 60,
+  chunkGenTimeBudgetMs: 8,
+  chunkGenMaxPerTick: 4,
+  physFieldGenTimeBudgetMs: 8,
+  physFieldGenMaxPerTick: 1,
+  maxChunksToScan: 256,
+  generationRange: 200,
+  lodCheckRange: 250,
+};