@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/math/mat4.js

@@ -0,0 +1,198 @@
+// ============================================================================
+// mat4 — column-major 4×4 matrix utilities (WebGPU convention)
+// ============================================================================
+//
+// Shared implementation used by the engine's skeleton/animation system and
+// by games that need matrix math (e.g. model-viewer's animation helper).
+// All matrices are Float32Array(16) in column-major layout: m[col*4 + row].
+/** Compute A * B in column-major layout, writing into `out` (no allocation). */
+export function multiplyMat4Into(a, b, out) {
+    for (let i = 0; i < 4; i++) {
+        const bi0 = b[i * 4 + 0], bi1 = b[i * 4 + 1], bi2 = b[i * 4 + 2], bi3 = b[i * 4 + 3];
+        out[i * 4 + 0] = a[0] * bi0 + a[4] * bi1 + a[8] * bi2 + a[12] * bi3;
+        out[i * 4 + 1] = a[1] * bi0 + a[5] * bi1 + a[9] * bi2 + a[13] * bi3;
+        out[i * 4 + 2] = a[2] * bi0 + a[6] * bi1 + a[10] * bi2 + a[14] * bi3;
+        out[i * 4 + 3] = a[3] * bi0 + a[7] * bi1 + a[11] * bi2 + a[15] * bi3;
+    }
+}
+/** Invert a 4×4 column-major matrix via adjugate / determinant. Returns zeros if singular. */
+export function invertMat4(m) {
+    const a00 = m[0], a01 = m[4], a02 = m[8], a03 = m[12];
+    const a10 = m[1], a11 = m[5], a12 = m[9], a13 = m[13];
+    const a20 = m[2], a21 = m[6], a22 = m[10], a23 = m[14];
+    const a30 = m[3], a31 = m[7], a32 = m[11], a33 = m[15];
+    const b00 = a11 * a22 * a33 - a11 * a23 * a32 - a21 * a12 * a33 + a21 * a13 * a32 + a31 * a12 * a23 - a31 * a13 * a22;
+    const b01 = -a10 * a22 * a33 + a10 * a23 * a32 + a20 * a12 * a33 - a20 * a13 * a32 - a30 * a12 * a23 + a30 * a13 * a22;
+    const b02 = a10 * a21 * a33 - a10 * a23 * a31 - a20 * a11 * a33 + a20 * a13 * a31 + a30 * a11 * a23 - a30 * a13 * a21;
+    const b03 = -a10 * a21 * a32 + a10 * a22 * a31 + a20 * a11 * a32 - a20 * a12 * a31 - a30 * a11 * a22 + a30 * a12 * a21;
+    const b10 = -a01 * a22 * a33 + a01 * a23 * a32 + a21 * a02 * a33 - a21 * a03 * a32 - a31 * a02 * a23 + a31 * a03 * a22;
+    const b11 = a00 * a22 * a33 - a00 * a23 * a32 - a20 * a02 * a33 + a20 * a03 * a32 + a30 * a02 * a23 - a30 * a03 * a22;
+    const b12 = -a00 * a21 * a33 + a00 * a23 * a31 + a20 * a01 * a33 - a20 * a03 * a31 - a30 * a01 * a23 + a30 * a03 * a21;
+    const b13 = a00 * a21 * a32 - a00 * a22 * a31 - a20 * a01 * a32 + a20 * a02 * a31 + a30 * a01 * a22 - a30 * a02 * a21;
+    const b20 = a01 * a12 * a33 - a01 * a13 * a32 - a11 * a02 * a33 + a11 * a03 * a32 + a31 * a02 * a13 - a31 * a03 * a12;
+    const b21 = -a00 * a12 * a33 + a00 * a13 * a32 + a10 * a02 * a33 - a10 * a03 * a32 - a30 * a02 * a13 + a30 * a03 * a12;
+    const b22 = a00 * a11 * a33 - a00 * a13 * a31 - a10 * a01 * a33 + a10 * a03 * a31 + a30 * a01 * a13 - a30 * a03 * a11;
+    const b23 = -a00 * a11 * a32 + a00 * a12 * a31 + a10 * a01 * a32 - a10 * a02 * a31 - a30 * a01 * a12 + a30 * a02 * a11;
+    const b30 = -a01 * a12 * a23 + a01 * a13 * a22 + a11 * a02 * a23 - a11 * a03 * a22 - a21 * a02 * a13 + a21 * a03 * a12;
+    const b31 = a00 * a12 * a23 - a00 * a13 * a22 - a10 * a02 * a23 + a10 * a03 * a22 + a20 * a02 * a13 - a20 * a03 * a12;
+    const b32 = -a00 * a11 * a23 + a00 * a13 * a21 + a10 * a01 * a23 - a10 * a03 * a21 - a20 * a01 * a13 + a20 * a03 * a11;
+    const b33 = a00 * a11 * a22 - a00 * a12 * a21 - a10 * a01 * a22 + a10 * a02 * a21 + a20 * a01 * a12 - a20 * a02 * a11;
+    let det = a00 * b00 + a01 * b01 + a02 * b02 + a03 * b03;
+    if (Math.abs(det) < 1e-9)
+        return new Float32Array(16);
+    det = 1 / det;
+    const out = new Float32Array(16);
+    out[0] = b00 * det;
+    out[1] = b01 * det;
+    out[2] = b02 * det;
+    out[3] = b03 * det;
+    out[4] = b10 * det;
+    out[5] = b11 * det;
+    out[6] = b12 * det;
+    out[7] = b13 * det;
+    out[8] = b20 * det;
+    out[9] = b21 * det;
+    out[10] = b22 * det;
+    out[11] = b23 * det;
+    out[12] = b30 * det;
+    out[13] = b31 * det;
+    out[14] = b32 * det;
+    out[15] = b33 * det;
+    return out;
+}
+/**
+ * Write a WebGPU perspective projection matrix (clip Z ∈ [0, 1]) into `out`.
+ * No Y flip — the view matrix handles the world convention.
+ */
+export function perspectiveMat4Into(out, fovY, aspect, near, far) {
+    const f = 1.0 / Math.tan(fovY / 2);
+    const range = far - near;
+    out[0] = f / aspect;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    out[4] = 0;
+    out[5] = f;
+    out[6] = 0;
+    out[7] = 0;
+    out[8] = 0;
+    out[9] = 0;
+    out[10] = far / range;
+    out[11] = 1;
+    out[12] = 0;
+    out[13] = 0;
+    out[14] = -(far * near) / range;
+    out[15] = 0;
+}
+/**
+ * Write a look-at view matrix into `out`. Uses left-handed cross products
+ * (matches WebGPU's Z ∈ [0,1] clip space); `up` is the world-space up vector
+ * for the game's convention (e.g. [0,-1,0] for Y-down worlds).
+ */
+export function lookAtMat4Into(out, eye, target, up) {
+    const fx = target[0] - eye[0];
+    const fy = target[1] - eye[1];
+    const fz = target[2] - eye[2];
+    const fl = Math.hypot(fx, fy, fz) || 1;
+    const f0 = fx / fl, f1 = fy / fl, f2 = fz / fl;
+    const rx = up[1] * f2 - up[2] * f1;
+    const ry = up[2] * f0 - up[0] * f2;
+    const rz = up[0] * f1 - up[1] * f0;
+    const rl = Math.hypot(rx, ry, rz) || 1;
+    const r0 = rx / rl, r1 = ry / rl, r2 = rz / rl;
+    const u0 = f1 * r2 - f2 * r1;
+    const u1 = f2 * r0 - f0 * r2;
+    const u2 = f0 * r1 - f1 * r0;
+    out[0] = r0;
+    out[1] = u0;
+    out[2] = f0;
+    out[3] = 0;
+    out[4] = r1;
+    out[5] = u1;
+    out[6] = f1;
+    out[7] = 0;
+    out[8] = r2;
+    out[9] = u2;
+    out[10] = f2;
+    out[11] = 0;
+    out[12] = -(r0 * eye[0] + r1 * eye[1] + r2 * eye[2]);
+    out[13] = -(u0 * eye[0] + u1 * eye[1] + u2 * eye[2]);
+    out[14] = -(f0 * eye[0] + f1 * eye[1] + f2 * eye[2]);
+    out[15] = 1;
+}
+/**
+ * Invert a 4×4 column-major matrix into `out` via adjugate / determinant.
+ * Returns false (leaving `out` undefined) when the matrix is singular.
+ */
+export function invertMat4Into(m, out) {
+    const a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3];
+    const a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7];
+    const a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11];
+    const a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15];
+    const b00 = a00 * a11 - a01 * a10;
+    const b01 = a00 * a12 - a02 * a10;
+    const b02 = a00 * a13 - a03 * a10;
+    const b03 = a01 * a12 - a02 * a11;
+    const b04 = a01 * a13 - a03 * a11;
+    const b05 = a02 * a13 - a03 * a12;
+    const b06 = a20 * a31 - a21 * a30;
+    const b07 = a20 * a32 - a22 * a30;
+    const b08 = a20 * a33 - a23 * a30;
+    const b09 = a21 * a32 - a22 * a31;
+    const b10 = a21 * a33 - a23 * a31;
+    const b11 = a22 * a33 - a23 * a32;
+    let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+    if (det === 0)
+        return false;
+    det = 1.0 / det;
+    out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det;
+    out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det;
+    out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det;
+    out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det;
+    out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det;
+    out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det;
+    out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det;
+    out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det;
+    out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det;
+    out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det;
+    out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det;
+    out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det;
+    out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det;
+    out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det;
+    out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det;
+    out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det;
+    return true;
+}
+/** Transform a vec4 by a column-major mat4. Returns [x, y, z, w]. */
+export function transformMat4Vec4(m, v) {
+    return [
+        m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12] * v[3],
+        m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13] * v[3],
+        m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14] * v[3],
+        m[3] * v[0] + m[7] * v[1] + m[11] * v[2] + m[15] * v[3],
+    ];
+}
+/** Compose a TRS (translation, rotation, scale) into a column-major 4×4 matrix. */
+export function composeMat4Into(pos, rot, scale, m) {
+    const x = rot[0], y = rot[1], z = rot[2], w = rot[3];
+    const x2 = x + x, y2 = y + y, z2 = z + z;
+    const xx = x * x2, xy = x * y2, xz = x * z2;
+    const yy = y * y2, yz = y * z2, zz = z * z2;
+    const wx = w * x2, wy = w * y2, wz = w * z2;
+    m[0] = (1 - (yy + zz)) * scale[0];
+    m[1] = (xy + wz) * scale[0];
+    m[2] = (xz - wy) * scale[0];
+    m[3] = 0;
+    m[4] = (xy - wz) * scale[1];
+    m[5] = (1 - (xx + zz)) * scale[1];
+    m[6] = (yz + wx) * scale[1];
+    m[7] = 0;
+    m[8] = (xz + wy) * scale[2];
+    m[9] = (yz - wx) * scale[2];
+    m[10] = (1 - (xx + yy)) * scale[2];
+    m[11] = 0;
+    m[12] = pos[0];
+    m[13] = pos[1];
+    m[14] = pos[2];
+    m[15] = 1;
+}

package/dist/core/src/math/perlin-noise-2d.js

@@ -0,0 +1,66 @@
+// ============================================================================
+// PerlinNoise2D — seeded 2D Perlin gradient noise with fBm
+// ============================================================================
+//
+// Standard 2D Perlin noise implementation using a 512-byte permutation table
+// (Fisher-Yates shuffled with mulberry32). Returns values in [-1, 1] for
+// noise2D and [0, 1] for fbm. Used by procedural terrain generation.
+import { mulberry32 } from "./rng.js";
+function fade(t) {
+    return t * t * t * (t * (t * 6 - 15) + 10);
+}
+function lerp(a, b, t) {
+    return a + t * (b - a);
+}
+function grad(hash, x, y) {
+    const h = hash & 7;
+    const u = h < 4 ? x : y;
+    const v = h < 4 ? y : x;
+    return ((h & 1) ? -u : u) + ((h & 2) ? -2 * v : 2 * v);
+}
+export class PerlinNoise2D {
+    perm;
+    constructor(seed) {
+        this.perm = new Uint8Array(512);
+        const p = new Uint8Array(256);
+        for (let i = 0; i < 256; i++)
+            p[i] = i;
+        const rng = mulberry32(seed);
+        for (let i = 255; i > 0; i--) {
+            const j = Math.floor(rng() * (i + 1));
+            const tmp = p[i];
+            p[i] = p[j];
+            p[j] = tmp;
+        }
+        for (let i = 0; i < 512; i++)
+            this.perm[i] = p[i & 255];
+    }
+    noise2D(x, y) {
+        const X = Math.floor(x) & 255;
+        const Y = Math.floor(y) & 255;
+        const xf = x - Math.floor(x);
+        const yf = y - Math.floor(y);
+        const u = fade(xf);
+        const v = fade(yf);
+        const aa = this.perm[this.perm[X] + Y];
+        const ab = this.perm[this.perm[X] + Y + 1];
+        const ba = this.perm[this.perm[X + 1] + Y];
+        const bb = this.perm[this.perm[X + 1] + Y + 1];
+        const x1 = lerp(grad(aa, xf, yf), grad(ba, xf - 1, yf), u);
+        const x2 = lerp(grad(ab, xf, yf - 1), grad(bb, xf - 1, yf - 1), u);
+        return lerp(x1, x2, v);
+    }
+    fbm(x, y, octaves, persistence, lacunarity) {
+        let total = 0;
+        let frequency = 1;
+        let amplitude = 1;
+        let maxValue = 0;
+        for (let i = 0; i < octaves; i++) {
+            total += this.noise2D(x * frequency, y * frequency) * amplitude;
+            maxValue += amplitude;
+            amplitude *= persistence;
+            frequency *= lacunarity;
+        }
+        return total / maxValue;
+    }
+}

package/dist/core/src/math/perlin-noise-3d.js

@@ -0,0 +1,76 @@
+// ============================================================================
+// PerlinNoise3D — seeded 3D Perlin noise with fBm for cave/terrain generation
+// ============================================================================
+import { mulberry32 } from "./rng.js";
+function fade(t) {
+    return t * t * t * (t * (t * 6 - 15) + 10);
+}
+function lerp(a, b, t) {
+    return a + t * (b - a);
+}
+// 3D gradient function — 12 gradient directions (corners of a cube's edges)
+const GRAD3 = [
+    [1, 1, 0], [-1, 1, 0], [1, -1, 0], [-1, -1, 0],
+    [1, 0, 1], [-1, 0, 1], [1, 0, -1], [-1, 0, -1],
+    [0, 1, 1], [0, -1, 1], [0, 1, -1], [0, -1, -1],
+];
+function grad3(hash, x, y, z) {
+    const h = hash & 11;
+    const g = GRAD3[h];
+    return g[0] * x + g[1] * y + g[2] * z;
+}
+export class PerlinNoise3D {
+    perm;
+    constructor(seed) {
+        this.perm = new Uint8Array(512);
+        const p = new Uint8Array(256);
+        for (let i = 0; i < 256; i++)
+            p[i] = i;
+        const rng = mulberry32(seed);
+        for (let i = 255; i > 0; i--) {
+            const j = Math.floor(rng() * (i + 1));
+            const tmp = p[i];
+            p[i] = p[j];
+            p[j] = tmp;
+        }
+        for (let i = 0; i < 512; i++)
+            this.perm[i] = p[i & 255];
+    }
+    noise3D(x, y, z) {
+        const X = Math.floor(x) & 255;
+        const Y = Math.floor(y) & 255;
+        const Z = Math.floor(z) & 255;
+        const xf = x - Math.floor(x);
+        const yf = y - Math.floor(y);
+        const zf = z - Math.floor(z);
+        const u = fade(xf);
+        const v = fade(yf);
+        const w = fade(zf);
+        const A = this.perm[X] + Y;
+        const AA = this.perm[A] + Z;
+        const AB = this.perm[A + 1] + Z;
+        const B = this.perm[X + 1] + Y;
+        const BA = this.perm[B] + Z;
+        const BB = this.perm[B + 1] + Z;
+        const x1 = lerp(grad3(this.perm[AA], xf, yf, zf), grad3(this.perm[BA], xf - 1, yf, zf), u);
+        const x2 = lerp(grad3(this.perm[AB], xf, yf - 1, zf), grad3(this.perm[BB], xf - 1, yf - 1, zf), u);
+        const y1 = lerp(x1, x2, v);
+        const x3 = lerp(grad3(this.perm[AA + 1], xf, yf, zf - 1), grad3(this.perm[BA + 1], xf - 1, yf, zf - 1), u);
+        const x4 = lerp(grad3(this.perm[AB + 1], xf, yf - 1, zf - 1), grad3(this.perm[BB + 1], xf - 1, yf - 1, zf - 1), u);
+        const y2 = lerp(x3, x4, v);
+        return lerp(y1, y2, w);
+    }
+    fbm3D(x, y, z, octaves, persistence, lacunarity) {
+        let total = 0;
+        let frequency = 1;
+        let amplitude = 1;
+        let maxValue = 0;
+        for (let i = 0; i < octaves; i++) {
+            total += this.noise3D(x * frequency, y * frequency, z * frequency) * amplitude;
+            maxValue += amplitude;
+            amplitude *= persistence;
+            frequency *= lacunarity;
+        }
+        return total / maxValue;
+    }
+}

package/dist/core/src/math/quat.js

@@ -0,0 +1,29 @@
+// ============================================================================
+// quat — quaternion utilities for 3D rotation
+// ============================================================================
+//
+// Quaternions use the engine's `Quat` type ({x, y, z, w}). Used by
+// animation/skeleton systems and games that compose rotations.
+/** Quaternion multiplication: a * b (Hamilton product). */
+export function quatMul(a, b) {
+    const ax = a.x, ay = a.y, az = a.z, aw = a.w;
+    const bx = b.x, by = b.y, bz = b.z, bw = b.w;
+    return {
+        x: aw * bx + ax * bw + ay * bz - az * by,
+        y: aw * by - ax * bz + ay * bw + az * bx,
+        z: aw * bz + ax * by - ay * bx + az * bw,
+        w: aw * bw - ax * bx - ay * by - az * bz,
+    };
+}
+/** Euler XYZ (radians) → quaternion (ZYX intrinsic: q = qz*qy*qx). */
+export function eulerXYZToQuat(ex, ey, ez) {
+    const cx = Math.cos(ex / 2), sx = Math.sin(ex / 2);
+    const cy = Math.cos(ey / 2), sy = Math.sin(ey / 2);
+    const cz = Math.cos(ez / 2), sz = Math.sin(ez / 2);
+    return {
+        x: sx * cy * cz - cx * sy * sz,
+        y: cx * sy * cz + sx * cy * sz,
+        z: cx * cy * sz - sx * sy * cz,
+        w: cx * cy * cz + sx * sy * sz,
+    };
+}

package/dist/core/src/math/rng.js

@@ -0,0 +1,25 @@
+// ============================================================================
+// Seeded PRNG — mulberry32, a fast 32-bit seeded pseudo-random generator.
+// ============================================================================
+//
+// Used by procedural generation (Perlin noise, terrain, ore veins) and any
+// system that needs deterministic randomness from a seed. Games should import
+// from here instead of redefining mulberry32 locally.
+/**
+ * Create a seeded PRNG function (mulberry32 algorithm).
+ * Returns a function that produces floats in [0, 1) from a 32-bit state.
+ */
+export function mulberry32(seed) {
+    let a = seed;
+    return () => {
+        a |= 0;
+        a = (a + 0x6D2B79F5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Alias for mulberry32 — create a seeded RNG function. */
+export function createRng(seed) {
+    return mulberry32(seed);
+}

package/dist/core/src/math/trig.js

@@ -0,0 +1,42 @@
+// ============================================================================
+// Fast trig — lookup-table-based sin/cos with linear interpolation
+// ============================================================================
+//
+// 4096 entries over 2π — ~16-bit precision. Replaces expensive Math.sin/
+// Math.cos calls in hot loops (e.g. water wave computation: ~458K calls/tick)
+// with array lookups + lerp.
+const TABLE_SIZE = 4096;
+const SCALE = TABLE_SIZE / (Math.PI * 2);
+const MASK = TABLE_SIZE - 1;
+const SIN_TABLE = (() => {
+    const t = new Float32Array(TABLE_SIZE);
+    for (let i = 0; i < TABLE_SIZE; i++) {
+        t[i] = Math.sin((i / TABLE_SIZE) * Math.PI * 2);
+    }
+    return t;
+})();
+const COS_TABLE = (() => {
+    const t = new Float32Array(TABLE_SIZE);
+    for (let i = 0; i < TABLE_SIZE; i++) {
+        t[i] = Math.cos((i / TABLE_SIZE) * Math.PI * 2);
+    }
+    return t;
+})();
+/** Fast sin via lookup table with linear interpolation. ~16-bit precision. */
+export function fastSin(x) {
+    const scaled = x * SCALE;
+    const idx = (scaled | 0) & MASK;
+    const frac = scaled - (scaled | 0);
+    const a = SIN_TABLE[idx];
+    const b = SIN_TABLE[(idx + 1) & MASK];
+    return a + (b - a) * frac;
+}
+/** Fast cos via lookup table with linear interpolation. ~16-bit precision. */
+export function fastCos(x) {
+    const scaled = x * SCALE;
+    const idx = (scaled | 0) & MASK;
+    const frac = scaled - (scaled | 0);
+    const a = COS_TABLE[idx];
+    const b = COS_TABLE[(idx + 1) & MASK];
+    return a + (b - a) * frac;
+}

package/dist/core/src/math/value-noise.js

@@ -0,0 +1,49 @@
+// ============================================================================
+// Value noise — seeded 2D value noise with fBm for procedural generation
+// ============================================================================
+//
+// Deterministic: same seed + same (x, y) always produces the same value.
+// Uses hash-based lattice interpolation (simpler and faster than Perlin
+// gradient noise, but less natural-looking). Used for procedural terrain generation.
+/** Integer hash for (x, y, seed) — returns [0, 1). */
+export function hash2(x, y, seed) {
+    let h = (x * 374761393 + y * 668265263 + seed * 362437) | 0;
+    h = (h ^ (h >>> 13)) * 1274126177;
+    h = h ^ (h >>> 16);
+    return (h >>> 0) / 4294967296;
+}
+/** Smoothstep interpolation: 3t² - 2t³ */
+export function smoothstep(t) {
+    return t * t * (3 - 2 * t);
+}
+/** 2D value noise via bilinear interpolation of hashed lattice values. Returns [0, 1). */
+export function valueNoise2D(x, y, seed) {
+    const ix = Math.floor(x);
+    const iy = Math.floor(y);
+    const fx = x - ix;
+    const fy = y - iy;
+    const a = hash2(ix, iy, seed);
+    const b = hash2(ix + 1, iy, seed);
+    const c = hash2(ix, iy + 1, seed);
+    const d = hash2(ix + 1, iy + 1, seed);
+    const ux = smoothstep(fx);
+    const uy = smoothstep(fy);
+    return (a * (1 - ux) * (1 - uy) +
+        b * ux * (1 - uy) +
+        c * (1 - ux) * uy +
+        d * ux * uy);
+}
+/** Multi-octave 2D value noise (fractal Brownian motion). Returns [0, 1). */
+export function fbm2D(x, y, seed, octaves = 4, lacunarity = 2.0, gain = 0.5) {
+    let value = 0;
+    let amplitude = 0.5;
+    let frequency = 1.0;
+    let maxAmplitude = 0;
+    for (let i = 0; i < octaves; i++) {
+        value += amplitude * valueNoise2D(x * frequency, y * frequency, seed + i * 1013);
+        maxAmplitude += amplitude;
+        frequency *= lacunarity;
+        amplitude *= gain;
+    }
+    return value / maxAmplitude;
+}

package/dist/core/src/mesh/builder.js

@@ -0,0 +1,137 @@
+import { STANDARD_VERTEX_LAYOUT } from "./vertex-layout.js";
+export class MeshBuilder {
+    vertices = [];
+    indices = [];
+    layout;
+    constructor(layout = STANDARD_VERTEX_LAYOUT) {
+        this.layout = layout;
+    }
+    addVertex(pos, normal = [0, 1, 0], uv = [0, 0], color = [1, 1, 1, 1]) {
+        const idx = this.vertices.length / (this.layout.stride / 4);
+        this.vertices.push(pos[0], pos[1], pos[2], normal[0], normal[1], normal[2], uv[0], uv[1], color[0], color[1], color[2], color[3]);
+        return idx;
+    }
+    addTriangle(a, b, c) {
+        this.indices.push(a, b, c);
+    }
+    addQuad(a, b, c, d) {
+        this.indices.push(a, b, c, a, c, d);
+    }
+    build() {
+        const vertices = new Float32Array(this.vertices);
+        const indexCount = this.indices.length;
+        const indices = indexCount > 65535
+            ? new Uint32Array(this.indices)
+            : new Uint16Array(this.indices);
+        return {
+            vertices,
+            indices,
+            layout: this.layout,
+            vertexCount: vertices.length / (this.layout.stride / 4),
+            indexCount,
+        };
+    }
+    static cube(size = 1) {
+        const builder = new MeshBuilder();
+        const half = size / 2;
+        const faces = [
+            {
+                normal: [0, 1, 0],
+                positions: [[-half, half, -half], [half, half, -half], [half, half, half], [-half, half, half]],
+            },
+            {
+                normal: [0, -1, 0],
+                positions: [[-half, -half, -half], [-half, -half, half], [half, -half, half], [half, -half, -half]],
+            },
+            {
+                normal: [1, 0, 0],
+                positions: [[half, -half, -half], [half, -half, half], [half, half, half], [half, half, -half]],
+            },
+            {
+                normal: [-1, 0, 0],
+                positions: [[-half, -half, -half], [-half, half, -half], [-half, half, half], [-half, -half, half]],
+            },
+            {
+                normal: [0, 0, 1],
+                positions: [[-half, -half, half], [-half, half, half], [half, half, half], [half, -half, half]],
+            },
+            {
+                normal: [0, 0, -1],
+                positions: [[-half, -half, -half], [half, -half, -half], [half, half, -half], [-half, half, -half]],
+            },
+        ];
+        const uvs = [
+            [0, 0], [1, 0], [1, 1], [0, 1],
+        ];
+        for (let f = 0; f < faces.length; f++) {
+            const face = faces[f];
+            const color = [
+                0.5 + face.normal[0] * 0.5,
+                0.5 + face.normal[1] * 0.5,
+                0.5 + face.normal[2] * 0.5,
+                1,
+            ];
+            const base = builder.addVertex(face.positions[0], face.normal, uvs[0], color);
+            const v1 = builder.addVertex(face.positions[1], face.normal, uvs[1], color);
+            const v2 = builder.addVertex(face.positions[2], face.normal, uvs[2], color);
+            const v3 = builder.addVertex(face.positions[3], face.normal, uvs[3], color);
+            builder.addQuad(base, v1, v2, v3);
+        }
+        return builder.build();
+    }
+    static plane(width = 1, depth = 1, segments = 1) {
+        const builder = new MeshBuilder();
+        const hw = width / 2;
+        const hd = depth / 2;
+        const sw = width / segments;
+        const sd = depth / segments;
+        for (let z = 0; z <= segments; z++) {
+            for (let x = 0; x <= segments; x++) {
+                const px = -hw + x * sw;
+                const pz = -hd + z * sd;
+                const u = x / segments;
+                const v = z / segments;
+                builder.addVertex([px, 0, pz], [0, 1, 0], [u, v]);
+            }
+        }
+        for (let z = 0; z < segments; z++) {
+            for (let x = 0; x < segments; x++) {
+                const a = z * (segments + 1) + x;
+                const b = a + 1;
+                const c = a + (segments + 1);
+                const d = c + 1;
+                builder.addQuad(a, b, d, c);
+            }
+        }
+        return builder.build();
+    }
+    static sphere(radius = 0.5, widthSegments = 16, heightSegments = 12) {
+        const builder = new MeshBuilder();
+        for (let y = 0; y <= heightSegments; y++) {
+            const v = y / heightSegments;
+            const phi = v * Math.PI;
+            for (let x = 0; x <= widthSegments; x++) {
+                const u = x / widthSegments;
+                const theta = u * Math.PI * 2;
+                const sinPhi = Math.sin(phi);
+                const px = radius * sinPhi * Math.cos(theta);
+                const py = radius * Math.cos(phi);
+                const pz = radius * sinPhi * Math.sin(theta);
+                const nx = px / radius;
+                const ny = py / radius;
+                const nz = pz / radius;
+                builder.addVertex([px, py, pz], [nx, ny, nz], [u, v]);
+            }
+        }
+        for (let y = 0; y < heightSegments; y++) {
+            for (let x = 0; x < widthSegments; x++) {
+                const a = y * (widthSegments + 1) + x;
+                const b = a + 1;
+                const c = a + (widthSegments + 1);
+                const d = c + 1;
+                builder.addQuad(a, b, d, c);
+            }
+        }
+        return builder.build();
+    }
+}