@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/trail.js

@@ -0,0 +1,555 @@
+import { VERTEX_LAYOUT_3D, VERTEX3D_FLOATS } from '../render/mesh.js';
+import { Transform } from '../render/transform.js';
+import { TRAIL_TEXTURED_WGSL, TRAIL_WGSL } from './trail-wgsl.js';
+/** Point stride in the ring: x, y, z, birth time. */
+const PF = 4;
+const VF = VERTEX3D_FLOATS;
+const DEFAULT_FADE = new Float32Array([1, 0]);
+const UP = new Float32Array([0, 1, 0]);
+const Z = new Float32Array([0, 0, 1]);
+/** Linear sample of channel `ch` of a table of `stride`-float stops at `t` in 0..1. */
+function sampleCurve(table, stride, ch, t) {
+    const stops = table.length / stride;
+    if (stops <= 1)
+        return table[ch] ?? 0;
+    const k = t * (stops - 1);
+    const i = Math.min(Math.floor(k), stops - 2);
+    const f = k - i;
+    return table[i * stride + ch] * (1 - f) + table[(i + 1) * stride + ch] * f;
+}
+function toTable(src) {
+    if (!src || src.length === 0)
+        return null;
+    const out = new Float32Array(src.length);
+    for (let i = 0; i < src.length; i++)
+        out[i] = src[i];
+    return out;
+}
+/** Index buffer for `quads` ribbon quads over vertices 0.. (two per point). */
+function ribbonIndices(quads, vertices) {
+    const idx = vertices > 0xffff ? new Uint32Array(quads * 6) : new Uint16Array(quads * 6);
+    writeQuads(idx, 0, 0, quads);
+    return idx;
+}
+/** Write `quads` quads starting at vertex `base` into `idx` at `at`; returns the next index. */
+function writeQuads(idx, at, base, quads) {
+    let o = at;
+    for (let q = 0; q < quads; q++) {
+        const a = base + q * 2;
+        idx[o++] = a;
+        idx[o++] = a + 1;
+        idx[o++] = a + 2;
+        idx[o++] = a + 1;
+        idx[o++] = a + 3;
+        idx[o++] = a + 2;
+    }
+    return o;
+}
+/**
+ * The points of one ribbon: a ring of stored points (x, y, z, birth time) plus the tip, the
+ * latest pushed position, which is drawn as an extra, age-0 point when it sits apart from the
+ * newest stored point. Nothing here touches the GPU.
+ */
+class Ring {
+    cap;
+    pts;
+    tail = 0;
+    /** Stored points. */
+    n = 0;
+    tip = new Float32Array(3);
+    hasTip = false;
+    constructor(cap) {
+        this.cap = cap;
+        this.pts = new Float32Array(cap * PF);
+    }
+    /** Store or move the tip; true when a point was stored. */
+    push(x, y, z, now, minDistance) {
+        const tip = this.tip;
+        tip[0] = x;
+        tip[1] = y;
+        tip[2] = z;
+        this.hasTip = true;
+        if (this.n > 0) {
+            const o = ((this.tail + this.n - 1) % this.cap) * PF;
+            const p = this.pts;
+            const dx = x - p[o];
+            const dy = y - p[o + 1];
+            const dz = z - p[o + 2];
+            if (dx * dx + dy * dy + dz * dz < minDistance * minDistance)
+                return false;
+        }
+        if (this.n === this.cap) {
+            this.tail = (this.tail + 1) % this.cap;
+            this.n--;
+        }
+        const o = ((this.tail + this.n) % this.cap) * PF;
+        const p = this.pts;
+        p[o] = x;
+        p[o + 1] = y;
+        p[o + 2] = z;
+        p[o + 3] = now;
+        this.n++;
+        return true;
+    }
+    /** Drop stored points older than `lifetime`. */
+    expire(now, lifetime) {
+        const p = this.pts;
+        while (this.n > 0 && now - p[this.tail * PF + 3] > lifetime) {
+            this.tail = (this.tail + 1) % this.cap;
+            this.n--;
+        }
+    }
+    /** Does the tip sit apart from the newest stored point (so it is drawn)? */
+    tipApart() {
+        if (!this.hasTip)
+            return false;
+        if (this.n === 0)
+            return true;
+        const o = ((this.tail + this.n - 1) % this.cap) * PF;
+        const p = this.pts;
+        const t = this.tip;
+        return p[o] !== t[0] || p[o + 1] !== t[1] || p[o + 2] !== t[2];
+    }
+    /** Points drawn: stored points plus the tip when apart. */
+    count() {
+        return this.n + (this.tipApart() ? 1 : 0);
+    }
+    /** Point `i` (0 = newest, the tip when apart) into `out` (x, y, z, birth time). */
+    read(i, now, out) {
+        let k = i;
+        if (this.tipApart()) {
+            if (k === 0) {
+                out[0] = this.tip[0];
+                out[1] = this.tip[1];
+                out[2] = this.tip[2];
+                out[3] = now;
+                return;
+            }
+            k--;
+        }
+        const o = ((this.tail + this.n - 1 - k) % this.cap) * PF;
+        const p = this.pts;
+        out[0] = p[o];
+        out[1] = p[o + 1];
+        out[2] = p[o + 2];
+        out[3] = p[o + 3];
+    }
+    clear() {
+        this.tail = 0;
+        this.n = 0;
+        this.hasTip = false;
+    }
+}
+const prev = new Float32Array(4);
+const cur = new Float32Array(4);
+const next = new Float32Array(4);
+const side = new Float32Array(3);
+const axis = new Float32Array(3);
+/**
+ * Build the ribbon of `ring` into `verts` (3D layout, two vertices per point, oldest first)
+ * from float `at`; returns the vertices written (0 when fewer than two points). Allocates
+ * nothing. `camera` drives `facing: 'camera'`: in world space the face turns toward the eye at
+ * each point, in 2D (or without a camera) it lies in the XY plane.
+ */
+function writeRibbon(ring, style, now, camera, verts, at) {
+    const m = ring.count();
+    if (m < 2)
+        return 0;
+    const facing = style.facing;
+    const toEye = facing === 'camera' && style.space === 'world' && camera !== null;
+    let eye = null;
+    if (facing === 'camera') {
+        if (toEye)
+            eye = camera.position;
+        else if (camera) {
+            const v = camera.view;
+            axis[0] = v[2];
+            axis[1] = v[6];
+            axis[2] = v[10];
+        }
+        else
+            axis.set(Z);
+    }
+    else if (facing === 'up')
+        axis.set(UP);
+    else {
+        axis[0] = facing[0];
+        axis[1] = facing[1];
+        axis[2] = facing[2];
+    }
+    const lifetime = style.lifetime;
+    const inv = lifetime > 0 ? 1 / lifetime : 0;
+    const tile = style.uvMode === 'tile';
+    const tileLen = style.width > 0 ? style.width : 1;
+    const color = style.color;
+    side[0] = 1;
+    side[1] = 0;
+    side[2] = 0;
+    let dist = 0;
+    ring.read(0, now, cur);
+    for (let j = 0; j < m; j++) {
+        if (j + 1 < m)
+            ring.read(j + 1, now, next);
+        let dx;
+        let dy;
+        let dz;
+        if (j === 0) {
+            dx = cur[0] - next[0];
+            dy = cur[1] - next[1];
+            dz = cur[2] - next[2];
+        }
+        else if (j + 1 < m) {
+            dx = prev[0] - next[0];
+            dy = prev[1] - next[1];
+            dz = prev[2] - next[2];
+        }
+        else {
+            dx = prev[0] - cur[0];
+            dy = prev[1] - cur[1];
+            dz = prev[2] - cur[2];
+        }
+        if (eye) {
+            axis[0] = eye[0] - cur[0];
+            axis[1] = eye[1] - cur[1];
+            axis[2] = eye[2] - cur[2];
+        }
+        // side = normalize(dir × axis); a degenerate pair keeps the previous side.
+        const sx = dy * axis[2] - dz * axis[1];
+        const sy = dz * axis[0] - dx * axis[2];
+        const sz = dx * axis[1] - dy * axis[0];
+        const sl = Math.hypot(sx, sy, sz);
+        if (sl > 1e-12) {
+            side[0] = sx / sl;
+            side[1] = sy / sl;
+            side[2] = sz / sl;
+        }
+        // normal = side × dir, the face direction (toward the eye / the axis).
+        let nx = side[1] * dz - side[2] * dy;
+        let ny = side[2] * dx - side[0] * dz;
+        let nz = side[0] * dy - side[1] * dx;
+        const nl = Math.hypot(nx, ny, nz);
+        if (nl > 1e-12) {
+            nx /= nl;
+            ny /= nl;
+            nz /= nl;
+        }
+        else {
+            nx = axis[0];
+            ny = axis[1];
+            nz = axis[2];
+        }
+        const t = Math.min(Math.max((now - cur[3]) * inv, 0), 1);
+        const hw = (style.widthCurve ? sampleCurve(style.widthCurve, 1, 0, t) : style.width) / 2;
+        let a = style.colorCurve ? sampleCurve(style.colorCurve, 4, 3, t) : color[3];
+        if (style.fade)
+            a *= sampleCurve(style.fade, 1, 0, t);
+        const r = style.colorCurve ? sampleCurve(style.colorCurve, 4, 0, t) : color[0];
+        const g = style.colorCurve ? sampleCurve(style.colorCurve, 4, 1, t) : color[1];
+        const b = style.colorCurve ? sampleCurve(style.colorCurve, 4, 2, t) : color[2];
+        if (j > 0)
+            dist += Math.hypot(cur[0] - prev[0], cur[1] - prev[1], cur[2] - prev[2]);
+        const u = tile ? dist / tileLen : j / (m - 1);
+        const px = cur[0];
+        const py = cur[1];
+        const pz = cur[2];
+        const ox = side[0] * hw;
+        const oy = side[1] * hw;
+        const oz = side[2] * hw;
+        // Oldest first in the buffer so the index buffer is static.
+        let o = at + (m - 1 - j) * 2 * VF;
+        verts[o++] = px + ox;
+        verts[o++] = py + oy;
+        verts[o++] = pz + oz;
+        verts[o++] = nx;
+        verts[o++] = ny;
+        verts[o++] = nz;
+        verts[o++] = u;
+        verts[o++] = 0;
+        verts[o++] = r;
+        verts[o++] = g;
+        verts[o++] = b;
+        verts[o++] = a;
+        verts[o++] = px - ox;
+        verts[o++] = py - oy;
+        verts[o++] = pz - oz;
+        verts[o++] = nx;
+        verts[o++] = ny;
+        verts[o++] = nz;
+        verts[o++] = u;
+        verts[o++] = 1;
+        verts[o++] = r;
+        verts[o++] = g;
+        verts[o++] = b;
+        verts[o++] = a;
+        prev.set(cur);
+        cur.set(next);
+    }
+    return m * 2;
+}
+/** Untextured trail materials, one per renderer and blend mode (textured ones are per trail). */
+const sharedMaterials = new WeakMap();
+function trailMaterial(renderer, opts, label) {
+    const blend = opts.blend ?? 'additive';
+    if (opts.texture) {
+        const m = renderer.createMaterial({
+            label: `${label}-textured`,
+            wgsl: TRAIL_TEXTURED_WGSL,
+            blend,
+            textures: 1,
+            sampler: opts.uvMode === 'tile' ? 'linear-repeat' : 'linear-clamp',
+        });
+        m.setTexture(0, opts.texture);
+        return m;
+    }
+    let byBlend = sharedMaterials.get(renderer);
+    if (!byBlend) {
+        byBlend = new Map();
+        sharedMaterials.set(renderer, byBlend);
+    }
+    let m = byBlend.get(blend);
+    if (!m) {
+        m = renderer.createMaterial({ label: `trail-${blend}`, wgsl: TRAIL_WGSL, blend });
+        byBlend.set(blend, m);
+    }
+    return m;
+}
+/** Fields `Trail` and `TrailBatch` share; `TrailStyle` plus the GPU side. */
+class RibbonBase {
+    space;
+    /** Seconds a point lives. Mutable. */
+    lifetime;
+    /** Ribbon width (or the tile length under `widthCurve`). Mutable. */
+    width;
+    /** See `TrailOptions.minDistance`. Mutable. */
+    minDistance;
+    /** See `TrailFacing`. Mutable. */
+    facing;
+    widthCurve;
+    /** Linear RGBA; mutate in place. */
+    color;
+    colorCurve;
+    fade;
+    uvMode;
+    /** The mesh the ribbon is written into (3D vertex layout; two vertices per point). */
+    mesh;
+    /** The unlit soft-edged material (shared per renderer and blend unless textured). */
+    material;
+    /**
+     * Places the ribbon: identity by default (points are already in trail space). Parent it or
+     * move it like any `Transform`.
+     */
+    transform = new Transform();
+    /**
+     * Per-draw instance fields (`tint`, `emissive`, `order`, `layers`, ...); `params.x` is the
+     * edge softness and is owned by the trail (`softness`).
+     */
+    instance;
+    params = new Float32Array(4);
+    ownsMaterial;
+    time = 0;
+    /** Vertices the last `update` wrote. */
+    written = 0;
+    vertexUpdate = { vertexCount: 0, indexCount: 0 };
+    constructor(renderer, opts, vertices, indices, label) {
+        const world = opts.space === 'world';
+        this.space = world ? 'world' : '2d';
+        this.lifetime = opts.lifetime ?? 0.5;
+        this.width = opts.width ?? (world ? 0.2 : 12);
+        this.minDistance = opts.minDistance ?? (world ? 0.02 : 2);
+        this.facing = opts.facing ?? 'camera';
+        this.widthCurve = toTable(opts.widthCurve);
+        this.color = new Float32Array(4);
+        const c = opts.color;
+        this.color[0] = c ? c[0] : 1;
+        this.color[1] = c ? c[1] : 1;
+        this.color[2] = c ? c[2] : 1;
+        this.color[3] = c ? (c[3] ?? 1) : 1;
+        this.colorCurve = toTable(opts.colorCurve);
+        this.fade = opts.fade === null ? null : (toTable(opts.fade) ?? DEFAULT_FADE);
+        this.uvMode = opts.uvMode ?? 'stretch';
+        this.params[0] = opts.softness ?? 0.5;
+        this.instance = { params: this.params };
+        this.ownsMaterial = !!opts.texture;
+        this.material = trailMaterial(renderer, opts, label);
+        this.mesh = renderer.createMesh({
+            label,
+            layout: VERTEX_LAYOUT_3D,
+            capacity: { vertices, indices: indices ? indices.length : 0 },
+            indices,
+        });
+        this.mesh.update({ vertexCount: 0, indexCount: 0 });
+    }
+    /** Share of the half width that fades toward each long edge, 0..1. */
+    get softness() {
+        return this.params[0];
+    }
+    set softness(v) {
+        this.params[0] = v;
+    }
+    /** Upload `count` vertices of `verts` and set the index range (allocation-free). */
+    upload(verts, count, indexCount) {
+        const u = this.vertexUpdate;
+        u.vertices = verts;
+        u.vertexCount = count;
+        u.indexCount = indexCount;
+        this.written = count;
+        this.mesh.update(u);
+    }
+    /** Record the ribbon into `frame` (nothing when it has fewer than two points). */
+    draw(frame) {
+        if (this.written < 4)
+            return;
+        frame.mesh(this.mesh, this.material, this.transform, this.instance);
+    }
+    destroy() {
+        this.mesh.destroy();
+        if (this.ownsMaterial)
+            this.material.destroy();
+    }
+}
+/**
+ * A ribbon trail: a strip that follows a moving point, with width, colour and alpha over age,
+ * camera-facing or fixed-axis, in 2D or world space.
+ *
+ * ```ts
+ * const trail = new Trail(renderer, { space: 'world', width: 0.15, lifetime: 0.4 });
+ * trail.push(tip.x, tip.y, tip.z);   // every update, wherever the point is
+ * trail.update(dt, camera);          // ages points and rebuilds the ribbon
+ * trail.draw(frame);                 // inside the scene's render
+ * ```
+ *
+ * Geometry is built on the CPU into one preallocated array (two vertices per point, the
+ * oldest first, over a static index buffer) and uploaded through `Mesh.update` each frame;
+ * nothing allocates after construction.
+ */
+export class Trail extends RibbonBase {
+    maxPoints;
+    ring;
+    verts;
+    constructor(renderer, opts = {}) {
+        const cap = Math.max(2, Math.floor(opts.maxPoints ?? 64));
+        const vertices = (cap + 1) * 2;
+        super(renderer, opts, vertices, ribbonIndices(cap, vertices), opts.label ?? 'trail');
+        this.maxPoints = cap;
+        this.ring = new Ring(cap);
+        this.verts = new Float32Array(vertices * VF);
+    }
+    /** Points the ribbon currently has (stored points plus the tip when it sits apart). */
+    get count() {
+        return this.ring.count();
+    }
+    /**
+     * Point `i` (0 = newest) into `out` as `x, y, z`. Out of range leaves `out` untouched and
+     * returns false.
+     */
+    pointAt(i, out) {
+        if (i < 0 || i >= this.ring.count())
+            return false;
+        this.ring.read(i, this.time, cur);
+        out.x = cur[0];
+        out.y = cur[1];
+        out.z = cur[2];
+        return true;
+    }
+    /**
+     * Move the trail's tip to a point. A point farther than `minDistance` from the newest stored
+     * one is stored (true); a closer one only moves the tip (false). When `maxPoints` are stored
+     * the oldest drops.
+     */
+    push(x, y, z = 0) {
+        return this.ring.push(x, y, z, this.time, this.minDistance);
+    }
+    /**
+     * Advance time, drop points older than `lifetime` and rebuild the ribbon. `camera` turns a
+     * `facing: 'camera'` ribbon (needed in world space; in 2D the ribbon lies flat without it).
+     */
+    update(dt, camera) {
+        this.time += dt;
+        const ring = this.ring;
+        ring.expire(this.time, this.lifetime);
+        const n = writeRibbon(ring, this, this.time, camera ?? null, this.verts, 0);
+        this.upload(this.verts, n, n >= 4 ? (n / 2 - 1) * 6 : 0);
+    }
+    /** Forget every point; the ribbon is empty until the next `push` and `update`. */
+    clear() {
+        this.ring.clear();
+        this.upload(this.verts, 0, 0);
+    }
+}
+/**
+ * Many ribbons of one style in one mesh and one draw (projectiles, a flock). Each ribbon is
+ * addressed by its index; `update` rebuilds the shared vertex and index arrays in place.
+ */
+export class TrailBatch extends RibbonBase {
+    /** Ribbons in the batch. */
+    size;
+    maxPoints;
+    rings;
+    verts;
+    indices;
+    indexUpdate;
+    constructor(renderer, size, opts = {}) {
+        const cap = Math.max(2, Math.floor(opts.maxPoints ?? 64));
+        const count = Math.max(1, Math.floor(size));
+        const vertices = (cap + 1) * 2 * count;
+        super(renderer, opts, vertices, ribbonIndices(cap * count, vertices), opts.label ?? 'trails');
+        this.size = count;
+        this.maxPoints = cap;
+        this.rings = [];
+        for (let i = 0; i < count; i++)
+            this.rings.push(new Ring(cap));
+        this.verts = new Float32Array(vertices * VF);
+        this.indices =
+            vertices > 0xffff ? new Uint32Array(cap * count * 6) : new Uint16Array(cap * count * 6);
+        this.indexUpdate = { indices: this.indices, indexCount: 0 };
+    }
+    /** Points ribbon `i` currently has. */
+    count(i) {
+        return this.rings[i]?.count() ?? 0;
+    }
+    /** `Trail.pointAt` for ribbon `i`: point `j` (0 = newest) into `out`. */
+    pointAt(i, j, out) {
+        const r = this.rings[i];
+        if (!r || j < 0 || j >= r.count())
+            return false;
+        r.read(j, this.time, cur);
+        out.x = cur[0];
+        out.y = cur[1];
+        out.z = cur[2];
+        return true;
+    }
+    /** `Trail.push` for ribbon `i`. */
+    push(i, x, y, z = 0) {
+        const r = this.rings[i];
+        return r ? r.push(x, y, z, this.time, this.minDistance) : false;
+    }
+    /** `Trail.update` for every ribbon, packed into one mesh. */
+    update(dt, camera) {
+        this.time += dt;
+        const cam = camera ?? null;
+        let vb = 0;
+        let ib = 0;
+        for (const ring of this.rings) {
+            ring.expire(this.time, this.lifetime);
+            const n = writeRibbon(ring, this, this.time, cam, this.verts, vb * VF);
+            if (n < 4)
+                continue;
+            ib = writeQuads(this.indices, ib, vb, n / 2 - 1);
+            vb += n;
+        }
+        const u = this.indexUpdate;
+        u.indexCount = ib;
+        this.mesh.update(u);
+        this.upload(this.verts, vb, ib);
+    }
+    /** Forget ribbon `i`'s points, or every ribbon's without an index. */
+    clear(i) {
+        if (i === undefined)
+            for (const r of this.rings)
+                r.clear();
+        else
+            this.rings[i]?.clear();
+        if (i === undefined)
+            this.upload(this.verts, 0, 0);
+    }
+}

package/dist/fx/water-wgsl.d.ts

@@ -0,0 +1,34 @@
+/** Wave layers the params block carries (`WaterOptions.waves` beyond this are ignored). */
+export declare const WATER_MAX_WAVES = 4;
+/**
+ * The water shader: a plane in the engine's 3D vertex layout, no instance, group 1 = the
+ * water's params block and its copy of the scene depth.
+ *
+ * Waves. Each layer is an analytic field with a closed-form gradient (`water_wave`):
+ * `p = (x, z) * scale + dir * (t * speed)`, `a = p.x + 0.6 sin(1.3 p.y)`,
+ * `b = 0.8 p.y + 0.5 sin(0.9 p.x)`, value `sin(a) cos(b)` in -1..1, and its derivatives by the
+ * chain rule. The height is `level + displace * Σ amplitude_i * value_i` (the vertex shader
+ * offsets y by it; `waterHeight` in `water.ts` is the same sum in TypeScript), and the normal
+ * is `normalize(-slope.x, 1, -slope.z)` with `slope = Σ amplitude_i * scale_i * grad_i`, so
+ * `amplitude` is the normal strength whether or not vertices move.
+ *
+ * Shading, all linear: the view ray's Schlick Fresnel (f0 0.02) times `fresnel` lerps the
+ * refraction colour (`shallow` → `deep` by the linear depth below the surface over
+ * `depth_fade`, from the depth copy) towards the reflection colour (a sky gradient between
+ * `lights.fog.rgb`, or a pale haze without fog, at the horizon and a bluer zenith, darkened at
+ * night like `Sky`); the sun adds a GGX lobe of `roughness` (`engine_d_ggx`,
+ * `engine_v_smith_ggx`, `engine_f_schlick` from `WGSL_PBR`), which also goes to the emissive
+ * target so bloom picks it up; foam (`foam.w` > 0) mixes `foam.rgb` in where the depth below the
+ * surface is under `foam.w`, through a two-octave noise mask; the alpha ramps up from zero at
+ * the shoreline over a quarter of `depth_fade` to `opacity`, then `engine_fog`.
+ *
+ * Depth copy. `misc.z` says whether `scene_depth` holds this frame's copy. Its texel is turned
+ * into view-space z (`view_z_of`) and compared with the fragment's own: the difference is the
+ * water depth along the ray. A texel within a sliver of the fragment's own depth is the water
+ * surface itself (the copy was taken after a frame that drew this water into the same depth
+ * buffer) and counts as no information: fully deep, no foam. Without a copy the surface is
+ * deep everywhere, foam off.
+ */
+export declare const WATER_WGSL: string;
+/** Copies a depth texture into the water's own depth32float copy (one fullscreen triangle). */
+export declare const WATER_DEPTH_COPY_WGSL = "\n@group(0) @binding(0) var src: texture_depth_2d;\n@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {\n  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));\n  return vec4f(p * 2.0 - 1.0, 0.0, 1.0);\n}\n@fragment fn fs(@builtin(position) pos: vec4f) -> @builtin(frag_depth) f32 {\n  return textureLoad(src, vec2i(pos.xy), 0);\n}\n";