@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/voxel/mesher.js

@@ -0,0 +1,306 @@
+import { VERTEX3D_FLOATS } from '../render/mesh.js';
+/** Outward normal of each `VoxelFace`. */
+export const VOXEL_FACE_NORMALS = [
+    [1, 0, 0],
+    [-1, 0, 0],
+    [0, 1, 0],
+    [0, -1, 0],
+    [0, 0, 1],
+    [0, 0, -1],
+];
+/** Default AO curve: corner level (0 darkest .. 3 open) → vertex brightness. */
+export const VOXEL_AO_CURVE = [0.42, 0.62, 0.82, 1];
+/** Floats per vertex of the mesher's output (`VERTEX_LAYOUT_3D`). */
+export const VOXEL_VERTEX_FLOATS = VERTEX3D_FLOATS;
+/** Output buffers with room for `quads` quads before the first growth. */
+export function createChunkMeshOut(quads = 1024) {
+    return {
+        vertices: new Float32Array(quads * 4 * VOXEL_VERTEX_FLOATS),
+        indices: new Uint32Array(quads * 6),
+        vertexCount: 0,
+        indexCount: 0,
+        bounds: { center: [0, 0, 0], radius: 0 },
+    };
+}
+const defaultLayer = (block) => block - 1;
+/** Growth factor of `ChunkMeshOut` buffers (1.5×, a vector's amortised growth). */
+const GROWTH = 1.5;
+let mask = new Int32Array(0);
+const p = [0, 0, 0];
+const n = [0, 0, 0];
+const ea = [0, 0, 0];
+const eb = [0, 0, 0];
+const extent = [0, 0, 0];
+const corners = new Int32Array(4);
+const aoLevels = new Int32Array(4);
+/**
+ * Mesh chunk (`cx`, `cy`, `cz`) of `grid` into `out`. Returns `out`. Every quad is planar on
+ * its face's axis, winds counter-clockwise seen from outside (both triangles) and its vertex
+ * normal is the face's normal. `out.vertexCount` 0 means an empty chunk.
+ */
+export function meshChunk(grid, cx, cy, cz, opts, out) {
+    const size = grid.chunk;
+    if (mask.length < size * size)
+        mask = new Int32Array(size * size);
+    const ao = opts.ao ?? true;
+    const curve = opts.aoCurve ?? VOXEL_AO_CURVE;
+    const layerOf = opts.layerOf ?? defaultLayer;
+    const outside = opts.outside ?? 0;
+    const outsideFn = typeof outside === 'function' ? outside : null;
+    const outsideBlock = typeof outside === 'number' ? outside : 0;
+    const data = grid.data;
+    const sx = grid.sizeX;
+    const sy = grid.sizeY;
+    const sz = grid.sizeZ;
+    const ox = cx * size;
+    const oy = cy * size;
+    const oz = cz * size;
+    extent[0] = Math.min(size, sx - ox);
+    extent[1] = Math.min(size, sy - oy);
+    extent[2] = Math.min(size, sz - oz);
+    const at = (x, y, z) => {
+        if (x >= 0 && y >= 0 && z >= 0 && x < sx && y < sy && z < sz) {
+            return data[x + sx * (y + sy * z)];
+        }
+        return outsideFn ? outsideFn(x, y, z) : outsideBlock;
+    };
+    let vf = 0; // floats written
+    let ic = 0; // indices written
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let d = 0; d < 3; d++) {
+        // (a, b, d) is a cyclic permutation of (x, y, z): a × b = d, so corners emitted in
+        // (a0,b0) (a1,b0) (a1,b1) (a0,b1) order wind counter-clockwise seen from +d.
+        const a = (d + 1) % 3;
+        const b = (d + 2) % 3;
+        ea[0] = ea[1] = ea[2] = 0;
+        eb[0] = eb[1] = eb[2] = 0;
+        ea[a] = 1;
+        eb[b] = 1;
+        const na = extent[a];
+        const nb = extent[b];
+        const nd = extent[d];
+        for (let dir = 1; dir >= -1; dir -= 2) {
+            const face = (d * 2 + (dir > 0 ? 0 : 1));
+            n[0] = n[1] = n[2] = 0;
+            n[d] = dir;
+            for (let k = 0; k < nd; k++) {
+                // The mask of this slice.
+                let any = false;
+                for (let j = 0; j < nb; j++) {
+                    for (let i = 0; i < na; i++) {
+                        p[d] = k;
+                        p[a] = i;
+                        p[b] = j;
+                        const wx = ox + p[0];
+                        const wy = oy + p[1];
+                        const wz = oz + p[2];
+                        const block = data[wx + sx * (wy + sy * wz)];
+                        let key = 0;
+                        if (block !== 0) {
+                            const qx = wx + n[0];
+                            const qy = wy + n[1];
+                            const qz = wz + n[2];
+                            if (at(qx, qy, qz) === 0) {
+                                key = 1 | ((layerOf(block, face) & 0xff) << 1);
+                                if (ao) {
+                                    for (let slot = 0; slot < 4; slot++) {
+                                        const sa = slot & 1 ? 1 : -1;
+                                        const sb = slot & 2 ? 1 : -1;
+                                        const s1 = at(qx + sa * ea[0], qy + sa * ea[1], qz + sa * ea[2]) !== 0 ? 1 : 0;
+                                        const s2 = at(qx + sb * eb[0], qy + sb * eb[1], qz + sb * eb[2]) !== 0 ? 1 : 0;
+                                        let level;
+                                        if (s1 && s2)
+                                            level = 0;
+                                        else {
+                                            const c = at(qx + sa * ea[0] + sb * eb[0], qy + sa * ea[1] + sb * eb[1], qz + sa * ea[2] + sb * eb[2]) !== 0
+                                                ? 1
+                                                : 0;
+                                            level = 3 - (s1 + s2 + c);
+                                        }
+                                        key |= level << (9 + 2 * slot);
+                                    }
+                                }
+                                any = true;
+                            }
+                        }
+                        mask[i + size * j] = key;
+                    }
+                }
+                if (!any)
+                    continue;
+                // Greedy merge.
+                for (let j = 0; j < nb; j++) {
+                    for (let i = 0; i < na;) {
+                        const key = mask[i + size * j];
+                        if (key === 0) {
+                            i++;
+                            continue;
+                        }
+                        let w = 1;
+                        while (i + w < na && mask[i + w + size * j] === key)
+                            w++;
+                        let h = 1;
+                        outer: while (j + h < nb) {
+                            for (let t = 0; t < w; t++) {
+                                if (mask[i + t + size * (j + h)] !== key)
+                                    break outer;
+                            }
+                            h++;
+                        }
+                        for (let hh = 0; hh < h; hh++) {
+                            for (let t = 0; t < w; t++)
+                                mask[i + t + size * (j + hh)] = 0;
+                        }
+                        // Emit the quad: the plane sits at d = k (+1 for the positive face).
+                        if (vf + 4 * VOXEL_VERTEX_FLOATS > out.vertices.length) {
+                            const bigger = new Float32Array(Math.ceil(out.vertices.length * GROWTH));
+                            bigger.set(out.vertices);
+                            out.vertices = bigger;
+                        }
+                        if (ic + 6 > out.indices.length) {
+                            const bigger = new Uint32Array(Math.ceil(out.indices.length * GROWTH));
+                            bigger.set(out.indices);
+                            out.indices = bigger;
+                        }
+                        const verts = out.vertices;
+                        const layer = (key >> 1) & 0xff;
+                        const plane = k + (dir > 0 ? 1 : 0);
+                        const base = vf / VOXEL_VERTEX_FLOATS;
+                        for (let c = 0; c < 4; c++) {
+                            // Corner order (a0,b0) (a1,b0) (a1,b1) (a0,b1); reversed for the negative face.
+                            const cc = dir > 0 ? c : (4 - c) % 4;
+                            const ha = cc === 1 || cc === 2 ? 1 : 0;
+                            const hb = cc === 2 || cc === 3 ? 1 : 0;
+                            const ac = i + ha * w;
+                            const bc = j + hb * h;
+                            p[d] = plane;
+                            p[a] = ac;
+                            p[b] = bc;
+                            const px = p[0];
+                            const py = p[1];
+                            const pz = p[2];
+                            if (px < minX)
+                                minX = px;
+                            if (py < minY)
+                                minY = py;
+                            if (pz < minZ)
+                                minZ = pz;
+                            if (px > maxX)
+                                maxX = px;
+                            if (py > maxY)
+                                maxY = py;
+                            if (pz > maxZ)
+                                maxZ = pz;
+                            verts[vf] = px;
+                            verts[vf + 1] = py;
+                            verts[vf + 2] = pz;
+                            verts[vf + 3] = n[0];
+                            verts[vf + 4] = n[1];
+                            verts[vf + 5] = n[2];
+                            // uv in block units: u along the horizontal axis, v downward from the quad's top.
+                            let u;
+                            let v;
+                            if (d === 0) {
+                                // a = y (vertical), b = z.
+                                u = bc - j;
+                                v = i + w - ac;
+                            }
+                            else if (d === 2) {
+                                // a = x, b = y (vertical).
+                                u = ac - i;
+                                v = j + h - bc;
+                            }
+                            else {
+                                u = ac - i;
+                                v = bc - j;
+                            }
+                            verts[vf + 6] = u;
+                            verts[vf + 7] = v;
+                            const slot = ha | (hb << 1);
+                            const level = ao ? (key >> (9 + 2 * slot)) & 3 : 3;
+                            const bright = ao ? (curve[level] ?? 1) : 1;
+                            aoLevels[c] = level;
+                            verts[vf + 8] = bright;
+                            verts[vf + 9] = bright;
+                            verts[vf + 10] = bright;
+                            verts[vf + 11] = layer;
+                            corners[c] = base + c;
+                            vf += VOXEL_VERTEX_FLOATS;
+                        }
+                        // Split along the diagonal whose corners are darker, so the dark pair shares an edge.
+                        const idx = out.indices;
+                        if (aoLevels[0] + aoLevels[2] > aoLevels[1] + aoLevels[3]) {
+                            idx[ic++] = corners[1];
+                            idx[ic++] = corners[2];
+                            idx[ic++] = corners[3];
+                            idx[ic++] = corners[1];
+                            idx[ic++] = corners[3];
+                            idx[ic++] = corners[0];
+                        }
+                        else {
+                            idx[ic++] = corners[0];
+                            idx[ic++] = corners[1];
+                            idx[ic++] = corners[2];
+                            idx[ic++] = corners[0];
+                            idx[ic++] = corners[2];
+                            idx[ic++] = corners[3];
+                        }
+                        i += w;
+                    }
+                }
+            }
+        }
+    }
+    out.vertexCount = vf / VOXEL_VERTEX_FLOATS;
+    out.indexCount = ic;
+    const bounds = out.bounds;
+    if (vf === 0) {
+        bounds.center[0] = bounds.center[1] = bounds.center[2] = 0;
+        bounds.radius = 0;
+    }
+    else {
+        bounds.center[0] = (minX + maxX) / 2;
+        bounds.center[1] = (minY + maxY) / 2;
+        bounds.center[2] = (minZ + maxZ) / 2;
+        bounds.radius = Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2;
+    }
+    return out;
+}
+/**
+ * Exposed faces of chunk (`cx`, `cy`, `cz`) counted one cell at a time (no merging): the
+ * reference the mesher's quads must cover exactly. Each quad of `meshChunk` covers
+ * `w × h` of these, so a test sums quad areas against it. Same `outside` rule.
+ */
+export function countExposedFaces(grid, cx, cy, cz, outside = 0) {
+    const size = grid.chunk;
+    const x0 = cx * size;
+    const y0 = cy * size;
+    const z0 = cz * size;
+    const x1 = Math.min(grid.sizeX, x0 + size);
+    const y1 = Math.min(grid.sizeY, y0 + size);
+    const z1 = Math.min(grid.sizeZ, z0 + size);
+    const at = (x, y, z) => grid.inBounds(x, y, z)
+        ? grid.get(x, y, z)
+        : typeof outside === 'function'
+            ? outside(x, y, z)
+            : outside;
+    let faces = 0;
+    for (let z = z0; z < z1; z++) {
+        for (let y = y0; y < y1; y++) {
+            for (let x = x0; x < x1; x++) {
+                if (grid.get(x, y, z) === 0)
+                    continue;
+                for (const [nx, ny, nz] of VOXEL_FACE_NORMALS) {
+                    if (at(x + nx, y + ny, z + nz) === 0)
+                        faces++;
+                }
+            }
+        }
+    }
+    return faces;
+}

package/dist/voxel/ray.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Block picking: a ray walked cell by cell through a `VoxelGrid` (Amanatides & Woo's DDA).
+ * Grid units are world units with the grid's corner at the origin; a world placed elsewhere
+ * subtracts its origin from the ray first. Pure, no allocation.
+ */
+import type { VoxelGrid } from './grid.js';
+/** What `raycastVoxels` fills on a hit. */
+export interface VoxelHit {
+    /** The solid cell hit. */
+    x: number;
+    y: number;
+    z: number;
+    /** Outward normal of the face entered (one unit axis; all zero when the ray starts inside a block). */
+    nx: number;
+    ny: number;
+    nz: number;
+    /** The empty cell in front of that face: where a placed block goes (the hit cell itself when inside). */
+    px: number;
+    py: number;
+    pz: number;
+    /** Ray parameter of the hit, in units of the direction's length (world units for a unit direction). */
+    distance: number;
+}
+/** A hit record to fill. */
+export declare function createVoxelHit(): VoxelHit;
+/**
+ * Walk the ray from (`ox`, `oy`, `oz`) along (`dx`, `dy`, `dz`) up to `maxDist` (in units of
+ * the direction's length) through `grid`, returning true and filling `out` at the first
+ * non-air cell. Cells outside the grid are air. A ray starting inside a block hits it at
+ * distance 0 with a zero normal.
+ */
+export declare function raycastVoxels(grid: VoxelGrid, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist: number, out: VoxelHit): boolean;

package/dist/voxel/ray.js

@@ -0,0 +1,73 @@
+/** A hit record to fill. */
+export function createVoxelHit() {
+    return { x: 0, y: 0, z: 0, nx: 0, ny: 0, nz: 0, px: 0, py: 0, pz: 0, distance: 0 };
+}
+/**
+ * Walk the ray from (`ox`, `oy`, `oz`) along (`dx`, `dy`, `dz`) up to `maxDist` (in units of
+ * the direction's length) through `grid`, returning true and filling `out` at the first
+ * non-air cell. Cells outside the grid are air. A ray starting inside a block hits it at
+ * distance 0 with a zero normal.
+ */
+export function raycastVoxels(grid, ox, oy, oz, dx, dy, dz, maxDist, out) {
+    let x = Math.floor(ox);
+    let y = Math.floor(oy);
+    let z = Math.floor(oz);
+    const stepX = dx > 0 ? 1 : dx < 0 ? -1 : 0;
+    const stepY = dy > 0 ? 1 : dy < 0 ? -1 : 0;
+    const stepZ = dz > 0 ? 1 : dz < 0 ? -1 : 0;
+    const tDeltaX = stepX === 0 ? Infinity : Math.abs(1 / dx);
+    const tDeltaY = stepY === 0 ? Infinity : Math.abs(1 / dy);
+    const tDeltaZ = stepZ === 0 ? Infinity : Math.abs(1 / dz);
+    let tMaxX = stepX === 0 ? Infinity : (stepX > 0 ? x + 1 - ox : ox - x) * tDeltaX;
+    let tMaxY = stepY === 0 ? Infinity : (stepY > 0 ? y + 1 - oy : oy - y) * tDeltaY;
+    let tMaxZ = stepZ === 0 ? Infinity : (stepZ > 0 ? z + 1 - oz : oz - z) * tDeltaZ;
+    let nx = 0;
+    let ny = 0;
+    let nz = 0;
+    let t = 0;
+    // Every step crosses one cell boundary; the ray crosses at most one per axis per unit of
+    // travel along that axis, so `3 * maxDist + 3` steps cover the whole distance.
+    const steps = Math.ceil(3 * maxDist * Math.max(Math.abs(dx), Math.abs(dy), Math.abs(dz))) + 3;
+    for (let i = 0; i < steps; i++) {
+        if (grid.inBounds(x, y, z) && grid.data[grid.index(x, y, z)] !== 0) {
+            out.x = x;
+            out.y = y;
+            out.z = z;
+            out.nx = nx;
+            out.ny = ny;
+            out.nz = nz;
+            out.px = x + nx;
+            out.py = y + ny;
+            out.pz = z + nz;
+            out.distance = t;
+            return true;
+        }
+        if (tMaxX < tMaxY && tMaxX < tMaxZ) {
+            t = tMaxX;
+            x += stepX;
+            tMaxX += tDeltaX;
+            nx = -stepX;
+            ny = 0;
+            nz = 0;
+        }
+        else if (tMaxY < tMaxZ) {
+            t = tMaxY;
+            y += stepY;
+            tMaxY += tDeltaY;
+            nx = 0;
+            ny = -stepY;
+            nz = 0;
+        }
+        else {
+            t = tMaxZ;
+            z += stepZ;
+            tMaxZ += tDeltaZ;
+            nx = 0;
+            ny = 0;
+            nz = -stepZ;
+        }
+        if (t > maxDist)
+            return false;
+    }
+    return false;
+}

package/dist/voxel/wgsl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * WGSL helpers for a block material over the mesher's vertex convention. Prepend `VOXEL_WGSL`
+ * to the material's `wgsl` (after any `@group(1)` declarations it needs) and read:
+ *
+ * - `voxel_layer(in.color)`: the texture-array layer the mesher wrote to colour.a
+ *   (`u32(round(a))`, exact through interpolation because every vertex of a quad carries the
+ *   same layer);
+ * - `voxel_ao(in.color)`: the baked ambient occlusion in colour.r;
+ * - `voxel_uv_wrap(in.uv)`: the uv wrapped into 0..1 for a clamping sampler or an atlas;
+ *   the quad's uv spans whole block units, so `fract` tiles the face. Sample with
+ *   `textureSampleGrad(tex, s, voxel_uv_wrap(in.uv), layer, dpdx(in.uv), dpdy(in.uv))`: the
+ *   derivatives of the unwrapped uv keep the mip selection continuous across the wrap seam.
+ *   With the `'nearest-mip-repeat'` sampler kind the wrap is the sampler's and
+ *   `textureSample(tex, s, in.uv, layer)` is enough.
+ */
+export declare const VOXEL_WGSL = "\nfn voxel_layer(color: vec4f) -> u32 {\n  return u32(round(max(color.a, 0.0)));\n}\n\nfn voxel_ao(color: vec4f) -> f32 {\n  return color.r;\n}\n\nfn voxel_uv_wrap(uv: vec2f) -> vec2f {\n  return fract(uv);\n}\n";

package/dist/voxel/wgsl.js

@@ -0,0 +1,28 @@
+/**
+ * WGSL helpers for a block material over the mesher's vertex convention. Prepend `VOXEL_WGSL`
+ * to the material's `wgsl` (after any `@group(1)` declarations it needs) and read:
+ *
+ * - `voxel_layer(in.color)`: the texture-array layer the mesher wrote to colour.a
+ *   (`u32(round(a))`, exact through interpolation because every vertex of a quad carries the
+ *   same layer);
+ * - `voxel_ao(in.color)`: the baked ambient occlusion in colour.r;
+ * - `voxel_uv_wrap(in.uv)`: the uv wrapped into 0..1 for a clamping sampler or an atlas;
+ *   the quad's uv spans whole block units, so `fract` tiles the face. Sample with
+ *   `textureSampleGrad(tex, s, voxel_uv_wrap(in.uv), layer, dpdx(in.uv), dpdy(in.uv))`: the
+ *   derivatives of the unwrapped uv keep the mip selection continuous across the wrap seam.
+ *   With the `'nearest-mip-repeat'` sampler kind the wrap is the sampler's and
+ *   `textureSample(tex, s, in.uv, layer)` is enough.
+ */
+export const VOXEL_WGSL = /* wgsl */ `
+fn voxel_layer(color: vec4f) -> u32 {
+  return u32(round(max(color.a, 0.0)));
+}
+
+fn voxel_ao(color: vec4f) -> f32 {
+  return color.r;
+}
+
+fn voxel_uv_wrap(uv: vec2f) -> vec2f {
+  return fract(uv);
+}
+`;

package/dist/voxel/worker-client.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The mesher behind a promise: `createVoxelMesher(grid, { worker })` runs `meshChunk` in the
+ * Worker the game made from a three-line script calling `installVoxelMesherWorker`
+ * (`mesher-worker.ts`), or on the main thread when no Worker is given (the same code, the same
+ * reply shape, a microtask later). The Worker owns a copy of the grid: `createVoxelMesher`
+ * sends `grid.serialize()` once and mirrors every `set` the grid reports afterwards
+ * (`VoxelGrid.subscribe`), so the game edits the grid and nothing else.
+ *
+ * `remesh(chunk)` resolves with a `ChunkMesh`: one transferred `ArrayBuffer` in the
+ * `MeshReply` shape `Mesh.update` takes as it is (vertices from byte 0, uint32 indices after
+ * them). One request per chunk is in flight at a time; a repeat while one is in flight waits
+ * for the next run (coalesced: a burst of edits to one chunk meshes it twice at most).
+ */
+import type { MeshBounds, MeshReply } from '../render/mesh.js';
+import type { VoxelGrid } from './grid.js';
+import { type ChunkMeshOut, type MeshChunkOptions } from './mesher.js';
+/** A meshed chunk: `Mesh.update` takes it as a `MeshReply`. */
+export interface ChunkMesh extends MeshReply {
+    chunk: number;
+    buffer: ArrayBuffer;
+    vertexCount: number;
+    /** 6 per quad; 0 for an empty chunk (`buffer` is then empty). */
+    indexCount: number;
+    /** Byte offset of the uint32 indices in `buffer`. */
+    indexOffset: number;
+    /** Bounding sphere in chunk-local units (radius 0 when empty). */
+    bounds: MeshBounds;
+}
+/** Page → Worker. */
+export type VoxelMesherRequest = {
+    type: 'grid';
+    buffer: ArrayBuffer;
+} | {
+    type: 'set';
+    x: number;
+    y: number;
+    z: number;
+    block: number;
+} | {
+    type: 'mesh';
+    chunk: number;
+};
+/** Worker → page. */
+export type VoxelMesherReply = ChunkMesh & {
+    type: 'mesh';
+};
+/** The part of a `Worker` the client uses (a test passes a fake). */
+export interface VoxelWorkerLike {
+    postMessage(message: VoxelMesherRequest, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (e: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (e: {
+        data: unknown;
+    }) => void): void;
+}
+export interface VoxelMesherOptions extends MeshChunkOptions {
+    /** Mesh in this Worker (made from a script calling `installVoxelMesherWorker`). Default: in-thread. */
+    worker?: VoxelWorkerLike;
+}
+export interface VoxelMesher {
+    readonly grid: VoxelGrid;
+    /** True when a Worker does the meshing. */
+    readonly offThread: boolean;
+    /** Requests not yet resolved. */
+    readonly pending: number;
+    /** Mesh `chunk` (a chunk index) as the grid stands when the request runs. */
+    remesh(chunk: number): Promise<ChunkMesh>;
+    /** Resend the whole grid to the Worker (`fill` and `deserialize` do this on their own). */
+    sync(): void;
+    /** Stop mirroring the grid and listening to the Worker. The game terminates the Worker. */
+    dispose(): void;
+}
+/**
+ * Copy the mesher's output into one new `ArrayBuffer` (vertices, then uint32 indices) as a
+ * `ChunkMesh`, ready to transfer. An empty output gives an empty buffer.
+ */
+export declare function packChunkMesh(out: ChunkMeshOut, chunk: number): ChunkMesh;
+export declare function createVoxelMesher(grid: VoxelGrid, opts?: VoxelMesherOptions): VoxelMesher;

package/dist/voxel/worker-client.js

@@ -0,0 +1,122 @@
+import { createChunkMeshOut, meshChunk, VOXEL_VERTEX_FLOATS, } from './mesher.js';
+/**
+ * Copy the mesher's output into one new `ArrayBuffer` (vertices, then uint32 indices) as a
+ * `ChunkMesh`, ready to transfer. An empty output gives an empty buffer.
+ */
+export function packChunkMesh(out, chunk) {
+    const vertexBytes = out.vertexCount * VOXEL_VERTEX_FLOATS * 4;
+    const indexBytes = out.indexCount * 4;
+    const buffer = new ArrayBuffer(vertexBytes + indexBytes);
+    if (vertexBytes > 0) {
+        new Float32Array(buffer, 0, out.vertexCount * VOXEL_VERTEX_FLOATS).set(out.vertices.subarray(0, out.vertexCount * VOXEL_VERTEX_FLOATS));
+    }
+    if (indexBytes > 0) {
+        new Uint32Array(buffer, vertexBytes, out.indexCount).set(out.indices.subarray(0, out.indexCount));
+    }
+    const b = out.bounds;
+    return {
+        chunk,
+        buffer,
+        vertexCount: out.vertexCount,
+        indexCount: out.indexCount,
+        indexOffset: vertexBytes,
+        bounds: { center: [b.center[0], b.center[1], b.center[2]], radius: b.radius },
+    };
+}
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+const coordsOut = [0, 0, 0];
+export function createVoxelMesher(grid, opts = {}) {
+    const worker = opts.worker ?? null;
+    const inflight = new Map();
+    const queued = new Map();
+    let out = null;
+    let pendingCount = 0;
+    const send = (chunk, d) => {
+        inflight.set(chunk, d);
+        worker.postMessage({ type: 'mesh', chunk });
+    };
+    const onMessage = (e) => {
+        const reply = e.data;
+        if (!reply || reply.type !== 'mesh')
+            return;
+        const d = inflight.get(reply.chunk);
+        if (!d)
+            return;
+        inflight.delete(reply.chunk);
+        pendingCount--;
+        const next = queued.get(reply.chunk);
+        if (next) {
+            queued.delete(reply.chunk);
+            send(reply.chunk, next);
+        }
+        d.resolve(reply);
+    };
+    const unsubscribe = grid.subscribe({
+        set: (x, y, z, block) => worker?.postMessage({ type: 'set', x, y, z, block }),
+        reset: () => sync(),
+    });
+    function sync() {
+        if (!worker)
+            return;
+        const buffer = grid.serialize();
+        worker.postMessage({ type: 'grid', buffer }, [buffer]);
+    }
+    if (worker) {
+        worker.addEventListener('message', onMessage);
+        sync();
+    }
+    const remeshInThread = (chunk) => {
+        const d = deferred();
+        inflight.set(chunk, d);
+        pendingCount++;
+        queueMicrotask(() => {
+            inflight.delete(chunk);
+            pendingCount--;
+            out ??= createChunkMeshOut();
+            grid.chunkCoords(chunk, coordsOut);
+            meshChunk(grid, coordsOut[0], coordsOut[1], coordsOut[2], opts, out);
+            d.resolve(packChunkMesh(out, chunk));
+        });
+        return d.promise;
+    };
+    return {
+        grid,
+        offThread: worker !== null,
+        get pending() {
+            return pendingCount;
+        },
+        remesh(chunk) {
+            const current = inflight.get(chunk);
+            if (current) {
+                if (!worker)
+                    return current.promise;
+                let next = queued.get(chunk);
+                if (!next) {
+                    next = deferred();
+                    queued.set(chunk, next);
+                    pendingCount++;
+                }
+                return next.promise;
+            }
+            if (!worker)
+                return remeshInThread(chunk);
+            const d = deferred();
+            pendingCount++;
+            send(chunk, d);
+            return d.promise;
+        },
+        sync,
+        dispose() {
+            unsubscribe();
+            worker?.removeEventListener('message', onMessage);
+            inflight.clear();
+            queued.clear();
+        },
+    };
+}