@downdraft/engine 0.0.0 → 0.1.0

package/libraries/stickman/src/stickman-pass.ts

@@ -0,0 +1,255 @@
+// ============================================================================
+// StickmanPass — shared render pass that draws a stickman player avatar as
+// thick lines, lit by the game's light/volumetric textures.
+//
+// Generalized from the falling-sand + mining-rpg copies. Viewport is set
+// separately from the per-frame pose:
+//   - setGridViewport(gridW, gridH): cell coords -> NDC across the whole
+//     canvas (falling-sand — grid fills the screen).
+//   - setCameraViewport(camX, camY, zoom, canvasW, canvasH): pan/zoom camera
+//     (mining-rpg).
+//
+// Bindings: 0 = uniforms, 1 = light accumulation texture, 2 = volumetric
+// texture. Unset light bindings default to a 1×1 white dummy (identity
+// lighting).
+// ============================================================================
+
+import { createValidatedShaderModule } from "@downdraft/engine";
+import type { StructView, WgslStruct } from "@downdraft/engine/shader-graph";
+import { f32, vec2f, vec3f, vec4f, wgsl } from "@downdraft/engine/shader-graph";
+import { DEFAULT_LINE_WIDTH } from "./proportions";
+import { STICKMAN_WGSL } from "./shader";
+import { computeSkeleton, type StickmanPose } from "./skeleton";
+import {
+    buildThickLineIndices,
+    buildThickLineVertices,
+    STICKMAN_INDEX_COUNT,
+    STICKMAN_VERTEX_COUNT,
+    STICKMAN_VERTEX_STRIDE,
+    type ThickLineGeometry,
+} from "./thick-line";
+
+// ─── Uniform struct (must match StickmanUniforms in STICKMAN_WGSL) ──────────
+const StickmanUniformsStruct: WgslStruct = wgsl.struct("StickmanUniforms", {
+  transform: vec4f,
+  screenSize: vec2f,
+  lineWidth: f32,
+  color: vec3f,
+});
+
+const UNIFORM_SIZE = StickmanUniformsStruct.size;
+const UNIFORM_FLOATS = StickmanUniformsStruct.floatCount;
+
+/** Per-frame pose + vitals for the stickman draw. */
+export interface StickmanDrawState extends StickmanPose {
+  /** 0–100; drives the body color gradient (red → yellow → green). */
+  health: number;
+  /** Vertical velocity — accepted for API parity; currently unused. */
+  vy?: number;
+}
+
+export class StickmanPass {
+  private device: GPUDevice;
+  private format: GPUTextureFormat;
+  private pipeline: GPURenderPipeline | null = null;
+  private bindGroupLayout: GPUBindGroupLayout | null = null;
+  private bindGroup: GPUBindGroup | null = null;
+  private uniformBuffer: GPUBuffer | null = null;
+  private vertexBuffer: GPUBuffer | null = null;
+  private indexBuffer: GPUBuffer | null = null;
+  private lightView: GPUTextureView | null = null;
+  private volumetricView: GPUTextureView | null = null;
+  private dummyTexture: GPUTexture | null = null;
+  private dummyView: GPUTextureView | null = null;
+
+  // Current viewport transform (set via setGridViewport/setCameraViewport).
+  private transform = new Float32Array(4); // scaleX, scaleY, offX, offY
+  private screenSize = new Float32Array([1, 1]);
+
+  // Preallocated uniform buffer (avoid per-frame allocation)
+  private _uniformBuf: Float32Array<ArrayBuffer> | null = null;
+  private _uniformView: StructView | null = null;
+
+  // Reused each frame to avoid allocation.
+  private skeleton: Float32Array;
+  private geom: ThickLineGeometry;
+
+  constructor(config: { device: GPUDevice; format: GPUTextureFormat }) {
+    this.device = config.device;
+    this.format = config.format;
+    this.skeleton = new Float32Array(0);
+    this.geom = { vertices: new Float32Array(0), indices: new Uint16Array(0), vertexCount: 0, indexCount: 0 };
+  }
+
+  init(): void {
+    this.uniformBuffer = this.device.createBuffer({
+      size: UNIFORM_SIZE,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+    });
+    this._uniformBuf = new Float32Array(UNIFORM_FLOATS);
+    this._uniformView = StickmanUniformsStruct.view(this._uniformBuf);
+
+    // 1x1 dummy white texture for the light/volumetric bindings (before the
+    // real views are set each frame). Lighting becomes identity (white).
+    this.dummyTexture = this.device.createTexture({
+      size: [1, 1],
+      format: "rgba8unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    });
+    this.dummyView = this.dummyTexture.createView();
+    this.device.queue.writeTexture(
+      { texture: this.dummyTexture },
+      new Uint8Array([255, 255, 255, 255]),
+      { bytesPerRow: 4, rowsPerImage: 1 },
+      [1, 1],
+    );
+
+    // Static-size vertex buffer (rewritten each frame) + static index buffer.
+    this.vertexBuffer = this.device.createBuffer({
+      size: STICKMAN_VERTEX_COUNT * STICKMAN_VERTEX_STRIDE,
+      usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
+    const indices = buildThickLineIndices();
+    this.indexBuffer = this.device.createBuffer({
+      size: indices.byteLength,
+      usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+    });
+    this.device.queue.writeBuffer(this.indexBuffer, 0, indices as unknown as BufferSource);
+
+    const shader = createValidatedShaderModule(this.device, { code: STICKMAN_WGSL, label: "StickmanPass" });
+
+    this.bindGroupLayout = this.device.createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+        { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+      ],
+    });
+
+    const pipelineLayout = this.device.createPipelineLayout({
+      bindGroupLayouts: [this.bindGroupLayout],
+    });
+
+    this.pipeline = this.device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: {
+        module: shader,
+        entryPoint: "vs_main",
+        buffers: [{
+          arrayStride: STICKMAN_VERTEX_STRIDE,
+          attributes: [
+            { shaderLocation: 0, offset: 0, format: "float32x3" },  // endpointA
+            { shaderLocation: 1, offset: 12, format: "float32x3" }, // endpointB
+            { shaderLocation: 2, offset: 24, format: "float32x2" }, // cornerVec
+          ],
+        }],
+      },
+      fragment: { module: shader, entryPoint: "fs_main", targets: [{ format: this.format }] },
+      primitive: { topology: "triangle-list" },
+    });
+
+    this.createBindGroup();
+  }
+
+  private createBindGroup(): void {
+    if (!this.bindGroupLayout || !this.uniformBuffer || !this.dummyView) return;
+    const lView = this.lightView ?? this.dummyView;
+    const vView = this.volumetricView ?? this.dummyView;
+    this.bindGroup = this.device.createBindGroup({
+      layout: this.bindGroupLayout,
+      entries: [
+        { binding: 0, resource: { buffer: this.uniformBuffer } },
+        { binding: 1, resource: lView },
+        { binding: 2, resource: vView },
+      ],
+    });
+  }
+
+  /** Set the light accumulation texture view (binding 1). */
+  setLightTexture(view: GPUTextureView | null): void {
+    if (this.lightView === view) return;
+    this.lightView = view;
+    this.createBindGroup();
+  }
+
+  /** Set the volumetric light texture view (binding 2). */
+  setVolumetricTexture(view: GPUTextureView | null): void {
+    if (this.volumetricView === view) return;
+    this.volumetricView = view;
+    this.createBindGroup();
+  }
+
+  /** Grid-fills-canvas viewport: cell coords → NDC across the whole canvas. */
+  setGridViewport(gridW: number, gridH: number): void {
+    this.transform[0] = 2 / gridW;
+    this.transform[1] = -2 / gridH;
+    this.transform[2] = -1;
+    this.transform[3] = 1;
+    this.screenSize[0] = gridW;
+    this.screenSize[1] = gridH;
+  }
+
+  /** Pan/zoom camera viewport: world cell coords → NDC. */
+  setCameraViewport(camX: number, camY: number, zoom: number, canvasW: number, canvasH: number): void {
+    const scaleX = (zoom * 2) / canvasW;
+    const scaleY = (-zoom * 2) / canvasH;
+    this.transform[0] = scaleX;
+    this.transform[1] = scaleY;
+    this.transform[2] = -camX * scaleX;
+    this.transform[3] = -camY * scaleY;
+    this.screenSize[0] = canvasW;
+    this.screenSize[1] = canvasH;
+  }
+
+  update(state: StickmanDrawState): void {
+    if (!this.vertexBuffer || !this.uniformBuffer) return;
+
+    // --- Skeleton -> thick-line vertices ---
+    this.skeleton = computeSkeleton(
+      { cx: state.cx, topY: state.topY, facing: state.facing, animFrame: state.animFrame, vx: state.vx, onGround: state.onGround },
+      this.skeleton,
+    );
+    this.geom = buildThickLineVertices(this.skeleton, this.geom);
+    this.device.queue.writeBuffer(this.vertexBuffer, 0, this.geom.vertices as unknown as BufferSource);
+
+    // --- Color: health gradient (red -> yellow -> green) ---
+    const hp = Math.max(0, Math.min(1, state.health / 100));
+    let r: number, g: number, b: number;
+    if (hp > 0.5) {
+      const t = (hp - 0.5) * 2;
+      r = 1.0 - t;
+      g = 0.85 + (1.0 - 0.85) * t;
+      b = 0.2 * t;
+    } else {
+      const t = hp * 2;
+      r = 1.0;
+      g = 0.85 * t;
+      b = 0.0;
+    }
+
+    const view = this._uniformView!;
+    view.set("transform", [this.transform[0], this.transform[1], this.transform[2], this.transform[3]]);
+    view.set("screenSize", [this.screenSize[0], this.screenSize[1]]);
+    view.set("lineWidth", DEFAULT_LINE_WIDTH);
+    view.set("color", [r, g, b]);
+    this.device.queue.writeBuffer(this.uniformBuffer, 0, this._uniformBuf!);
+  }
+
+  render(pass: GPURenderPassEncoder): void {
+    if (!this.pipeline || !this.bindGroup || !this.vertexBuffer || !this.indexBuffer) return;
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.bindGroup);
+    pass.setVertexBuffer(0, this.vertexBuffer);
+    pass.setIndexBuffer(this.indexBuffer, "uint16");
+    pass.drawIndexed(STICKMAN_INDEX_COUNT);
+  }
+
+  destroy(): void {
+    this.uniformBuffer?.destroy();
+    this.vertexBuffer?.destroy();
+    this.indexBuffer?.destroy();
+    this.dummyTexture?.destroy();
+    this._uniformBuf = null;
+    this._uniformView = null;
+  }
+}

package/libraries/stickman/src/thick-line.ts

@@ -0,0 +1,123 @@
+// Thick-line geometry builder.
+//
+// Expands each skeleton segment into a camera-facing quad (2 triangles).
+// Two segment types:
+//
+//   Line segments (index > 0): endpointA = start, endpointB = end, cornerVec = (t, side).
+//     The shader extrudes a constant-width stroke perpendicular to the segment.
+//
+//   Circle segment (index 0, the head): endpointA = endpointB = center.
+//     The builder encodes the radius in endpointB.z. cornerVec = (±1, ±1).
+//     The shader expands the quad to the circle's bounding box and uses an
+//     SDF in the fragment shader to draw a perfect circle ring.
+//
+// Vertex layout (arrayStride = 32 bytes):
+//   location 0: float32x3  endpointA
+//   location 1: float32x3  endpointB  (z = radius for circle, 0 for line)
+//   location 2: float32x2  cornerVec  (t,side for line; cornerX,cornerY for circle)
+
+import { STICKMAN_FLOATS_PER_SEGMENT, STICKMAN_SEGMENT_COUNT, getHeadRadius } from "./skeleton";
+
+// Line segment corners: (t=0,side=-1), (t=0,side=+1), (t=1,side=+1), (t=1,side=-1).
+const LINE_CORNERS: ReadonlyArray<readonly [number, number]> = [
+  [0, -1],
+  [0, 1],
+  [1, 1],
+  [1, -1],
+];
+
+// Circle quad corners: (-1,-1), (1,-1), (1,1), (-1,1) — full bounding box.
+const CIRCLE_CORNERS: ReadonlyArray<readonly [number, number]> = [
+  [-1, -1],
+  [1, -1],
+  [1, 1],
+  [-1, 1],
+];
+
+export const STICKMAN_VERTEX_COUNT = STICKMAN_SEGMENT_COUNT * 4;
+export const STICKMAN_INDEX_COUNT = STICKMAN_SEGMENT_COUNT * 6;
+export const STICKMAN_VERTEX_STRIDE = 32; // bytes: 3 + 3 + 2 floats
+
+export interface ThickLineGeometry {
+  /** Float32Array of length STICKMAN_VERTEX_COUNT * 8 (reused each frame). */
+  vertices: Float32Array;
+  /** Uint16Array of length STICKMAN_INDEX_COUNT (built once, static). */
+  indices: Uint16Array;
+  vertexCount: number;
+  indexCount: number;
+}
+
+/**
+ * Build the static index buffer for the stickman quads. Call once at init.
+ */
+export function buildThickLineIndices(out?: Uint16Array): Uint16Array {
+  const idx = out && out.length >= STICKMAN_INDEX_COUNT ? out : new Uint16Array(STICKMAN_INDEX_COUNT);
+  let p = 0;
+  for (let s = 0; s < STICKMAN_SEGMENT_COUNT; s++) {
+    const b = s * 4;
+    idx[p++] = b + 0; idx[p++] = b + 1; idx[p++] = b + 2;
+    idx[p++] = b + 0; idx[p++] = b + 2; idx[p++] = b + 3;
+  }
+  return idx;
+}
+
+/**
+ * Expand a skeleton into quad vertices. Segment 0 is the head circle (radius
+ * encoded in endpointB.z); all other segments are thick lines.
+ *
+ * @param skeleton Float32Array from `computeSkeleton` (length >= STICKMAN_SKELETON_FLOATS).
+ * @param geom Optional existing geometry to reuse (its `vertices` buffer is overwritten).
+ */
+export function buildThickLineVertices(skeleton: Float32Array, geom?: ThickLineGeometry): ThickLineGeometry {
+  if (skeleton.length < STICKMAN_SEGMENT_COUNT * STICKMAN_FLOATS_PER_SEGMENT) {
+    throw new Error(`skeleton too small: ${skeleton.length} < ${STICKMAN_SEGMENT_COUNT * STICKMAN_FLOATS_PER_SEGMENT}`);
+  }
+  const vertices = geom?.vertices && geom.vertices.length >= STICKMAN_VERTEX_COUNT * 8
+    ? geom.vertices
+    : new Float32Array(STICKMAN_VERTEX_COUNT * 8);
+  const indices = geom?.indices ?? buildThickLineIndices();
+  const headR = getHeadRadius();
+
+  let v = 0;
+  for (let s = 0; s < STICKMAN_SEGMENT_COUNT; s++) {
+    const base = s * STICKMAN_FLOATS_PER_SEGMENT;
+    const ax = skeleton[base + 0];
+    const ay = skeleton[base + 1];
+    const bx = skeleton[base + 2];
+    const by = skeleton[base + 3];
+
+    if (s === 0) {
+      // Head circle: endpointA = center, endpointB.z = radius.
+      // cornerVec = (cornerX, cornerY) ∈ {-1,+1}².
+      for (let c = 0; c < 4; c++) {
+        const [cx, cy] = CIRCLE_CORNERS[c];
+        vertices[v++] = ax; vertices[v++] = ay; vertices[v++] = 0;       // endpointA = center
+        vertices[v++] = ax; vertices[v++] = ay; vertices[v++] = headR;    // endpointB = (center, radius)
+        vertices[v++] = cx; vertices[v++] = cy;                            // cornerVec
+      }
+    } else {
+      // Line segment: endpointA = start, endpointB = end (z=0).
+      // cornerVec = (t, side).
+      for (let c = 0; c < 4; c++) {
+        const [t, side] = LINE_CORNERS[c];
+        vertices[v++] = ax; vertices[v++] = ay; vertices[v++] = 0;
+        vertices[v++] = bx; vertices[v++] = by; vertices[v++] = 0;
+        vertices[v++] = t;  vertices[v++] = side;
+      }
+    }
+  }
+
+  if (geom) {
+    geom.vertices = vertices;
+    geom.indices = indices;
+    geom.vertexCount = STICKMAN_VERTEX_COUNT;
+    geom.indexCount = STICKMAN_INDEX_COUNT;
+    return geom;
+  }
+  return {
+    vertices,
+    indices,
+    vertexCount: STICKMAN_VERTEX_COUNT,
+    indexCount: STICKMAN_INDEX_COUNT,
+  };
+}

package/libraries/surface-nets/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/libraries/surface-nets`
+
+Surface-nets meshing — smooth isosurface extraction for density-field terrain.
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/surface-nets
+```
+
+## Key exports
+
+- `DEFAULT_LOD_LEVELS`
+- `DEFAULT_STREAMING_CONFIG`
+- `SurfaceNetsLib`
+- `SurfaceNetsStreamingConfigTok`
+- `TerrainChannel`
+- `TerrainLODManager`
+- `TerrainSABChannel`
+- `TerrainStreamingManager`
+- `allocateChunk`
+- `applyDeformation`
+- …and 10 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/surface-nets/src/chunked-field.ts

@@ -0,0 +1,14 @@
+// Re-export chunked voxel field utilities from the marching cubes plugin.
+// These are algorithm-agnostic — they only manage voxel data storage and
+// materialization. The actual mesh extraction is done separately via
+// extractMeshFromField from this plugin's surface-nets.ts.
+export {
+  allocateChunk,
+  createChunkedVoxelField,
+  getChunkedVoxel,
+  isChunkEmpty,
+  isChunkGenerated,
+  markChunkGenerated,
+  setChunkedVoxel,
+} from "@downdraft/engine/libraries/marching-cubes";
+export type { ChunkedVoxelField } from "@downdraft/engine/libraries/marching-cubes";

package/libraries/surface-nets/src/deformation.ts

@@ -0,0 +1,45 @@
+import type { ExtractedMesh } from "./types";
+import type { DensityField } from "./types";
+
+export interface DeformationConfig {
+  radius: number;
+  strength: number;
+  falloff: number;
+}
+
+// applyDeformation is algorithm-agnostic — it wraps a density field function.
+// Re-exported from MC plugin for convenience.
+export { applyDeformation, applyMultipleDeformations } from "@downdraft/engine/libraries/marching-cubes";
+
+/**
+ * Deform a surface nets mesh by displacing vertices within a spherical region.
+ * Unlike MC's deformChunk (which uses 3-float stride), surface nets vertices
+ * use 9-float stride (pos.xyz, normal.xyz, color.rgb).
+ */
+export function deformChunk(
+  mesh: ExtractedMesh,
+  deformPos: [number, number, number],
+  config: DeformationConfig,
+): ExtractedMesh {
+  const [dx, dy, dz] = deformPos;
+  const r = config.radius;
+  const strength = config.strength;
+  const falloff = config.falloff;
+
+  const verts = new Float32Array(mesh.verts);
+  const vertexCount = verts.length / 9;
+
+  for (let i = 0; i < vertexCount; i++) {
+    const offset = i * 9;
+    const vx = verts[offset];
+    const vy = verts[offset + 1];
+    const vz = verts[offset + 2];
+    const distSq = (vx - dx) ** 2 + (vy - dy) ** 2 + (vz - dz) ** 2;
+    if (distSq > r * r) continue;
+    const dist = Math.sqrt(distSq);
+    const t = 1 - (dist / r) ** falloff;
+    verts[offset + 1] += strength * t;
+  }
+
+  return { verts, indices: mesh.indices, useUint32: mesh.useUint32 };
+}

package/libraries/surface-nets/src/index.ts

@@ -0,0 +1,36 @@
+// Core algorithm
+export { extractMeshFromField } from "./surface-nets";
+export type { DensityField, ExtractMeshOptions, MeshColorFn } from "./types";
+
+// Shared types (re-exported from MC plugin)
+export type { ExtractedMesh, VoxelField } from "./types";
+
+// Chunked voxel field storage (re-exported from MC plugin)
+export {
+    allocateChunk, createChunkedVoxelField,
+    getChunkedVoxel, isChunkEmpty,
+    isChunkGenerated, markChunkGenerated, setChunkedVoxel
+} from "./chunked-field";
+export type { ChunkedVoxelField } from "./chunked-field";
+
+// Deformation
+export { applyDeformation, applyMultipleDeformations, deformChunk } from "./deformation";
+export type { DeformationConfig } from "./deformation";
+
+// LOD (re-exported from MC plugin)
+export { DEFAULT_LOD_LEVELS, TerrainLODManager } from "./lod";
+export type { ChunkLODEntry, LODLevel } from "./lod";
+
+// Streaming config (re-exported from MC plugin)
+export { DEFAULT_STREAMING_CONFIG, getLODVoxelSize } from "./streaming-config";
+export type { LODLevelConfig, TerrainStreamingConfig } from "./streaming-config";
+
+// Streaming manager (re-exported from MC plugin)
+export { TerrainStreamingManager } from "./streaming-manager";
+export type {
+    ChunkEmptyChecker, ChunkFieldFactory, ChunkGenerator, TerrainDeformation as Deformation, DirtyTerrain, TerrainEntityPosition as EntityPosition, TerrainLODChange as LODChange, PhysicsFieldFactory, TerrainEntry
+} from "./streaming-manager";
+
+// SAB channel (re-exported from MC plugin)
+export { TerrainChannel, TerrainSABChannel } from "./sab";
+export { SurfaceNetsLib, SurfaceNetsStreamingConfigTok } from "./library"; export type { SurfaceNetsLibConfig } from "./library";

package/libraries/surface-nets/src/library.ts

@@ -0,0 +1,59 @@
+// ============================================================================
+// SurfaceNetsLib — declarative engine library descriptor for @downdraft/engine/libraries/surface-nets
+//
+// Surface-nets is an alternative mesh extraction algorithm to marching cubes.
+// This library provides the extraction functions + chunked voxel field storage.
+// Games declare `libraries: [SurfaceNetsLib]` to get the streaming config and
+// mesh extraction utilities wired into the DI graph.
+//
+// Games that need full control can still import extractMeshFromField and
+// createChunkedVoxelField directly (escape hatch).
+// ============================================================================
+
+import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import { DEFAULT_STREAMING_CONFIG, type TerrainStreamingConfig } from "./streaming-config";
+
+// ── Config ──
+
+export interface SurfaceNetsLibConfig {
+  /** Terrain streaming config (LOD levels, voxel sizes, etc.). */
+  streaming?: Partial<TerrainStreamingConfig>;
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the surface-nets streaming config. */
+export const SurfaceNetsStreamingConfigTok = resourceToken<TerrainStreamingConfig>("surface-nets:streaming-config");
+
+// ── Descriptor ──
+
+export const SurfaceNetsLib: EngineLibrary<SurfaceNetsLibConfig> = {
+  name: "surface-nets",
+  version: "1.0.0",
+
+  // No SAB channels — surface-nets uses the same RPC/deformation model as
+  // marching-cubes. Games can add a SAB channel if they want zero-copy terrain.
+  sabChannels: [],
+
+  provides: [SurfaceNetsStreamingConfigTok],
+
+  sim: {
+    create(config, ctx) {
+      const streamingConfig = { ...DEFAULT_STREAMING_CONFIG, ...config.streaming };
+      ctx.provide(SurfaceNetsStreamingConfigTok, streamingConfig);
+      return { streamingConfig };
+    },
+    dispose(_system) {
+      // The system is a plain config object — no resources to free.
+    },
+    // tick is game-specific (calls lodManager.updateLOD(), mesh extraction, etc.)
+    // — games wire this via onReady.
+  },
+
+  tickPhase: "terrain",
+
+  // No renderer setup — terrain mesh generation is handled by the game's
+  // mesh worker pool, not by the library descriptor.
+
+  defaultConfig: {},
+};

package/libraries/surface-nets/src/lod.ts

@@ -0,0 +1,7 @@
+// Re-export LOD manager from the marching cubes plugin.
+// The LOD manager uses generateChunk (MC-specific) for its own chunk
+// generation, but the LOD selection logic (distance-based) is algorithm-agnostic.
+// Games that want surface nets LOD should use the streaming manager instead,
+// which delegates mesh extraction to a configurable function.
+export { DEFAULT_LOD_LEVELS, TerrainLODManager } from "@downdraft/engine/libraries/marching-cubes";
+export type { ChunkLODEntry, LODLevel } from "@downdraft/engine/libraries/marching-cubes";

package/libraries/surface-nets/src/sab.ts

@@ -0,0 +1,4 @@
+// Re-export SAB channel from the marching cubes plugin.
+// The SAB channel is a shared array buffer for terrain heightmap data —
+// it has no dependency on the mesh extraction algorithm.
+export { TerrainChannel, TerrainSABChannel } from "@downdraft/engine/libraries/marching-cubes";

package/libraries/surface-nets/src/streaming-config.ts

@@ -0,0 +1,5 @@
+// Re-export streaming config from the marching cubes plugin.
+// These configs are purely about voxel resolution and chunk sizes —
+// algorithm-agnostic.
+export { DEFAULT_STREAMING_CONFIG, getLODVoxelSize } from "@downdraft/engine/libraries/marching-cubes";
+export type { LODLevelConfig, TerrainStreamingConfig } from "@downdraft/engine/libraries/marching-cubes";

package/libraries/surface-nets/src/streaming-manager.ts

@@ -0,0 +1,15 @@
+// Re-export the streaming manager from the marching cubes plugin.
+// The streaming manager manages voxel field lifecycle (chunk generation,
+// LOD transitions, deformation batching) but does NOT perform mesh extraction.
+// Mesh extraction happens in the game layer (the game's terrain renderer) which
+// calls extractMeshFromField from whichever plugin is configured.
+//
+// Therefore the streaming manager is fully algorithm-agnostic and can be
+// re-exported as-is.
+export { TerrainStreamingManager } from "@downdraft/engine/libraries/marching-cubes";
+export type {
+    ChunkEmptyChecker,
+    ChunkFieldFactory,
+    ChunkGenerator, DirtyTerrain, PhysicsFieldFactory, TerrainDeformation, TerrainEntityPosition, TerrainEntry, TerrainLODChange
+} from "@downdraft/engine/libraries/marching-cubes";
+