@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/lighting/src/lighting-system.js

@@ -0,0 +1,57 @@
+// ============================================================================
+// Lighting System — directional sun/moon, ambient, bioluminescent
+// ============================================================================
+// Uses WeatherBlend from @downdraft/engine/libraries/weather for smooth transitions.
+//
+import { WeatherBlend } from "@downdraft/engine/libraries/weather";
+// Base sun brightness multiplier for PBR radiance — matches core engine default (3.0).
+// The raw sunIntensity (0..1) is kept for systems that use it as a blend factor (water, clouds).
+const SUN_BRIGHTNESS = 3.0;
+export class LightingSystem {
+    device;
+    weatherBlend;
+    // Pooled return object for getLightingParams (avoids per-frame allocation)
+    pooledResult = {
+        sunDir: [0, 0, 0],
+        sunIntensity: 0,
+        sunBrightness: 0,
+        moonDir: [0, 0, 0],
+        moonIntensity: 0,
+        ambient: 0,
+        fogDensity: 0,
+        wetness: 0,
+        fogColor: [0.0, 0.1, 0.2],
+    };
+    constructor(device) {
+        this.device = device;
+        this.weatherBlend = new WeatherBlend(30.0);
+    }
+    // Calculate lighting parameters based on time of day and weather
+    getLightingParams(timeOfDay, weatherType, visibility) {
+        const sunAngle = timeOfDay * Math.PI * 2 - Math.PI / 2;
+        const cosA = Math.cos(sunAngle);
+        const sinA = Math.sin(sunAngle);
+        const rawZ = 0.3;
+        const sunLen = Math.sqrt(cosA * cosA + sinA * sinA + rawZ * rawZ);
+        const result = this.pooledResult;
+        result.sunDir[0] = cosA / sunLen;
+        result.sunDir[1] = sinA / sunLen;
+        result.sunDir[2] = rawZ / sunLen;
+        result.moonDir[0] = -result.sunDir[0];
+        result.moonDir[1] = -result.sunDir[1];
+        result.moonDir[2] = -result.sunDir[2];
+        result.moonIntensity = Math.max(0, -sinA);
+        // Blend lighting using the shared WeatherBlend from the plugin
+        const blended = this.weatherBlend.getLightingParams(timeOfDay, weatherType, visibility);
+        result.ambient = blended.ambient;
+        result.sunIntensity = blended.sunIntensity;
+        result.wetness = blended.wetness;
+        result.sunBrightness = blended.sunIntensity * SUN_BRIGHTNESS;
+        // Visibility affects fog distance
+        result.fogDensity = (1 - visibility) * 0.01;
+        return result;
+    }
+    updateWeatherBlend(weatherType, dt) {
+        this.weatherBlend.update(weatherType, dt);
+    }
+}

package/dist/libraries/lighting/src/shaders/light-debug.wgsl

@@ -0,0 +1,30 @@
+struct Uniforms {
+  viewProj: mat4x4<f32>,
+};
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+
+struct VertexInput {
+  @location(0) position: vec3<f32>,
+  @location(1) instancePos: vec3<f32>,
+  @location(2) instanceRadius: f32,
+  @location(3) instanceColor: vec3<f32>,
+};
+
+struct VertexOutput {
+  @builtin(position) clipPos: vec4<f32>,
+  @location(0) color: vec3<f32>,
+};
+
+@vertex
+fn vs_main(input: VertexInput) -> VertexOutput {
+  var output: VertexOutput;
+  let worldPos = input.position * input.instanceRadius + input.instancePos;
+  output.clipPos = uniforms.viewProj * vec4<f32>(worldPos, 1.0);
+  output.color = input.instanceColor;
+  return output;
+}
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  return vec4<f32>(input.color, 0.4);
+}

package/dist/libraries/marching-cubes/src/chunked-field.js

@@ -0,0 +1,130 @@
+// ============================================================================
+// ChunkedVoxelField — chunked voxel storage for on-demand generation
+// ============================================================================
+// Stores voxel data in fixed-size chunks for memory-efficient terrain.
+// Only non-empty chunks are allocated in the buffer, indexed via chunkOffsets.
+//
+// Chunk classification (chunkClass) reduces memory by skipping chunks that are
+// entirely solid (FullSolid) or entirely empty (FullEmpty) — only surface chunks
+// (Full) get buffer space allocated.
+//
+export const CHUNK_EMPTY = 0; // FullEmpty: all voxels below isoLevel
+export const CHUNK_SOLID = 1; // FullSolid: all voxels above isoLevel
+export const CHUNK_FULL = 2; // Full: contains surface, needs buffer storage
+export function createChunkedVoxelField(chunkX, chunkZ, radius, voxelSize, dimX, dimY, dimZ, originX, originY, originZ, isoLevel = 0.0, chunkSize = 32, isPort = false, maxVoxelMemory = 160_000_000) {
+    const chunkBits = Math.log2(chunkSize) | 0;
+    const chunkMask = chunkSize - 1;
+    const chunkDimX = Math.ceil(dimX / chunkSize);
+    const chunkDimY = Math.ceil(dimY / chunkSize);
+    const chunkDimZ = Math.ceil(dimZ / chunkSize);
+    const voxelsPerChunk = chunkSize * chunkSize * chunkSize;
+    const totalChunks = chunkDimX * chunkDimY * chunkDimZ;
+    const maxFloats = Math.floor(maxVoxelMemory / 4);
+    const maxChunkSlots = Math.floor(maxFloats / voxelsPerChunk);
+    const totalChunkSlots = Math.min(totalChunks, maxChunkSlots);
+    const buffer = new ArrayBuffer(totalChunkSlots * voxelsPerChunk * 4);
+    const view = new Float32Array(buffer);
+    const chunkOffsets = new Int32Array(totalChunks).fill(-1);
+    const chunkGenerated = new Uint8Array(totalChunks);
+    const chunkClass = new Uint8Array(totalChunks); // default 0 = FullEmpty
+    return {
+        dimX, dimY, dimZ,
+        voxelSize,
+        originX, originY, originZ,
+        isoLevel,
+        radius,
+        chunkSize, chunkBits, chunkMask,
+        chunkDimX, chunkDimY, chunkDimZ,
+        voxelsPerChunk,
+        buffer, view,
+        chunkOffsets, chunkGenerated, chunkClass,
+        totalChunkSlots,
+        nextChunkOffset: 0,
+        chunkX, chunkZ,
+        isPort,
+    };
+}
+export function getChunkedVoxel(field, x, y, z) {
+    if (x < 0 || x >= field.dimX || y < 0 || y >= field.dimY || z < 0 || z >= field.dimZ)
+        return -1.0;
+    const cx = x >>> field.chunkBits;
+    const cy = y >>> field.chunkBits;
+    const cz = z >>> field.chunkBits;
+    const chunkIdx = cx * field.chunkDimY * field.chunkDimZ + cy * field.chunkDimZ + cz;
+    const cls = field.chunkClass[chunkIdx];
+    if (cls === CHUNK_SOLID)
+        return 1.0; // FullSolid sentinel
+    if (cls === CHUNK_EMPTY)
+        return -1.0; // FullEmpty sentinel
+    // CHUNK_FULL: look up in buffer
+    const offset = field.chunkOffsets[chunkIdx];
+    if (offset < 0)
+        return -1.0;
+    const lx = x & field.chunkMask;
+    const ly = y & field.chunkMask;
+    const lz = z & field.chunkMask;
+    const cs = field.chunkSize;
+    return field.view[offset + lx * cs * cs + ly * cs + lz];
+}
+export function setChunkedVoxel(field, x, y, z, value) {
+    if (x < 0 || x >= field.dimX || y < 0 || y >= field.dimY || z < 0 || z >= field.dimZ)
+        return;
+    const cx = x >>> field.chunkBits;
+    const cy = y >>> field.chunkBits;
+    const cz = z >>> field.chunkBits;
+    const chunkIdx = cx * field.chunkDimY * field.chunkDimZ + cy * field.chunkDimZ + cz;
+    const cls = field.chunkClass[chunkIdx];
+    if (cls !== CHUNK_FULL)
+        return; // Only write to Full chunks; others need promotion first
+    const offset = field.chunkOffsets[chunkIdx];
+    if (offset < 0)
+        return;
+    const lx = x & field.chunkMask;
+    const ly = y & field.chunkMask;
+    const lz = z & field.chunkMask;
+    const cs = field.chunkSize;
+    field.view[offset + lx * cs * cs + ly * cs + lz] = value;
+}
+export function isChunkEmpty(field, chunkIdx) {
+    return field.chunkOffsets[chunkIdx] < 0;
+}
+export function isChunkGenerated(field, chunkIdx) {
+    return field.chunkGenerated[chunkIdx] === 1;
+}
+export function allocateChunk(field, chunkIdx) {
+    if (chunkIdx < 0 || chunkIdx >= field.chunkOffsets.length)
+        return -1;
+    if (field.chunkOffsets[chunkIdx] >= 0)
+        return field.chunkOffsets[chunkIdx];
+    if (field.nextChunkOffset + field.voxelsPerChunk > field.view.length)
+        return -1;
+    const offset = field.nextChunkOffset;
+    field.nextChunkOffset += field.voxelsPerChunk;
+    field.chunkOffsets[chunkIdx] = offset;
+    field.chunkClass[chunkIdx] = CHUNK_FULL;
+    return offset;
+}
+export function markChunkGenerated(field, chunkIdx) {
+    field.chunkGenerated[chunkIdx] = 1;
+}
+// Promote a FullSolid or FullEmpty chunk to Full so it can be deformed.
+// Allocates buffer space and returns the offset, or -1 if no space.
+export function promoteChunk(field, chunkIdx) {
+    if (field.chunkClass[chunkIdx] === CHUNK_FULL && field.chunkOffsets[chunkIdx] >= 0) {
+        return field.chunkOffsets[chunkIdx];
+    }
+    const offset = allocateChunk(field, chunkIdx);
+    if (offset < 0)
+        return -1;
+    // Fill with sentinel values based on previous class
+    const vpc = field.voxelsPerChunk;
+    if (field.chunkClass[chunkIdx] === CHUNK_SOLID || field.chunkClass[chunkIdx] === CHUNK_FULL) {
+        field.view.fill(1.0, offset, offset + vpc);
+    }
+    else {
+        field.view.fill(-1.0, offset, offset + vpc);
+    }
+    field.chunkClass[chunkIdx] = CHUNK_FULL;
+    field.chunkGenerated[chunkIdx] = 1; // mark as generated (sentinel data)
+    return offset;
+}

package/dist/libraries/marching-cubes/src/deformation.js

@@ -0,0 +1,41 @@
+export function applyDeformation(field, deformPos, config) {
+    const [dx, dy, dz] = deformPos;
+    const r = config.radius;
+    const strength = config.strength;
+    const falloff = config.falloff;
+    return (x, y, z) => {
+        const distSq = (x - dx) ** 2 + (y - dy) ** 2 + (z - dz) ** 2;
+        if (distSq > r * r)
+            return field(x, y, z);
+        const dist = Math.sqrt(distSq);
+        const t = 1 - (dist / r) ** falloff;
+        return field(x, y, z) + strength * t;
+    };
+}
+export function applyMultipleDeformations(field, deformations) {
+    let result = field;
+    deformations.forEach((def) => {
+        result = applyDeformation(result, def.pos, def.config);
+    });
+    return result;
+}
+export function deformChunk(mesh, deformPos, config) {
+    const [dx, dy, dz] = deformPos;
+    const r = config.radius;
+    const strength = config.strength;
+    const falloff = config.falloff;
+    const vertices = new Float32Array(mesh.vertices);
+    for (let i = 0; i < mesh.vertexCount; i++) {
+        const offset = i * 3;
+        const vx = vertices[offset];
+        const vy = vertices[offset + 1];
+        const vz = vertices[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;
+        vertices[offset + 1] += strength * t;
+    }
+    return { ...mesh, vertices };
+}

package/dist/libraries/marching-cubes/src/generator.js

@@ -0,0 +1,356 @@
+import { EDGE_VERTS, MC_EDGE_TABLE, MC_TRI_TABLE } from "./tables.js";
+export const DEFAULT_MC_CONFIG = {
+    chunkSize: 32,
+    isoLevel: 0.5,
+    scale: 1.0,
+};
+export function generateChunk(originX, originY, originZ, densityField, config) {
+    const size = config.chunkSize;
+    const isoLevel = config.isoLevel;
+    const scale = config.scale;
+    const verts = [];
+    const norms = [];
+    const indices = [];
+    const corners = new Float32Array(8);
+    const cornerPos = [];
+    for (let z = 0; z < size - 1; z++) {
+        for (let y = 0; y < size - 1; y++) {
+            for (let x = 0; x < size - 1; x++) {
+                const wx = originX + x * scale;
+                const wy = originY + y * scale;
+                const wz = originZ + z * scale;
+                cornerPos[0] = [wx, wy, wz];
+                cornerPos[1] = [wx + scale, wy, wz];
+                cornerPos[2] = [wx + scale, wy, wz + scale];
+                cornerPos[3] = [wx, wy, wz + scale];
+                cornerPos[4] = [wx, wy + scale, wz];
+                cornerPos[5] = [wx + scale, wy + scale, wz];
+                cornerPos[6] = [wx + scale, wy + scale, wz + scale];
+                cornerPos[7] = [wx, wy + scale, wz + scale];
+                for (let i = 0; i < 8; i++) {
+                    corners[i] = densityField(cornerPos[i][0], cornerPos[i][1], cornerPos[i][2]);
+                }
+                let cubeIndex = 0;
+                for (let i = 0; i < 8; i++) {
+                    if (corners[i] < isoLevel)
+                        cubeIndex |= (1 << i);
+                }
+                if (cubeIndex === 0 || cubeIndex === 255)
+                    continue;
+                const edges = MC_EDGE_TABLE[cubeIndex];
+                if (edges === 0)
+                    continue;
+                const edgeVerts = new Array(12).fill(null);
+                for (let i = 0; i < 12; i++) {
+                    if (edges & (1 << i)) {
+                        const [a, b] = EDGE_VERTS[i];
+                        const va = corners[a];
+                        const vb = corners[b];
+                        const t = (isoLevel - va) / (vb - va);
+                        const pa = cornerPos[a];
+                        const pb = cornerPos[b];
+                        edgeVerts[i] = [
+                            pa[0] + t * (pb[0] - pa[0]),
+                            pa[1] + t * (pb[1] - pa[1]),
+                            pa[2] + t * (pb[2] - pa[2]),
+                        ];
+                    }
+                }
+                const triOffset = cubeIndex * 16;
+                for (let i = 0; i < 16; i += 3) {
+                    const e0 = MC_TRI_TABLE[triOffset + i];
+                    if (e0 < 0)
+                        break;
+                    const e1 = MC_TRI_TABLE[triOffset + i + 1];
+                    const e2 = MC_TRI_TABLE[triOffset + i + 2];
+                    const v0 = edgeVerts[e0];
+                    const v1 = edgeVerts[e1];
+                    const v2 = edgeVerts[e2];
+                    if (!v0 || !v1 || !v2)
+                        continue;
+                    const baseIdx = verts.length / 3;
+                    verts.push(v0[0], v0[1], v0[2]);
+                    verts.push(v1[0], v1[1], v1[2]);
+                    verts.push(v2[0], v2[1], v2[2]);
+                    const ex1 = v1[0] - v0[0];
+                    const ey1 = v1[1] - v0[1];
+                    const ez1 = v1[2] - v0[2];
+                    const ex2 = v2[0] - v0[0];
+                    const ey2 = v2[1] - v0[1];
+                    const ez2 = v2[2] - v0[2];
+                    let nx = ey1 * ez2 - ez1 * ey2;
+                    let ny = ez1 * ex2 - ex1 * ez2;
+                    let nz = ex1 * ey2 - ey1 * ex2;
+                    const nlen = Math.sqrt(nx * nx + ny * ny + nz * nz);
+                    if (nlen > 1e-9) {
+                        nx /= nlen;
+                        ny /= nlen;
+                        nz /= nlen;
+                    }
+                    else {
+                        nx = 0;
+                        ny = 1;
+                        nz = 0;
+                    }
+                    norms.push(nx, ny, nz);
+                    norms.push(nx, ny, nz);
+                    norms.push(nx, ny, nz);
+                    indices.push(baseIdx, baseIdx + 1, baseIdx + 2);
+                }
+            }
+        }
+    }
+    return {
+        vertices: new Float32Array(verts),
+        normals: new Float32Array(norms),
+        indices: new Uint32Array(indices),
+        vertexCount: verts.length / 3,
+        indexCount: indices.length,
+    };
+}
+export function defaultDensityField(x, y, z, maxHeight = 20, noiseScale = 0.05) {
+    const height = y / maxHeight;
+    const noise = simpleNoise(x * noiseScale, y * noiseScale, z * noiseScale);
+    return height - noise;
+}
+function simpleNoise(x, y, z) {
+    const a = Math.sin(x * 12.9898 + y * 78.233 + z * 37.719) * 43758.5453;
+    const b = Math.sin(x * 4.1231 + y * 12.7891 + z * 93.985) * 23421.6312;
+    const c = Math.sin(x * 8.7543 + y * 45.1234 + z * 73.456) * 17909.231;
+    return ((a - Math.floor(a)) + (b - Math.floor(b)) + (c - Math.floor(c))) / 3;
+}
+// ============================================================================
+// Full-featured mesh extraction — VoxelField-based with sub-region, coloring,
+// normal flipping, typed-array scratch buffers, and Uint16/Uint32 index support.
+// ============================================================================
+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],
+];
+const SCRATCH_D = new Float32Array(8);
+const SCRATCH_EDGE_VERTS = new Float32Array(12 * 3);
+function ensureCapacity(arr, needed) {
+    if (arr.length >= needed)
+        return arr;
+    let newLen = arr.length * 2;
+    while (newLen < needed)
+        newLen *= 2;
+    const MAX_FIELD_SIZE = 100_000_000;
+    if (newLen > MAX_FIELD_SIZE)
+        throw new Error(`Field capacity exceeded: ${newLen}`);
+    const newArr = new Float32Array(newLen);
+    newArr.set(arr);
+    return newArr;
+}
+function ensureCapacityU32(arr, needed) {
+    if (arr.length >= needed)
+        return arr;
+    let newLen = arr.length * 2;
+    while (newLen < needed)
+        newLen *= 2;
+    const MAX_FIELD_SIZE = 100_000_000;
+    if (newLen > MAX_FIELD_SIZE)
+        throw new Error(`Field capacity exceeded: ${newLen}`);
+    const newArr = new Uint32Array(newLen);
+    newArr.set(arr);
+    return newArr;
+}
+function ensureCapacityU16(arr, needed) {
+    if (arr.length >= needed)
+        return arr;
+    let newLen = arr.length * 2;
+    while (newLen < needed)
+        newLen *= 2;
+    const MAX_FIELD_SIZE = 100_000_000;
+    if (newLen > MAX_FIELD_SIZE)
+        throw new Error(`Field capacity exceeded: ${newLen}`);
+    const newArr = new Uint16Array(newLen);
+    newArr.set(arr);
+    return newArr;
+}
+export function extractMeshFromField(field, options = {}) {
+    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 = new Float32Array(65536);
+    let vertCount = 0;
+    let indices32 = new Uint32Array(32768);
+    let indices16 = new Uint16Array(32768);
+    let indexCount = 0;
+    let useUint32 = false;
+    const d = SCRATCH_D;
+    const edgeVerts = SCRATCH_EDGE_VERTS;
+    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++) {
+                let cubeIndex = 0;
+                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];
+                    let val;
+                    if (cx < 0 || cx >= field.dimX || cy < 0 || cy >= field.dimY || cz < 0 || cz >= field.dimZ) {
+                        val = -1.0;
+                    }
+                    else {
+                        val = field.data[cx * dimYDimZ + cy * dimZ + cz];
+                    }
+                    d[c] = val;
+                    if (val < iso)
+                        cubeIndex |= (1 << c);
+                }
+                const edges = MC_EDGE_TABLE[cubeIndex];
+                if (edges === 0)
+                    continue;
+                for (let e = 0; e < 12; e++) {
+                    if (!(edges & (1 << e)))
+                        continue;
+                    const conn = EDGE_VERTS[e];
+                    const c1 = conn[0], c2 = conn[1];
+                    const co1 = CORNER_OFFSET[c1];
+                    const co2 = CORNER_OFFSET[c2];
+                    const p1x = (x + co1[0]) * vs + ox, p1y = (y + co1[1]) * vs + oy, p1z = (z + co1[2]) * vs + oz;
+                    const p2x = (x + co2[0]) * vs + ox, p2y = (y + co2[1]) * vs + oy, p2z = (z + co2[2]) * vs + oz;
+                    const d1 = d[c1], d2 = d[c2];
+                    let ex, ey, ez;
+                    if (Math.abs(iso - d1) < 1e-10) {
+                        ex = p1x;
+                        ey = p1y;
+                        ez = p1z;
+                    }
+                    else if (Math.abs(iso - d2) < 1e-10) {
+                        ex = p2x;
+                        ey = p2y;
+                        ez = p2z;
+                    }
+                    else if (Math.abs(d1 - d2) < 1e-10) {
+                        ex = p1x;
+                        ey = p1y;
+                        ez = p1z;
+                    }
+                    else {
+                        const t = (iso - d1) / (d2 - d1);
+                        ex = p1x + t * (p2x - p1x);
+                        ey = p1y + t * (p2y - p1y);
+                        ez = p1z + t * (p2z - p1z);
+                    }
+                    const eo = e * 3;
+                    edgeVerts[eo] = ex;
+                    edgeVerts[eo + 1] = ey;
+                    edgeVerts[eo + 2] = ez;
+                }
+                const triBase = cubeIndex * 16;
+                for (let t = 0; t < 15; t += 3) {
+                    const e0 = MC_TRI_TABLE[triBase + t];
+                    if (e0 < 0)
+                        break;
+                    const e1 = MC_TRI_TABLE[triBase + t + 1];
+                    const e2 = MC_TRI_TABLE[triBase + t + 2];
+                    const ev0o = e0 * 3, ev1o = e1 * 3, ev2o = e2 * 3;
+                    const v0x = edgeVerts[ev0o], v0y = edgeVerts[ev0o + 1], v0z = edgeVerts[ev0o + 2];
+                    const v1x = edgeVerts[ev1o], v1y = edgeVerts[ev1o + 1], v1z = edgeVerts[ev1o + 2];
+                    const v2x = edgeVerts[ev2o], v2y = edgeVerts[ev2o + 1], v2z = edgeVerts[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];
+                    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,
+        useUint32,
+    };
+}

package/dist/libraries/marching-cubes/src/index.js

@@ -0,0 +1,13 @@
+export { applyDeformation, applyMultipleDeformations, deformChunk } from "./deformation.js";
+export { DEFAULT_MC_CONFIG, defaultDensityField, extractMeshFromField, generateChunk } from "./generator.js";
+export { DEFAULT_LOD_LEVELS, TerrainLODManager } from "./lod.js";
+export { extractMeshFromFieldTetra } from "./marching-tetrahedra.js";
+export { TerrainChannel, TerrainSABChannel } from "./sab.js";
+// Chunked voxel field storage
+export { allocateChunk, CHUNK_EMPTY, CHUNK_FULL, CHUNK_SOLID, createChunkedVoxelField, getChunkedVoxel, isChunkEmpty, isChunkGenerated, markChunkGenerated, promoteChunk, setChunkedVoxel } from "./chunked-field.js";
+// Terrain streaming config
+export { DEFAULT_STREAMING_CONFIG, getLODVoxelSize } from "./streaming-config.js";
+// Declarative library descriptor
+export { MarchingCubesLib, TerrainStreamingConfigTok } from "./library.js";
+// Terrain streaming manager
+export { TerrainStreamingManager } from "./streaming-manager.js";

package/dist/libraries/marching-cubes/src/library.js

@@ -0,0 +1,54 @@
+// ============================================================================
+// 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 } from "@downdraft/engine";
+import { TerrainChannel } from "./sab.js";
+import { DEFAULT_STREAMING_CONFIG } from "./streaming-config.js";
+// ── Typed tokens (DI) ──
+/** Token for the terrain streaming config. */
+export const TerrainStreamingConfigTok = resourceToken("terrain:streaming-config");
+// ── Descriptor ──
+export const MarchingCubesLib = {
+    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,
+    },
+};