@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/voxel/chunks.js

@@ -0,0 +1,149 @@
+import { VERTEX_LAYOUT_3D } from '../render/mesh.js';
+import { Transform } from '../render/transform.js';
+import { createVoxelMesher } from './worker-client.js';
+const defaultNow = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+const coords = [0, 0, 0];
+export function createVoxelChunks(renderer, grid, opts) {
+    const material = opts.material;
+    const slack = Math.max(1, opts.slack ?? 1.5);
+    const minQuads = Math.max(1, opts.minQuads ?? 64);
+    const ownMesher = !opts.mesher;
+    const mesher = opts.mesher ?? createVoxelMesher(grid, opts);
+    const now = opts.now ?? defaultNow;
+    const params = opts.params;
+    const count = grid.chunkCount;
+    const meshes = new Array(count).fill(null);
+    const transforms = new Array(count);
+    const ox = opts.origin?.[0] ?? 0;
+    const oy = opts.origin?.[1] ?? 0;
+    const oz = opts.origin?.[2] ?? 0;
+    /** World centre and radius of each chunk's last sphere. */
+    const centers = new Float32Array(count * 3);
+    const radii = new Float32Array(count);
+    const requestedAt = new Float64Array(count);
+    const finished = [];
+    const stats = {
+        drawn: 0,
+        culled: 0,
+        triangles: 0,
+        chunks: 0,
+        growths: 0,
+        pending: 0,
+        remeshes: 0,
+        remeshMs: 0,
+    };
+    let disposed = false;
+    for (let c = 0; c < count; c++) {
+        grid.chunkCoords(c, coords);
+        transforms[c] = new Transform({
+            x: ox + coords[0] * grid.chunk,
+            y: oy + coords[1] * grid.chunk,
+            z: oz + coords[2] * grid.chunk,
+        });
+    }
+    const apply = (reply) => {
+        const c = reply.chunk;
+        let mesh = meshes[c];
+        if (reply.indexCount === 0) {
+            if (mesh && mesh.indexCount > 0) {
+                mesh.update({ vertexCount: 0, indexCount: 0 });
+                stats.chunks--;
+            }
+            radii[c] = 0;
+            return;
+        }
+        if (!mesh) {
+            const quads = Math.max(minQuads, Math.ceil((reply.indexCount / 6) * slack));
+            mesh = renderer.createMesh({
+                label: `voxel-chunk-${c}`,
+                layout: VERTEX_LAYOUT_3D,
+                capacity: { vertices: quads * 4, indices: quads * 6 },
+                indexFormat: 'uint32',
+                autoBounds: false,
+                bounds: { center: [0, 0, 0], radius: Infinity },
+            });
+            meshes[c] = mesh;
+        }
+        const wasEmpty = mesh.indexCount === 0;
+        mesh.update(reply);
+        if (wasEmpty)
+            stats.chunks++;
+        const t = transforms[c].position;
+        const b = reply.bounds;
+        centers[c * 3] = t.x + b.center[0];
+        centers[c * 3 + 1] = t.y + b.center[1];
+        centers[c * 3 + 2] = t.z + b.center[2];
+        radii[c] = b.radius;
+    };
+    const onReply = (reply) => {
+        if (!disposed)
+            finished.push(reply);
+    };
+    return {
+        grid,
+        material,
+        mesher,
+        meshes,
+        transforms,
+        stats,
+        update() {
+            let applied = 0;
+            const clock = now();
+            while (finished.length > 0) {
+                const reply = finished.shift();
+                apply(reply);
+                applied++;
+                stats.pending--;
+                stats.remeshes++;
+                stats.remeshMs = clock - requestedAt[reply.chunk];
+            }
+            grid.forEachDirtyChunk((c) => {
+                requestedAt[c] = clock;
+                stats.pending++;
+                void mesher.remesh(c).then(onReply);
+            });
+            let growths = 0;
+            for (let c = 0; c < count; c++) {
+                const m = meshes[c];
+                if (m)
+                    growths += m.growths;
+            }
+            stats.growths = growths;
+            return applied;
+        },
+        draw(frame, camera) {
+            let drawn = 0;
+            let culled = 0;
+            let triangles = 0;
+            for (let c = 0; c < count; c++) {
+                const mesh = meshes[c];
+                if (!mesh || mesh.indexCount === 0)
+                    continue;
+                if (!camera.seesSphere(centers[c * 3], centers[c * 3 + 1], centers[c * 3 + 2], radii[c])) {
+                    culled++;
+                    continue;
+                }
+                if (params)
+                    frame.mesh(mesh, material, transforms[c], params);
+                else
+                    frame.mesh(mesh, material, transforms[c]);
+                drawn++;
+                triangles += mesh.indexCount / 3;
+            }
+            stats.drawn = drawn;
+            stats.culled = culled;
+            stats.triangles = triangles;
+            return stats;
+        },
+        dispose() {
+            disposed = true;
+            finished.length = 0;
+            for (let c = 0; c < count; c++) {
+                meshes[c]?.destroy();
+                meshes[c] = null;
+            }
+            if (ownMesher)
+                mesher.dispose();
+        },
+    };
+}

package/dist/voxel/grid.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The block grid: one `Uint8Array` of block ids (0 = air) over a box of `sizeX × sizeY × sizeZ`
+ * cells, cut into cubic chunks of `chunk` cells on a side. Cell (x, y, z) lives at
+ * `x + sizeX * (y + sizeY * z)`; chunk (cx, cy, cz) is `cx + chunksX * (cy + chunksY * cz)`.
+ * Every `set` bumps `version` and flags the chunk it touched, plus the chunks sharing that
+ * cell's faces, edges and corners when it lies on a border (a face there changes the
+ * neighbour's ambient occlusion). `serialize()` packs the grid into one `ArrayBuffer` a Worker
+ * can own (`deserializeVoxelGrid`), so the mesher runs off the thread on its own copy.
+ * Pure: no GPU, no DOM.
+ */
+export interface VoxelGridOptions {
+    sizeX: number;
+    sizeY: number;
+    sizeZ: number;
+    /** Cells on a chunk's side. Default 16. The sizes need not be multiples of it. */
+    chunk?: number;
+}
+/** What a grid reports to its subscribers (`VoxelGrid.subscribe`). */
+export interface VoxelGridListener {
+    /** One cell changed to `block`. */
+    set?(x: number, y: number, z: number, block: number): void;
+    /** Every cell may have changed (`fill`, `deserialize`): resync whole. */
+    reset?(): void;
+}
+export interface VoxelGrid {
+    readonly sizeX: number;
+    readonly sizeY: number;
+    readonly sizeZ: number;
+    /** Cells on a chunk's side. */
+    readonly chunk: number;
+    readonly chunksX: number;
+    readonly chunksY: number;
+    readonly chunksZ: number;
+    /** Chunks in the grid (`chunksX * chunksY * chunksZ`). */
+    readonly chunkCount: number;
+    /** The cells, `x + sizeX * (y + sizeY * z)`. Writing it directly bypasses the dirty flags. */
+    readonly data: Uint8Array;
+    /** Bumps on every change (`set`, `setMany`, `fill`, `deserialize`). */
+    readonly version: number;
+    /** Dirty flag per chunk (1 = needs a remesh). */
+    readonly dirty: Uint8Array;
+    inBounds(x: number, y: number, z: number): boolean;
+    /** The cell's index in `data`; no bounds check. */
+    index(x: number, y: number, z: number): number;
+    /** The block at (x, y, z); `outside` (default 0) when out of bounds. */
+    get(x: number, y: number, z: number, outside?: number): number;
+    /** Set one cell; out of bounds is ignored. Returns whether the cell changed. */
+    set(x: number, y: number, z: number, block: number): boolean;
+    /** Set cells from a flat `[x, y, z, block, ...]` list. Returns how many changed. */
+    setMany(cells: ArrayLike<number>): number;
+    /** Every cell from `fn`; flags every chunk dirty. */
+    fill(fn: (x: number, y: number, z: number) => number): void;
+    /** Index of the chunk holding cell (x, y, z), -1 out of bounds. */
+    chunkAt(x: number, y: number, z: number): number;
+    /** Chunk index from chunk coordinates; no bounds check. */
+    chunkIndex(cx: number, cy: number, cz: number): number;
+    /** Chunk coordinates of a chunk index, into `out` (`[cx, cy, cz]`). */
+    chunkCoords(chunk: number, out: number[] | Float32Array | Int32Array): void;
+    /** True when no cell of the chunk is a block. */
+    chunkEmpty(chunk: number): boolean;
+    isDirty(chunk: number): boolean;
+    markDirty(chunk: number): void;
+    /** Flag every chunk. */
+    markAllDirty(): void;
+    clearDirty(chunk: number): void;
+    /** Calls `fn` for each dirty chunk, clearing its flag first; returns how many. */
+    forEachDirtyChunk(fn: (chunk: number) => void): number;
+    /**
+     * One `ArrayBuffer`: a 16-byte header (sizeX, sizeY, sizeZ, chunk as uint32) then the
+     * cells. Transferable; `deserializeVoxelGrid` rebuilds the grid from it.
+     */
+    serialize(): ArrayBuffer;
+    /** Copy the cells of a serialized grid of the same sizes into this one; every chunk dirty. */
+    deserialize(buffer: ArrayBuffer): void;
+    /** Mirror changes elsewhere (a mesher Worker). Returns the unsubscriber. */
+    subscribe(listener: VoxelGridListener): () => void;
+}
+/** A grid of air. */
+export declare function createVoxelGrid(opts: VoxelGridOptions): VoxelGrid;
+/**
+ * A grid over the cells of a `serialize()` buffer: the grid reads and writes that buffer in
+ * place (no copy), so a Worker handed the transferred buffer owns the cells.
+ */
+export declare function deserializeVoxelGrid(buffer: ArrayBuffer): VoxelGrid;

package/dist/voxel/grid.js

@@ -0,0 +1,223 @@
+/**
+ * The block grid: one `Uint8Array` of block ids (0 = air) over a box of `sizeX × sizeY × sizeZ`
+ * cells, cut into cubic chunks of `chunk` cells on a side. Cell (x, y, z) lives at
+ * `x + sizeX * (y + sizeY * z)`; chunk (cx, cy, cz) is `cx + chunksX * (cy + chunksY * cz)`.
+ * Every `set` bumps `version` and flags the chunk it touched, plus the chunks sharing that
+ * cell's faces, edges and corners when it lies on a border (a face there changes the
+ * neighbour's ambient occlusion). `serialize()` packs the grid into one `ArrayBuffer` a Worker
+ * can own (`deserializeVoxelGrid`), so the mesher runs off the thread on its own copy.
+ * Pure: no GPU, no DOM.
+ */
+const HEADER_BYTES = 16;
+class Grid {
+    sizeX;
+    sizeY;
+    sizeZ;
+    chunk;
+    chunksX;
+    chunksY;
+    chunksZ;
+    chunkCount;
+    data;
+    dirty;
+    version = 0;
+    listeners = [];
+    constructor(opts, data) {
+        const chunk = opts.chunk ?? 16;
+        if (!(chunk >= 1) || !(opts.sizeX >= 1) || !(opts.sizeY >= 1) || !(opts.sizeZ >= 1)) {
+            throw new Error('createVoxelGrid: sizes and chunk must be at least 1');
+        }
+        this.sizeX = Math.floor(opts.sizeX);
+        this.sizeY = Math.floor(opts.sizeY);
+        this.sizeZ = Math.floor(opts.sizeZ);
+        this.chunk = Math.floor(chunk);
+        this.chunksX = Math.ceil(this.sizeX / this.chunk);
+        this.chunksY = Math.ceil(this.sizeY / this.chunk);
+        this.chunksZ = Math.ceil(this.sizeZ / this.chunk);
+        this.chunkCount = this.chunksX * this.chunksY * this.chunksZ;
+        this.data = data ?? new Uint8Array(this.sizeX * this.sizeY * this.sizeZ);
+        this.dirty = new Uint8Array(this.chunkCount).fill(1);
+    }
+    inBounds(x, y, z) {
+        return x >= 0 && y >= 0 && z >= 0 && x < this.sizeX && y < this.sizeY && z < this.sizeZ;
+    }
+    index(x, y, z) {
+        return x + this.sizeX * (y + this.sizeY * z);
+    }
+    get(x, y, z, outside = 0) {
+        if (!this.inBounds(x, y, z))
+            return outside;
+        return this.data[x + this.sizeX * (y + this.sizeY * z)];
+    }
+    set(x, y, z, block) {
+        if (!this.inBounds(x, y, z))
+            return false;
+        const i = this.index(x, y, z);
+        if (this.data[i] === block)
+            return false;
+        this.data[i] = block;
+        this.version++;
+        this.touch(x, y, z);
+        for (const l of this.listeners)
+            l.set?.(x, y, z, block);
+        return true;
+    }
+    setMany(cells) {
+        let changed = 0;
+        for (let i = 0; i + 3 < cells.length; i += 4) {
+            if (this.set(cells[i], cells[i + 1], cells[i + 2], cells[i + 3]))
+                changed++;
+        }
+        return changed;
+    }
+    fill(fn) {
+        const d = this.data;
+        let i = 0;
+        for (let z = 0; z < this.sizeZ; z++) {
+            for (let y = 0; y < this.sizeY; y++) {
+                for (let x = 0; x < this.sizeX; x++)
+                    d[i++] = fn(x, y, z);
+            }
+        }
+        this.version++;
+        this.markAllDirty();
+        for (const l of this.listeners)
+            l.reset?.();
+    }
+    chunkAt(x, y, z) {
+        if (!this.inBounds(x, y, z))
+            return -1;
+        const c = this.chunk;
+        return this.chunkIndex(Math.floor(x / c), Math.floor(y / c), Math.floor(z / c));
+    }
+    chunkIndex(cx, cy, cz) {
+        return cx + this.chunksX * (cy + this.chunksY * cz);
+    }
+    chunkCoords(chunk, out) {
+        const cx = chunk % this.chunksX;
+        const rest = (chunk - cx) / this.chunksX;
+        const cy = rest % this.chunksY;
+        out[0] = cx;
+        out[1] = cy;
+        out[2] = (rest - cy) / this.chunksY;
+    }
+    chunkEmpty(chunk) {
+        const c = this.chunk;
+        const cx = chunk % this.chunksX;
+        const rest = (chunk - cx) / this.chunksX;
+        const cy = rest % this.chunksY;
+        const cz = (rest - cy) / this.chunksY;
+        const x1 = Math.min(this.sizeX, (cx + 1) * c);
+        const y1 = Math.min(this.sizeY, (cy + 1) * c);
+        const z1 = Math.min(this.sizeZ, (cz + 1) * c);
+        const d = this.data;
+        for (let z = cz * c; z < z1; z++) {
+            for (let y = cy * c; y < y1; y++) {
+                const row = this.sizeX * (y + this.sizeY * z);
+                for (let x = cx * c; x < x1; x++)
+                    if (d[row + x] !== 0)
+                        return false;
+            }
+        }
+        return true;
+    }
+    isDirty(chunk) {
+        return this.dirty[chunk] === 1;
+    }
+    markDirty(chunk) {
+        if (chunk >= 0 && chunk < this.chunkCount)
+            this.dirty[chunk] = 1;
+    }
+    markAllDirty() {
+        this.dirty.fill(1);
+    }
+    clearDirty(chunk) {
+        if (chunk >= 0 && chunk < this.chunkCount)
+            this.dirty[chunk] = 0;
+    }
+    forEachDirtyChunk(fn) {
+        let n = 0;
+        const d = this.dirty;
+        for (let c = 0; c < d.length; c++) {
+            if (d[c] !== 1)
+                continue;
+            d[c] = 0;
+            n++;
+            fn(c);
+        }
+        return n;
+    }
+    serialize() {
+        const buffer = new ArrayBuffer(HEADER_BYTES + this.data.length);
+        const header = new Uint32Array(buffer, 0, 4);
+        header[0] = this.sizeX;
+        header[1] = this.sizeY;
+        header[2] = this.sizeZ;
+        header[3] = this.chunk;
+        new Uint8Array(buffer, HEADER_BYTES).set(this.data);
+        return buffer;
+    }
+    deserialize(buffer) {
+        const header = readHeader(buffer);
+        if (header.sizeX !== this.sizeX ||
+            header.sizeY !== this.sizeY ||
+            header.sizeZ !== this.sizeZ ||
+            header.chunk !== this.chunk) {
+            throw new Error('VoxelGrid.deserialize: the buffer holds a grid of other sizes');
+        }
+        this.data.set(new Uint8Array(buffer, HEADER_BYTES, this.data.length));
+        this.version++;
+        this.markAllDirty();
+        for (const l of this.listeners)
+            l.reset?.();
+    }
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const i = this.listeners.indexOf(listener);
+            if (i >= 0)
+                this.listeners.splice(i, 1);
+        };
+    }
+    /** Flag the chunk of (x, y, z) and every chunk within one cell of it. */
+    touch(x, y, z) {
+        const c = this.chunk;
+        const cx = Math.floor(x / c);
+        const cy = Math.floor(y / c);
+        const cz = Math.floor(z / c);
+        const x0 = x % c === 0 && cx > 0 ? cx - 1 : cx;
+        const x1 = x % c === c - 1 && cx + 1 < this.chunksX ? cx + 1 : cx;
+        const y0 = y % c === 0 && cy > 0 ? cy - 1 : cy;
+        const y1 = y % c === c - 1 && cy + 1 < this.chunksY ? cy + 1 : cy;
+        const z0 = z % c === 0 && cz > 0 ? cz - 1 : cz;
+        const z1 = z % c === c - 1 && cz + 1 < this.chunksZ ? cz + 1 : cz;
+        for (let k = z0; k <= z1; k++) {
+            for (let j = y0; j <= y1; j++) {
+                for (let i = x0; i <= x1; i++)
+                    this.dirty[this.chunkIndex(i, j, k)] = 1;
+            }
+        }
+    }
+}
+function readHeader(buffer) {
+    if (buffer.byteLength < HEADER_BYTES)
+        throw new Error('voxel grid buffer: too short');
+    const h = new Uint32Array(buffer, 0, 4);
+    const opts = { sizeX: h[0], sizeY: h[1], sizeZ: h[2], chunk: h[3] };
+    if (buffer.byteLength !== HEADER_BYTES + opts.sizeX * opts.sizeY * opts.sizeZ) {
+        throw new Error('voxel grid buffer: length does not match its header');
+    }
+    return opts;
+}
+/** A grid of air. */
+export function createVoxelGrid(opts) {
+    return new Grid(opts);
+}
+/**
+ * A grid over the cells of a `serialize()` buffer: the grid reads and writes that buffer in
+ * place (no copy), so a Worker handed the transferred buffer owns the cells.
+ */
+export function deserializeVoxelGrid(buffer) {
+    const opts = readHeader(buffer);
+    return new Grid(opts, new Uint8Array(buffer, HEADER_BYTES));
+}

package/dist/voxel/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@thunderclap-engine/engine/voxel`: block grids into chunk meshes and onto the screen. A
+ * `VoxelGrid` of block ids with per-chunk dirty flags, a greedy mesher with baked ambient
+ * occlusion (`meshChunk`, pure, Worker-ready) and its Worker bridge (`createVoxelMesher`,
+ * `installVoxelMesherWorker`), a chunk renderer that owns one mesh per non-empty chunk and
+ * frustum-culls them (`createVoxelChunks`), a block-picking ray (`raycastVoxels`) and the WGSL
+ * prelude a block material reads the vertex convention with (`VOXEL_WGSL`). The game ships the
+ * blocks: what each id is, which texture layer each face shows, what a click does.
+ */
+export type { VoxelChunks, VoxelChunksOptions, VoxelChunksStats, VoxelDrawStats, } from './chunks.js';
+export { createVoxelChunks } from './chunks.js';
+export type { VoxelGrid, VoxelGridListener, VoxelGridOptions } from './grid.js';
+export { createVoxelGrid, deserializeVoxelGrid } from './grid.js';
+export type { ChunkMeshOut, MeshChunkOptions, VoxelFace } from './mesher.js';
+export { countExposedFaces, createChunkMeshOut, meshChunk, VOXEL_AO_CURVE, VOXEL_FACE_NORMALS, VOXEL_VERTEX_FLOATS, } from './mesher.js';
+export type { VoxelWorkerScopeLike } from './mesher-worker.js';
+export { installVoxelMesherWorker } from './mesher-worker.js';
+export type { VoxelHit } from './ray.js';
+export { createVoxelHit, raycastVoxels } from './ray.js';
+export { VOXEL_WGSL } from './wgsl.js';
+export type { ChunkMesh, VoxelMesher, VoxelMesherOptions, VoxelMesherReply, VoxelMesherRequest, VoxelWorkerLike, } from './worker-client.js';
+export { createVoxelMesher, packChunkMesh } from './worker-client.js';

package/dist/voxel/index.js

@@ -0,0 +1,7 @@
+export { createVoxelChunks } from './chunks.js';
+export { createVoxelGrid, deserializeVoxelGrid } from './grid.js';
+export { countExposedFaces, createChunkMeshOut, meshChunk, VOXEL_AO_CURVE, VOXEL_FACE_NORMALS, VOXEL_VERTEX_FLOATS, } from './mesher.js';
+export { installVoxelMesherWorker } from './mesher-worker.js';
+export { createVoxelHit, raycastVoxels } from './ray.js';
+export { VOXEL_WGSL } from './wgsl.js';
+export { createVoxelMesher, packChunkMesh } from './worker-client.js';

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

@@ -0,0 +1,14 @@
+import { type MeshChunkOptions } from './mesher.js';
+import { type VoxelMesherReply, type VoxelMesherRequest } from './worker-client.js';
+/** The part of a Worker's global scope the install uses (a test passes a fake). */
+export interface VoxelWorkerScopeLike {
+    postMessage(message: VoxelMesherReply, transfer?: Transferable[]): void;
+    addEventListener(type: 'message', listener: (e: {
+        data: unknown;
+    }) => void): void;
+}
+/**
+ * Listen for `VoxelMesherRequest`s on `scope` (default the Worker's `self`) and answer `mesh`
+ * requests. Returns the handler, so a test can call it directly.
+ */
+export declare function installVoxelMesherWorker(opts?: MeshChunkOptions, scope?: VoxelWorkerScopeLike): (req: VoxelMesherRequest) => void;

package/dist/voxel/mesher-worker.js

@@ -0,0 +1,47 @@
+/**
+ * The Worker side of `createVoxelMesher`. A game's worker script is two lines: import
+ * `installVoxelMesherWorker` from the voxel subpath and call it with the mesher options
+ * (`installVoxelMesherWorker({ layerOf })`); the page makes `new Worker(new URL('./mesher.worker.ts', import.meta.url), { type: 'module' })`
+ * and hands it to `createVoxelMesher(grid, { worker })`. The Worker keeps its own `VoxelGrid`
+ * over the buffer the client transfers, applies the edits the client mirrors and answers each
+ * `mesh` request with one transferred `ChunkMesh` buffer. `opts` are the mesher's
+ * (`layerOf`, `ao`, `outside`...): functions cannot cross the thread boundary, so the game
+ * names them here and again on the client for its in-thread fallback.
+ */
+import { deserializeVoxelGrid } from './grid.js';
+import { createChunkMeshOut, meshChunk } from './mesher.js';
+import { packChunkMesh } from './worker-client.js';
+const coords = [0, 0, 0];
+/**
+ * Listen for `VoxelMesherRequest`s on `scope` (default the Worker's `self`) and answer `mesh`
+ * requests. Returns the handler, so a test can call it directly.
+ */
+export function installVoxelMesherWorker(opts = {}, scope = self) {
+    let grid = null;
+    let out = null;
+    const handle = (req) => {
+        if (req.type === 'grid') {
+            grid = deserializeVoxelGrid(req.buffer);
+            return;
+        }
+        if (!grid)
+            return;
+        if (req.type === 'set') {
+            grid.set(req.x, req.y, req.z, req.block);
+            return;
+        }
+        if (req.type === 'mesh') {
+            out ??= createChunkMeshOut();
+            grid.chunkCoords(req.chunk, coords);
+            meshChunk(grid, coords[0], coords[1], coords[2], opts, out);
+            const reply = { type: 'mesh', ...packChunkMesh(out, req.chunk) };
+            scope.postMessage(reply, [reply.buffer]);
+        }
+    };
+    scope.addEventListener('message', (e) => {
+        const req = e.data;
+        if (req && typeof req === 'object' && 'type' in req)
+            handle(req);
+    });
+    return handle;
+}

package/dist/voxel/mesher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The chunk mesher: a block grid in, greedy-merged quads out, in `VERTEX_LAYOUT_3D` (12 floats:
+ * position, normal, uv, rgba) with uint32 indices. Pure arithmetic over a `VoxelGrid`, so it
+ * runs the same on the main thread or in a Worker (`mesher-worker.ts`).
+ *
+ * Convention (the block material's contract, see README):
+ * - positions are chunk-local block units (0..chunk on each axis); the renderer places each
+ *   chunk by a transform at its origin;
+ * - the normal is the face's axis;
+ * - uv is in block units across the quad, u along the face's right, v downward from the top
+ *   of the quad (a texture's row 0 is its top), so a merged 3×2 quad spans uv 0..3 × 0..2 and
+ *   the material wraps it (`voxel_uv_wrap` or a `repeat` sampler);
+ * - colour rgb is the baked ambient occlusion (`aoCurve` of the corner's level, 1 = open) and
+ *   colour a is the texture-array layer from `layerOf(block, face)`.
+ *
+ * Greedy meshing: for each of the six face directions and each slice of the chunk along that
+ * axis, a `chunk × chunk` mask holds a key per exposed face (the layer and the four corner AO
+ * levels); runs of equal keys merge into one quad, first along the row, then down the rows.
+ * AO is the four-neighbour rule: each quad corner looks at the two side cells and the diagonal
+ * cell touching it on the face's outer side; both sides solid is the darkest level (0), else
+ * `3 - solid count`. A quad whose opposite corners differ in AO is split along the diagonal
+ * with the lower sum, so the dark pair shares an edge and the interpolation has no crease
+ * (the "riser triangle" a fixed diagonal shows on a one-block step).
+ */
+import type { MeshBounds } from '../render/mesh.js';
+import type { VoxelGrid } from './grid.js';
+/** A block face: 0 +x, 1 -x, 2 +y, 3 -y, 4 +z, 5 -z. */
+export type VoxelFace = 0 | 1 | 2 | 3 | 4 | 5;
+/** Outward normal of each `VoxelFace`. */
+export declare const VOXEL_FACE_NORMALS: readonly (readonly [number, number, number])[];
+/** Default AO curve: corner level (0 darkest .. 3 open) → vertex brightness. */
+export declare const VOXEL_AO_CURVE: readonly number[];
+/** Floats per vertex of the mesher's output (`VERTEX_LAYOUT_3D`). */
+export declare const VOXEL_VERTEX_FLOATS = 12;
+export interface MeshChunkOptions {
+    /** Bake ambient occlusion into colour.rgb. Default true (off: rgb = 1, more merging). */
+    ao?: boolean;
+    /** Brightness per AO level, 4 entries. Default `VOXEL_AO_CURVE`. */
+    aoCurve?: ArrayLike<number>;
+    /** Texture-array layer of a block's face, written to colour.a. Default `block - 1`. */
+    layerOf?: (block: number, face: VoxelFace) => number;
+    /**
+     * What lies beyond the grid: a block id for every outside cell (0 = air, so the grid's
+     * boundary faces show), or a function of the cell (solid below y 0 and air elsewhere hides
+     * a world's underside). Default 0.
+     */
+    outside?: number | ((x: number, y: number, z: number) => number);
+}
+/** The mesher's output buffers, reused across calls and grown with slack when a chunk needs more. */
+export interface ChunkMeshOut {
+    vertices: Float32Array;
+    indices: Uint32Array;
+    /** Vertices written by the last `meshChunk` (`vertexCount * VOXEL_VERTEX_FLOATS` floats). */
+    vertexCount: number;
+    /** Indices written by the last `meshChunk` (6 per quad). */
+    indexCount: number;
+    /** Bounding sphere of the last output in chunk-local units; radius 0 when empty. */
+    bounds: MeshBounds;
+}
+/** Output buffers with room for `quads` quads before the first growth. */
+export declare function createChunkMeshOut(quads?: number): ChunkMeshOut;
+/**
+ * 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 declare function meshChunk(grid: VoxelGrid, cx: number, cy: number, cz: number, opts: MeshChunkOptions, out: ChunkMeshOut): ChunkMeshOut;
+/**
+ * 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 declare function countExposedFaces(grid: VoxelGrid, cx: number, cy: number, cz: number, outside?: MeshChunkOptions['outside']): number;