@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/text-atlas.js

@@ -0,0 +1,327 @@
+/**
+ * A canvas text atlas: strings rasterised once with `CanvasRenderingContext2D.fillText` into
+ * one square canvas, packed on shelves, cached by text and style, with least-recently-used
+ * eviction when the canvas is full. No GPU and no DOM beyond the canvas itself: the owner
+ * uploads `canvas` when `dirty` is set (`Billboards` does it once per frame at most).
+ */
+/** One cached string: its region plus the bookkeeping for packing and eviction. */
+class Entry {
+    u0 = 0;
+    v0 = 0;
+    u1 = 0;
+    v1 = 0;
+    width = 0;
+    height = 0;
+    /** Atlas px of the top-left corner. */
+    x = 0;
+    y = 0;
+    /** `TextAtlas.tick` when last requested or touched. */
+    lastUsed = 0;
+    shelf = null;
+    key = '';
+    /** An owned cell's resolved style (`TextAtlas.cell`); null for a cached string. */
+    style = null;
+}
+/** An owned cell's width is rounded up to this many atlas px, headroom for `rewrite`. */
+const CELL_STEP = 32;
+/** A row of the canvas: fixed height, entries packed left to right. */
+class Shelf {
+    y;
+    height;
+    /** Next free x. */
+    used = 0;
+    entries = [];
+    constructor(y, height) {
+        this.y = y;
+        this.height = height;
+    }
+}
+function makeCanvas(size) {
+    if (typeof OffscreenCanvas !== 'undefined')
+        return new OffscreenCanvas(size, size);
+    if (typeof document !== 'undefined') {
+        const c = document.createElement('canvas');
+        c.width = size;
+        c.height = size;
+        return c;
+    }
+    throw new Error('TextAtlas: no canvas available (pass `canvas`)');
+}
+/**
+ * Text rendered once into a canvas and shared by every quad that shows it. `text(text, style)`
+ * returns the cached `AtlasRegion` or rasterises and packs a new one; when the canvas is full the
+ * least recently used shelf is cleared and reused. Read `dirty` and `canvas` to upload, then
+ * call `markUploaded()`.
+ */
+export class TextAtlas {
+    size;
+    canvas;
+    /** The canvas has text the GPU has not seen yet. */
+    dirty = false;
+    /** Strings currently cached. */
+    count = 0;
+    /** Evictions so far (shelves cleared because the canvas was full). */
+    evictions = 0;
+    ctx;
+    font;
+    cache = new Map();
+    shelves = [];
+    /** Next free y for a new shelf. */
+    top = 0;
+    tick = 0;
+    /** Owned cells made so far (their cache keys). */
+    cells = 0;
+    constructor(opts = {}) {
+        this.size = Math.max(16, Math.floor(opts.size ?? 1024));
+        this.font = opts.font ?? 'sans-serif';
+        this.canvas = opts.canvas ?? makeCanvas(this.size);
+        const ctx = this.canvas.getContext('2d');
+        if (!ctx)
+            throw new Error('TextAtlas: no 2d context');
+        this.ctx = ctx;
+    }
+    /** Atlas px in use, as a share of the canvas (shelf area, 0..1). */
+    get used() {
+        let area = 0;
+        for (const s of this.shelves)
+            area += s.used * s.height;
+        return area / (this.size * this.size);
+    }
+    /**
+     * The region for `text` in `style`: cached, or rasterised now. Returns `null` only when the
+     * string is wider or taller than the whole canvas.
+     */
+    text(text, style = {}) {
+        const r = this.resolve(style);
+        const key = `${text}\u0001${r.font}\u0001${r.size}\u0001${r.color}\u0001${r.stroke}\u0001${r.sw}\u0001${r.pad}`;
+        this.tick++;
+        const hit = this.cache.get(key);
+        if (hit) {
+            hit.lastUsed = this.tick;
+            return hit;
+        }
+        const w = this.measure(text, r);
+        const h = this.lineHeight(r);
+        if (w > this.size || h > this.size)
+            return null;
+        const e = this.make(key, w, h);
+        this.draw(e, text, r);
+        return e;
+    }
+    /**
+     * An **owned** cell for text that changes (ws/fx-4): not shared through the cache, its width
+     * rounded up for headroom, the region covering the whole cell with `text` centred in it.
+     * Change its text with `rewrite`; `release` it when done. Evicted like any string when the
+     * canvas is full and it is the least recently used (`touch` keeps it). Returns `null` only
+     * when the text is larger than the whole canvas.
+     */
+    cell(text, style = {}) {
+        return this.makeCell(text, this.resolve(style));
+    }
+    /** The size in atlas px `cell(text, style)` would get, without placing anything. */
+    cellSize(text, style = {}) {
+        const r = this.resolve(style);
+        const tw = this.measure(text, r);
+        return {
+            width: Math.min(this.size, Math.ceil(tw / CELL_STEP) * CELL_STEP),
+            height: this.lineHeight(r),
+        };
+    }
+    /**
+     * Redraw an owned cell with `text`, in place (the same region object, nothing allocated) when
+     * it fits the cell, else in a new wider cell (the old one released). Also a new cell when
+     * `cell` was evicted since. Returns `null` when the text is larger than the whole canvas.
+     */
+    rewrite(cell, text) {
+        const e = cell;
+        if (!e.style)
+            throw new Error('TextAtlas.rewrite: not an owned cell (use `cell`)');
+        const r = e.style;
+        this.tick++;
+        if (this.has(e) && this.measure(text, r) <= e.width) {
+            e.lastUsed = this.tick;
+            this.draw(e, text, r);
+            return e;
+        }
+        this.release(e);
+        return this.makeCell(text, r);
+    }
+    /** Give back an owned cell (a no-op for a cached string or one already released/evicted). */
+    release(cell) {
+        const e = cell;
+        if (!e.style || !this.has(e))
+            return;
+        this.cache.delete(e.key);
+        const s = e.shelf;
+        const at = s.entries.indexOf(e);
+        if (at >= 0)
+            s.entries.splice(at, 1);
+        this.ctx.clearRect(e.x, e.y, e.width, e.height);
+        this.recycle(e);
+        this.count--;
+        this.dirty = true;
+    }
+    /** Mark `region` as used now, so a live quad's text is not the first evicted. */
+    touch(region) {
+        region.lastUsed = this.tick;
+    }
+    /** Is `region` still what it was made for (not evicted since)? */
+    has(region) {
+        const e = region;
+        return e.shelf !== null && this.cache.get(e.key) === e;
+    }
+    /** The owner uploaded `canvas`. */
+    markUploaded() {
+        this.dirty = false;
+    }
+    /** Forget every string and clear the canvas. */
+    clear() {
+        for (const e of this.cache.values())
+            this.recycle(e);
+        this.cache.clear();
+        this.shelves.length = 0;
+        this.top = 0;
+        this.count = 0;
+        this.ctx.clearRect(0, 0, this.size, this.size);
+        this.dirty = true;
+    }
+    resolve(style) {
+        const stroke = style.stroke ?? '';
+        return {
+            font: style.font ?? this.font,
+            size: style.size ?? 32,
+            color: style.color ?? '#fff',
+            stroke,
+            sw: stroke ? (style.strokeWidth ?? 0) : 0,
+            pad: style.padding ?? 2,
+        };
+    }
+    measure(text, r) {
+        this.ctx.font = `${r.size}px ${r.font}`;
+        return Math.ceil(this.ctx.measureText(text).width + 2 * r.pad + r.sw);
+    }
+    lineHeight(r) {
+        return Math.ceil(r.size * 1.25 + 2 * r.pad + r.sw);
+    }
+    makeCell(text, r) {
+        const h = this.lineHeight(r);
+        const tw = this.measure(text, r);
+        if (tw > this.size || h > this.size)
+            return null;
+        const w = Math.min(this.size, Math.ceil(tw / CELL_STEP) * CELL_STEP);
+        const e = this.make(`\u0002cell#${this.cells++}`, w, h);
+        e.style = r;
+        this.draw(e, text, r);
+        return e;
+    }
+    /** Place, size and cache a `w × h` entry under `key`. */
+    make(key, w, h) {
+        const e = this.place(w, h);
+        e.key = key;
+        e.lastUsed = this.tick;
+        e.width = w;
+        e.height = h;
+        const inv = 1 / this.size;
+        e.u0 = e.x * inv;
+        e.v0 = e.y * inv;
+        e.u1 = (e.x + w) * inv;
+        e.v1 = (e.y + h) * inv;
+        this.cache.set(key, e);
+        this.count++;
+        return e;
+    }
+    /** Clear `e`'s rect and draw `text` centred in it. */
+    draw(e, text, r) {
+        const ctx = this.ctx;
+        ctx.clearRect(e.x, e.y, e.width, e.height);
+        ctx.font = `${r.size}px ${r.font}`;
+        ctx.textBaseline = 'middle';
+        ctx.textAlign = 'center';
+        const cx = e.x + e.width / 2;
+        const cy = e.y + e.height / 2;
+        if (r.sw > 0) {
+            ctx.lineJoin = 'round';
+            ctx.lineWidth = r.sw;
+            ctx.strokeStyle = r.stroke;
+            ctx.strokeText(text, cx, cy);
+        }
+        ctx.fillStyle = r.color;
+        ctx.fillText(text, cx, cy);
+        this.dirty = true;
+    }
+    /** Find or make room for a `w × h` rect: a fitting shelf, a new shelf, or an evicted one. */
+    place(w, h) {
+        const fit = this.fit(w, h);
+        if (fit)
+            return this.alloc(fit, w, h);
+        if (this.top + h <= this.size) {
+            const s = new Shelf(this.top, h);
+            this.top += h;
+            this.shelves.push(s);
+            return this.alloc(s, w, h);
+        }
+        // Full: clear least-recently-used shelves until one fits.
+        for (;;) {
+            let victim = null;
+            let oldest = Number.POSITIVE_INFINITY;
+            for (const s of this.shelves) {
+                if (s.height < h || s.entries.length === 0)
+                    continue;
+                let newest = 0;
+                for (const e of s.entries)
+                    if (e.lastUsed > newest)
+                        newest = e.lastUsed;
+                if (newest < oldest) {
+                    oldest = newest;
+                    victim = s;
+                }
+            }
+            if (!victim) {
+                // No shelf is tall enough: start over.
+                this.clear();
+                const s = new Shelf(0, h);
+                this.top = h;
+                this.shelves.push(s);
+                return this.alloc(s, w, h);
+            }
+            this.evict(victim);
+            if (victim.used + w <= this.size)
+                return this.alloc(victim, w, h);
+        }
+    }
+    fit(w, h) {
+        let best = null;
+        for (const s of this.shelves) {
+            if (s.height >= h && s.used + w <= this.size && (!best || s.height < best.height))
+                best = s;
+        }
+        return best;
+    }
+    alloc(s, w, h) {
+        // A fresh object per string: an evicted region stays stale (`has` is false) rather than
+        // silently becoming another string's rect. Eviction is rare, never per frame.
+        const e = new Entry();
+        e.x = s.used;
+        e.y = s.y;
+        e.shelf = s;
+        s.used += w;
+        s.entries.push(e);
+        this.ctx.clearRect(e.x, e.y, w, h);
+        return e;
+    }
+    evict(s) {
+        for (const e of s.entries) {
+            this.cache.delete(e.key);
+            this.recycle(e);
+            this.count--;
+        }
+        s.entries.length = 0;
+        s.used = 0;
+        this.ctx.clearRect(0, s.y, this.size, s.height);
+        this.evictions++;
+        this.dirty = true;
+    }
+    recycle(e) {
+        e.shelf = null;
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The trail material: unlit vertex colour, soft across the ribbon, no lighting block reads.
+ *
+ * The ribbon's vertex colour already carries the age fade (alpha) from the CPU; here the
+ * fragment fades toward the two long edges. `in.local.y` is 0 on one edge and 1 on the other
+ * (the raw vertex v, untouched by `uvRect`); `in.params.x` is the edge softness (0..1, the
+ * share of the half width that fades). Emissive is colour × `in.emissive`, like the sprite.
+ */
+export declare const TRAIL_WGSL = "\nfn trail_edge(local_v: f32, softness: f32) -> f32 {\n  let edge = abs(local_v - 0.5) * 2.0;\n  return 1.0 - smoothstep(1.0 - max(softness, 1e-4), 1.0, edge);\n}\n\n@fragment fn fs_main(in: VSOut) -> FragOut {\n  let a = in.color.a * trail_edge(in.local.y, in.params.x);\n  var o: FragOut;\n  o.color = vec4f(in.color.rgb, a);\n  o.emissive = vec4f(in.color.rgb * in.emissive, a);\n  return o;\n}\n";
+/** Same, times a texture: `u` runs along the ribbon (stretched or tiled), `v` across it. */
+export declare const TRAIL_TEXTURED_WGSL = "\n@group(1) @binding(1) var trailSampler: sampler;\n@group(1) @binding(2) var trailTex: texture_2d<f32>;\n\nfn trail_edge(local_v: f32, softness: f32) -> f32 {\n  let edge = abs(local_v - 0.5) * 2.0;\n  return 1.0 - smoothstep(1.0 - max(softness, 1e-4), 1.0, edge);\n}\n\n@fragment fn fs_main(in: VSOut) -> FragOut {\n  let t = textureSample(trailTex, trailSampler, in.uv);\n  let rgb = in.color.rgb * t.rgb;\n  let a = in.color.a * t.a * trail_edge(in.local.y, in.params.x);\n  var o: FragOut;\n  o.color = vec4f(rgb, a);\n  o.emissive = vec4f(rgb * in.emissive, a);\n  return o;\n}\n";

package/dist/fx/trail-wgsl.js

@@ -0,0 +1,42 @@
+/**
+ * The trail material: unlit vertex colour, soft across the ribbon, no lighting block reads.
+ *
+ * The ribbon's vertex colour already carries the age fade (alpha) from the CPU; here the
+ * fragment fades toward the two long edges. `in.local.y` is 0 on one edge and 1 on the other
+ * (the raw vertex v, untouched by `uvRect`); `in.params.x` is the edge softness (0..1, the
+ * share of the half width that fades). Emissive is colour × `in.emissive`, like the sprite.
+ */
+export const TRAIL_WGSL = /* wgsl */ `
+fn trail_edge(local_v: f32, softness: f32) -> f32 {
+  let edge = abs(local_v - 0.5) * 2.0;
+  return 1.0 - smoothstep(1.0 - max(softness, 1e-4), 1.0, edge);
+}
+
+@fragment fn fs_main(in: VSOut) -> FragOut {
+  let a = in.color.a * trail_edge(in.local.y, in.params.x);
+  var o: FragOut;
+  o.color = vec4f(in.color.rgb, a);
+  o.emissive = vec4f(in.color.rgb * in.emissive, a);
+  return o;
+}
+`;
+/** Same, times a texture: `u` runs along the ribbon (stretched or tiled), `v` across it. */
+export const TRAIL_TEXTURED_WGSL = /* wgsl */ `
+@group(1) @binding(1) var trailSampler: sampler;
+@group(1) @binding(2) var trailTex: texture_2d<f32>;
+
+fn trail_edge(local_v: f32, softness: f32) -> f32 {
+  let edge = abs(local_v - 0.5) * 2.0;
+  return 1.0 - smoothstep(1.0 - max(softness, 1e-4), 1.0, edge);
+}
+
+@fragment fn fs_main(in: VSOut) -> FragOut {
+  let t = textureSample(trailTex, trailSampler, in.uv);
+  let rgb = in.color.rgb * t.rgb;
+  let a = in.color.a * t.a * trail_edge(in.local.y, in.params.x);
+  var o: FragOut;
+  o.color = vec4f(rgb, a);
+  o.emissive = vec4f(rgb * in.emissive, a);
+  return o;
+}
+`;

package/dist/fx/trail.d.ts

@@ -0,0 +1,194 @@
+import type { Camera } from '../render/camera.js';
+import type { Frame, InstanceParams } from '../render/frame.js';
+import type { Material } from '../render/material.js';
+import { type Mesh } from '../render/mesh.js';
+import type { Renderer } from '../render/renderer.js';
+import type { TextureLike } from '../render/texture.js';
+import { Transform } from '../render/transform.js';
+/**
+ * Which way the ribbon's face turns: `'camera'` (toward the camera passed to `update`; in 2D,
+ * flat in the XY plane), `'up'` (the ribbon lies flat, its face along +y) or a fixed axis the
+ * face is perpendicular to the motion and to.
+ */
+export type TrailFacing = 'camera' | 'up' | readonly [number, number, number];
+/** `'additive'`: glows and sparks. `'alpha'`: straight alpha over the scene. */
+export type TrailBlend = 'alpha' | 'additive';
+export interface TrailOptions {
+    /**
+     * `'2d'` (default): points in logical px, z optional (the ribbon lies in the XY plane).
+     * `'world'`: points in world units, y up, the ribbon facing the camera or a fixed axis.
+     */
+    space?: '2d' | 'world';
+    /** Points kept (ring buffer; the oldest drops when full). Default 64, at least 2. */
+    maxPoints?: number;
+    /** Ribbon width (px in 2D, world units in world space). Default 12 / 0.2. */
+    width?: number;
+    /**
+     * Width over age instead of `width`: stops from the newest point (age 0) to the oldest (age
+     * `lifetime`), linearly interpolated. `width` still sets the tile length of `uvMode: 'tile'`.
+     */
+    widthCurve?: ArrayLike<number>;
+    /** Linear RGBA (HDR ok). Default white. */
+    color?: ArrayLike<number>;
+    /** Colour over age instead of `color`: RGBA stops, newest to oldest. */
+    colorCurve?: ArrayLike<number>;
+    /**
+     * Alpha multiplier over age: stops, newest to oldest, applied on top of `color` /
+     * `colorCurve`. Default `[1, 0]` (a linear fade out); `null` for none.
+     */
+    fade?: ArrayLike<number> | null;
+    /** Seconds a point lives. Default 0.5. */
+    lifetime?: number;
+    /**
+     * Minimum distance between stored points. A push closer than this to the newest stored point
+     * moves the ribbon's tip without storing a point. Default 2 px / 0.02 units.
+     */
+    minDistance?: number;
+    /** Default `'camera'`. */
+    facing?: TrailFacing;
+    /** Default `'additive'`. */
+    blend?: TrailBlend;
+    /** Multiplied in, `u` along the ribbon and `v` across it. Default none (vertex colour only). */
+    texture?: TextureLike;
+    /**
+     * `'stretch'` (default): `u` runs 0 at the tip to 1 at the tail, whatever the length.
+     * `'tile'`: one repeat of the texture per `width` of ribbon length, anchored at the tip.
+     */
+    uvMode?: 'stretch' | 'tile';
+    /** Share of the half width that fades toward each long edge, 0..1. Default 0.5. */
+    softness?: number;
+    label?: string;
+}
+/** The per-frame look of a ribbon, read by the geometry writer (public fields on `Trail`). */
+interface TrailStyle {
+    readonly space: '2d' | 'world';
+    lifetime: number;
+    width: number;
+    facing: TrailFacing;
+    readonly widthCurve: Float32Array | null;
+    readonly color: Float32Array;
+    readonly colorCurve: Float32Array | null;
+    readonly fade: Float32Array | null;
+    readonly uvMode: 'stretch' | 'tile';
+}
+/** Fields `Trail` and `TrailBatch` share; `TrailStyle` plus the GPU side. */
+declare abstract class RibbonBase implements TrailStyle {
+    readonly space: '2d' | 'world';
+    /** Seconds a point lives. Mutable. */
+    lifetime: number;
+    /** Ribbon width (or the tile length under `widthCurve`). Mutable. */
+    width: number;
+    /** See `TrailOptions.minDistance`. Mutable. */
+    minDistance: number;
+    /** See `TrailFacing`. Mutable. */
+    facing: TrailFacing;
+    readonly widthCurve: Float32Array | null;
+    /** Linear RGBA; mutate in place. */
+    readonly color: Float32Array;
+    readonly colorCurve: Float32Array | null;
+    readonly fade: Float32Array | null;
+    readonly uvMode: 'stretch' | 'tile';
+    /** The mesh the ribbon is written into (3D vertex layout; two vertices per point). */
+    readonly mesh: Mesh;
+    /** The unlit soft-edged material (shared per renderer and blend unless textured). */
+    readonly material: Material;
+    /**
+     * Places the ribbon: identity by default (points are already in trail space). Parent it or
+     * move it like any `Transform`.
+     */
+    readonly transform: Transform;
+    /**
+     * Per-draw instance fields (`tint`, `emissive`, `order`, `layers`, ...); `params.x` is the
+     * edge softness and is owned by the trail (`softness`).
+     */
+    readonly instance: InstanceParams;
+    protected readonly params: Float32Array<ArrayBuffer>;
+    protected readonly ownsMaterial: boolean;
+    protected time: number;
+    /** Vertices the last `update` wrote. */
+    protected written: number;
+    private readonly vertexUpdate;
+    protected constructor(renderer: Renderer, opts: TrailOptions, vertices: number, indices: Uint16Array | Uint32Array | undefined, label: string);
+    /** Share of the half width that fades toward each long edge, 0..1. */
+    get softness(): number;
+    set softness(v: number);
+    /** Upload `count` vertices of `verts` and set the index range (allocation-free). */
+    protected upload(verts: Float32Array, count: number, indexCount: number): void;
+    /** Record the ribbon into `frame` (nothing when it has fewer than two points). */
+    draw(frame: Frame): void;
+    destroy(): void;
+}
+/**
+ * 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 declare class Trail extends RibbonBase {
+    readonly maxPoints: number;
+    private readonly ring;
+    private readonly verts;
+    constructor(renderer: Renderer, opts?: TrailOptions);
+    /** Points the ribbon currently has (stored points plus the tip when it sits apart). */
+    get count(): number;
+    /**
+     * Point `i` (0 = newest) into `out` as `x, y, z`. Out of range leaves `out` untouched and
+     * returns false.
+     */
+    pointAt(i: number, out: {
+        x: number;
+        y: number;
+        z: number;
+    }): boolean;
+    /**
+     * 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: number, y: number, z?: number): boolean;
+    /**
+     * 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: number, camera?: Camera | null): void;
+    /** Forget every point; the ribbon is empty until the next `push` and `update`. */
+    clear(): void;
+}
+/**
+ * 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 declare class TrailBatch extends RibbonBase {
+    /** Ribbons in the batch. */
+    readonly size: number;
+    readonly maxPoints: number;
+    private readonly rings;
+    private readonly verts;
+    private readonly indices;
+    private readonly indexUpdate;
+    constructor(renderer: Renderer, size: number, opts?: TrailOptions);
+    /** Points ribbon `i` currently has. */
+    count(i: number): number;
+    /** `Trail.pointAt` for ribbon `i`: point `j` (0 = newest) into `out`. */
+    pointAt(i: number, j: number, out: {
+        x: number;
+        y: number;
+        z: number;
+    }): boolean;
+    /** `Trail.push` for ribbon `i`. */
+    push(i: number, x: number, y: number, z?: number): boolean;
+    /** `Trail.update` for every ribbon, packed into one mesh. */
+    update(dt: number, camera?: Camera | null): void;
+    /** Forget ribbon `i`'s points, or every ribbon's without an index. */
+    clear(i?: number): void;
+}
+export {};