@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/core/scene.d.ts

@@ -0,0 +1,79 @@
+import type { Camera } from '../render/camera.js';
+/**
+ * Scene stack (C7 draft).
+ *
+ * - Only the top scene receives `update`.
+ * - `render(frame, camera, alpha)` hands scenes the camera the game draws with (`ctx.camera` in
+ *   `createGame`), so a scene never reaches for `renderer.camera`.
+ * - Rendering starts at the highest scene that is not `transparent` and goes up, so a
+ *   transparent scene (pause menu, modal) draws over the scene beneath it.
+ * - push/pop/replace called during `update` or `render` are deferred until that call returns,
+ *   so a scene can safely replace itself mid-update.
+ * - Covered scenes get `pause()` and `resume()` when they lose and regain the top.
+ * - Preload (ws/core-2): a pushed or replacing scene with `preload(ctx)` is awaited before it
+ *   enters; until then the stack is unchanged, so the old top keeps updating and rendering, and
+ *   `transitioning` is true. Later stack ops wait behind it, in order. `push` and `replace`
+ *   return a promise that resolves once the scene has entered (a scene without `preload` enters
+ *   at once, or when the current `update`/`render` returns, and its promise resolves on the next
+ *   microtask). A rejected `preload` rejects that promise and leaves the stack as it was.
+ * - `onTransition(fn)` reports `'preload'` (before `preload` starts), `'exit'` (after a scene's
+ *   `exit`, with the scene it gives way to) and `'enter'` (after a scene's `enter`, with the scene
+ *   it covered or replaced), so a game drives a loading screen or a fade from one hook.
+ */
+export interface Scene<Ctx = unknown, Frame = unknown, Cam = Camera> {
+    /** Debug name. */
+    readonly name?: string;
+    /** If true, the scene below keeps rendering underneath this one. */
+    readonly transparent?: boolean;
+    /**
+     * Load what the scene needs before it enters; awaited by `push`/`replace` while the previous
+     * top keeps running. A rejection cancels the push and leaves the stack unchanged.
+     */
+    preload?(ctx: Ctx): Promise<void>;
+    enter?(ctx: Ctx): void;
+    exit?(): void;
+    /** Another scene was pushed on top of this one. */
+    pause?(): void;
+    /** This scene became the top again. */
+    resume?(): void;
+    update?(dt: number): void;
+    /** Record this scene's draws into `frame` as seen by `camera`; `alpha` interpolates between fixed steps. */
+    render?(frame: Frame, camera: Cam, alpha: number): void;
+}
+export type TransitionPhase = 'preload' | 'enter' | 'exit';
+/** `from` is the scene leaving or being covered, `to` the one arriving or revealed (or undefined). */
+export type TransitionListener<Ctx = unknown, Frame = unknown, Cam = Camera> = (from: Scene<Ctx, Frame, Cam> | undefined, to: Scene<Ctx, Frame, Cam> | undefined, phase: TransitionPhase) => void;
+export declare class SceneStack<Ctx = unknown, Frame = unknown, Cam = Camera> {
+    private readonly ctx;
+    private readonly items;
+    private readonly pending;
+    private busy;
+    /** The op whose scene is preloading; the queue waits behind it. */
+    private loading;
+    private listeners;
+    constructor(ctx: Ctx);
+    get size(): number;
+    get top(): Scene<Ctx, Frame, Cam> | undefined;
+    /** True while a pushed or replacing scene's `preload` is pending. */
+    get transitioning(): boolean;
+    /** The scenes on the stack, bottom first: the live array (read it, copy it to keep it). */
+    get scenes(): readonly Scene<Ctx, Frame, Cam>[];
+    /** Push `scene` (after its `preload`, if any); resolves once it has entered. */
+    push(scene: Scene<Ctx, Frame, Cam>): Promise<void>;
+    pop(): void;
+    /** Replace the top with `scene` (after its `preload`, if any); resolves once it has entered. */
+    replace(scene: Scene<Ctx, Frame, Cam>): Promise<void>;
+    /** Exit every scene, top first. */
+    clear(): void;
+    /** Observe transitions; returns the unsubscribe function. Listeners are copy-on-write. */
+    onTransition(fn: TransitionListener<Ctx, Frame, Cam>): () => void;
+    update(dt: number): void;
+    /** Render every visible scene (highest opaque one upward) into `frame` through `camera`. */
+    render(frame: Frame, camera: Cam, alpha?: number): void;
+    private queueScene;
+    private queue;
+    private flush;
+    private startPreload;
+    private emit;
+    private apply;
+}

package/dist/core/scene.js

@@ -0,0 +1,195 @@
+const noop = () => { };
+export class SceneStack {
+    ctx;
+    items = [];
+    pending = [];
+    busy = 0;
+    /** The op whose scene is preloading; the queue waits behind it. */
+    loading = null;
+    listeners = [];
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    get size() {
+        return this.items.length;
+    }
+    get top() {
+        return this.items[this.items.length - 1];
+    }
+    /** True while a pushed or replacing scene's `preload` is pending. */
+    get transitioning() {
+        return this.loading !== null;
+    }
+    /** The scenes on the stack, bottom first: the live array (read it, copy it to keep it). */
+    get scenes() {
+        return this.items;
+    }
+    /** Push `scene` (after its `preload`, if any); resolves once it has entered. */
+    push(scene) {
+        return this.queueScene('push', scene);
+    }
+    pop() {
+        this.queue(bare('pop'));
+    }
+    /** Replace the top with `scene` (after its `preload`, if any); resolves once it has entered. */
+    replace(scene) {
+        return this.queueScene('replace', scene);
+    }
+    /** Exit every scene, top first. */
+    clear() {
+        this.queue(bare('clear'));
+    }
+    /** Observe transitions; returns the unsubscribe function. Listeners are copy-on-write. */
+    onTransition(fn) {
+        this.listeners = [...this.listeners, fn];
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== fn);
+        };
+    }
+    update(dt) {
+        const top = this.top;
+        if (!top?.update)
+            return;
+        this.busy++;
+        try {
+            top.update(dt);
+        }
+        finally {
+            this.busy--;
+            this.flush();
+        }
+    }
+    /** Render every visible scene (highest opaque one upward) into `frame` through `camera`. */
+    render(frame, camera, alpha = 0) {
+        const n = this.items.length;
+        if (n === 0)
+            return;
+        let start = n - 1;
+        while (start > 0 && this.items[start].transparent)
+            start--;
+        this.busy++;
+        try {
+            for (let i = start; i < n; i++)
+                this.items[i].render?.(frame, camera, alpha);
+        }
+        finally {
+            this.busy--;
+            this.flush();
+        }
+    }
+    queueScene(kind, scene) {
+        const op = {
+            kind,
+            scene,
+            loaded: false,
+            promise: null,
+            resolve: null,
+            reject: null,
+        };
+        op.promise = new Promise((resolve, reject) => {
+            op.resolve = resolve;
+            op.reject = reject;
+        });
+        // Outside the executor, so a throwing `enter` still throws out of `push`, as before.
+        this.queue(op);
+        return op.promise;
+    }
+    queue(op) {
+        this.pending.push(op);
+        if (this.busy === 0)
+            this.flush();
+    }
+    flush() {
+        while (this.busy === 0 && this.loading === null && this.pending.length > 0) {
+            const op = this.pending.shift();
+            const scene = op.scene;
+            if (!op.loaded && scene?.preload) {
+                this.startPreload(op, scene);
+                continue;
+            }
+            try {
+                this.apply(op);
+            }
+            catch (err) {
+                // The error throws out of the call that applied the op; the promise rejects too, marked
+                // handled so a caller that ignored it is not told twice.
+                op.promise?.catch(noop);
+                op.reject?.(err);
+                throw err;
+            }
+            op.resolve?.();
+        }
+    }
+    startPreload(op, scene) {
+        this.loading = op;
+        this.emit(this.top, scene, 'preload');
+        let p;
+        try {
+            p = Promise.resolve(scene.preload(this.ctx));
+        }
+        catch (err) {
+            p = Promise.reject(err);
+        }
+        p.then(() => {
+            this.loading = null;
+            op.loaded = true;
+            this.pending.unshift(op);
+            if (this.busy === 0)
+                this.flush();
+        }, (err) => {
+            this.loading = null;
+            op.reject?.(err);
+            if (this.busy === 0)
+                this.flush();
+        });
+    }
+    emit(from, to, phase) {
+        const ls = this.listeners;
+        for (let i = 0; i < ls.length; i++)
+            ls[i](from, to, phase);
+    }
+    apply(op) {
+        switch (op.kind) {
+            case 'push': {
+                const scene = op.scene;
+                const below = this.top;
+                below?.pause?.();
+                this.items.push(scene);
+                scene.enter?.(this.ctx);
+                this.emit(below, scene, 'enter');
+                break;
+            }
+            case 'pop': {
+                const s = this.items.pop();
+                s?.exit?.();
+                if (s) {
+                    this.top?.resume?.();
+                    this.emit(s, this.top, 'exit');
+                }
+                break;
+            }
+            case 'replace': {
+                const scene = op.scene;
+                const s = this.items.pop();
+                s?.exit?.();
+                if (s)
+                    this.emit(s, scene, 'exit');
+                this.items.push(scene);
+                scene.enter?.(this.ctx);
+                this.emit(s, scene, 'enter');
+                break;
+            }
+            case 'clear': {
+                while (this.items.length) {
+                    const s = this.items.pop();
+                    s.exit?.();
+                    this.emit(s, this.top, 'exit');
+                }
+                break;
+            }
+        }
+    }
+}
+function bare(kind) {
+    return { kind, scene: null, loaded: false, promise: null, resolve: null, reject: null };
+}

package/dist/core/timer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Delayed and repeating calls on the game's own clock (ws/core-2).
+ *
+ * The scheduler owns the bookkeeping, not time (the `tween` convention): it advances only when the
+ * game calls `update(dt)`, normally from a fixed step or a scene's `update`, so a paused loop, a
+ * replay or a test steps it exactly. A timer fires on the first `update` at which the scheduler's
+ * time reaches its due time (within 1e-9 s, so `after(1, fn)` under 60 steps of 1/60 fires on the
+ * 60th). Fires within one `update` run in due order (ties in scheduling order); an `every` that
+ * fell several periods behind in one long `dt` fires once per period, in order with the rest.
+ * A timer scheduled from inside a callback waits for the next `update`, even with 0 seconds.
+ *
+ * Handles are integers: a slot in a reused table plus a generation, so a stale handle (a timer
+ * that fired or was cancelled, its slot since reused) never touches the new occupant. The slot
+ * table and the heap grow to the peak number of live timers and are reused, and `update` creates
+ * no closures, so steady-state scheduling allocates nothing beyond the callbacks a game passes.
+ */
+/** A timer handle; 0 is never a live handle. */
+export type TimerHandle = number;
+export interface EveryOptions {
+    /** Fire this many times, then end. Default: until cancelled. */
+    count?: number;
+}
+export interface Cooldown {
+    readonly name: string;
+    /** Seconds a `use()` blocks for. */
+    readonly duration: number;
+    /** True when `use()` would succeed. */
+    readonly ready: boolean;
+    /** Seconds until ready, 0 when ready. */
+    readonly remaining: number;
+    /** 0 just used .. 1 ready (for a cooldown bar). */
+    readonly progress: number;
+    /** If ready, start the cooldown and return true; otherwise false. */
+    use(): boolean;
+    /** Ready now. */
+    reset(): void;
+}
+export interface Scheduler {
+    /** Seconds this scheduler has advanced (paused updates do not count). */
+    readonly time: number;
+    /** Live timers (cooldowns not counted). */
+    readonly active: number;
+    readonly paused: boolean;
+    /** Call `fn` once after `seconds`. */
+    after(seconds: number, fn: () => void): TimerHandle;
+    /** Call `fn` every `seconds` (the first after one period); `count` ends it after that many. */
+    every(seconds: number, fn: () => void, opts?: EveryOptions): TimerHandle;
+    /**
+     * The cooldown called `name`, created ready on first use; later calls return the same object
+     * (and set its duration to `seconds`), so calling it per frame allocates nothing.
+     */
+    cooldown(name: string, seconds: number): Cooldown;
+    /** Seconds until `handle` fires next, or -1 when it is not live. */
+    remaining(handle: TimerHandle): number;
+    /** Stop a timer; false when the handle is not live. Safe from inside a callback. */
+    cancel(handle: TimerHandle): boolean;
+    /** Advance by `dt` seconds and fire what is due. Does nothing while paused. */
+    update(dt: number): void;
+    /** Cancel every timer and make every cooldown ready. */
+    clear(): void;
+    /** Hold every timer and cooldown where it is until `resume()`. */
+    pause(): void;
+    resume(): void;
+}
+/** A scheduler on the caller's clock; see the module comment. */
+export declare function createScheduler(): Scheduler;

package/dist/core/timer.js

@@ -0,0 +1,286 @@
+/**
+ * Delayed and repeating calls on the game's own clock (ws/core-2).
+ *
+ * The scheduler owns the bookkeeping, not time (the `tween` convention): it advances only when the
+ * game calls `update(dt)`, normally from a fixed step or a scene's `update`, so a paused loop, a
+ * replay or a test steps it exactly. A timer fires on the first `update` at which the scheduler's
+ * time reaches its due time (within 1e-9 s, so `after(1, fn)` under 60 steps of 1/60 fires on the
+ * 60th). Fires within one `update` run in due order (ties in scheduling order); an `every` that
+ * fell several periods behind in one long `dt` fires once per period, in order with the rest.
+ * A timer scheduled from inside a callback waits for the next `update`, even with 0 seconds.
+ *
+ * Handles are integers: a slot in a reused table plus a generation, so a stale handle (a timer
+ * that fired or was cancelled, its slot since reused) never touches the new occupant. The slot
+ * table and the heap grow to the peak number of live timers and are reused, and `update` creates
+ * no closures, so steady-state scheduling allocates nothing beyond the callbacks a game passes.
+ */
+const EPS = 1e-9;
+const SLOT_BITS = 2 ** 20;
+class CooldownImpl {
+    name;
+    duration;
+    left = 0;
+    constructor(name, duration) {
+        this.name = name;
+        this.duration = duration;
+    }
+    get ready() {
+        return this.left <= EPS;
+    }
+    get remaining() {
+        return this.left <= EPS ? 0 : this.left;
+    }
+    get progress() {
+        if (this.duration <= 0 || this.left <= EPS)
+            return 1;
+        return 1 - this.left / this.duration;
+    }
+    use() {
+        if (this.left > EPS)
+            return false;
+        this.left = this.duration;
+        return true;
+    }
+    reset() {
+        this.left = 0;
+    }
+}
+class SchedulerImpl {
+    now = 0;
+    seq = 0;
+    isPaused = false;
+    updating = false;
+    live = 0;
+    entries = [];
+    free = [];
+    /** Min-heap of slot indices by (due, seq). */
+    heap = [];
+    /** Slots scheduled during `update`, joined to the heap when it returns. */
+    incoming = [];
+    cooldowns = new Map();
+    cooldownList = [];
+    get time() {
+        return this.now;
+    }
+    get active() {
+        return this.live;
+    }
+    get paused() {
+        return this.isPaused;
+    }
+    after(seconds, fn) {
+        return this.add(seconds, 0, 1, fn);
+    }
+    every(seconds, fn, opts) {
+        const count = opts?.count ?? Number.POSITIVE_INFINITY;
+        if (!(count >= 1))
+            return 0;
+        const s = Math.max(0, seconds);
+        return this.add(s, s, Math.floor(count), fn);
+    }
+    cooldown(name, seconds) {
+        let c = this.cooldowns.get(name);
+        if (!c) {
+            c = new CooldownImpl(name, Math.max(0, seconds));
+            this.cooldowns.set(name, c);
+            this.cooldownList.push(c);
+        }
+        else
+            c.duration = Math.max(0, seconds);
+        return c;
+    }
+    remaining(handle) {
+        const e = this.lookup(handle);
+        return e ? Math.max(0, e.due - this.now) : -1;
+    }
+    cancel(handle) {
+        const e = this.lookup(handle);
+        if (!e)
+            return false;
+        e.live = false;
+        e.fn = null;
+        this.live--;
+        // In the heap: out now. Otherwise it waits in `incoming`, which frees it when the update ends.
+        if (e.heapIndex >= 0) {
+            this.heapRemove(e.heapIndex);
+            e.heapIndex = -1;
+            this.release(handle % SLOT_BITS);
+        }
+        return true;
+    }
+    update(dt) {
+        if (this.isPaused || !(dt > 0))
+            return;
+        this.now += dt;
+        const cds = this.cooldownList;
+        for (let i = 0; i < cds.length; i++) {
+            const c = cds[i];
+            if (c.left > 0)
+                c.left = Math.max(0, c.left - dt);
+        }
+        this.updating = true;
+        try {
+            const heap = this.heap;
+            const limit = this.now + EPS;
+            while (heap.length > 0) {
+                const slot = heap[0];
+                const e = this.entries[slot];
+                if (e.due > limit)
+                    break;
+                this.heapRemove(0);
+                e.heapIndex = -1;
+                const fn = e.fn;
+                e.left--;
+                const repeat = e.left > 0;
+                if (repeat) {
+                    e.due += e.interval;
+                    e.seq = this.seq++;
+                    // A zero period fires once per update; otherwise catch up within this one.
+                    if (e.interval > 0)
+                        this.heapPush(slot);
+                    else
+                        this.incoming.push(slot);
+                }
+                else {
+                    e.live = false;
+                    e.fn = null;
+                    this.live--;
+                    // Its handle is stale from here (a reuse bumps the generation), so `fn` may reuse it.
+                    this.release(slot);
+                }
+                fn();
+            }
+        }
+        finally {
+            this.updating = false;
+            this.joinIncoming();
+        }
+    }
+    clear() {
+        for (let i = 0; i < this.entries.length; i++) {
+            const e = this.entries[i];
+            if (e.live)
+                this.cancel(e.gen * SLOT_BITS + i);
+        }
+        for (let i = 0; i < this.cooldownList.length; i++)
+            this.cooldownList[i].reset();
+    }
+    pause() {
+        this.isPaused = true;
+    }
+    resume() {
+        this.isPaused = false;
+    }
+    // ── internals ─────────────────────────────────────────────────────────────
+    add(seconds, interval, left, fn) {
+        let slot = this.free.pop();
+        if (slot === undefined) {
+            slot = this.entries.length;
+            if (slot >= SLOT_BITS)
+                throw new RangeError('Scheduler: too many live timers');
+            this.entries.push({
+                gen: 0,
+                live: false,
+                due: 0,
+                interval: 0,
+                left: 0,
+                fn: null,
+                seq: 0,
+                heapIndex: -1,
+            });
+        }
+        const e = this.entries[slot];
+        e.gen++;
+        e.live = true;
+        e.due = this.now + Math.max(0, seconds);
+        e.interval = interval;
+        e.left = left;
+        e.fn = fn;
+        e.seq = this.seq++;
+        e.heapIndex = -1;
+        this.live++;
+        if (this.updating)
+            this.incoming.push(slot);
+        else
+            this.heapPush(slot);
+        return e.gen * SLOT_BITS + slot;
+    }
+    lookup(handle) {
+        if (!Number.isInteger(handle) || handle <= 0)
+            return null;
+        const slot = handle % SLOT_BITS;
+        const e = this.entries[slot];
+        if (!e?.live || e.gen !== Math.floor(handle / SLOT_BITS))
+            return null;
+        return e;
+    }
+    release(slot) {
+        this.free.push(slot);
+    }
+    joinIncoming() {
+        const inc = this.incoming;
+        for (let i = 0; i < inc.length; i++) {
+            const slot = inc[i];
+            if (this.entries[slot].live)
+                this.heapPush(slot);
+            else
+                this.release(slot);
+        }
+        inc.length = 0;
+    }
+    less(a, b) {
+        const ea = this.entries[a];
+        const eb = this.entries[b];
+        return ea.due < eb.due || (ea.due === eb.due && ea.seq < eb.seq);
+    }
+    place(i, slot) {
+        this.heap[i] = slot;
+        this.entries[slot].heapIndex = i;
+    }
+    heapPush(slot) {
+        this.heap.push(slot);
+        this.siftUp(this.heap.length - 1);
+    }
+    heapRemove(i) {
+        const heap = this.heap;
+        const last = heap.pop();
+        if (i < heap.length) {
+            this.place(i, last);
+            this.siftDown(i);
+            this.siftUp(this.entries[last].heapIndex);
+        }
+    }
+    siftUp(i) {
+        const heap = this.heap;
+        const slot = heap[i];
+        while (i > 0) {
+            const p = (i - 1) >> 1;
+            if (!this.less(slot, heap[p]))
+                break;
+            this.place(i, heap[p]);
+            i = p;
+        }
+        this.place(i, slot);
+    }
+    siftDown(i) {
+        const heap = this.heap;
+        const n = heap.length;
+        const slot = heap[i];
+        for (;;) {
+            const l = 2 * i + 1;
+            if (l >= n)
+                break;
+            const r = l + 1;
+            const c = r < n && this.less(heap[r], heap[l]) ? r : l;
+            if (!this.less(heap[c], slot))
+                break;
+            this.place(i, heap[c]);
+            i = c;
+        }
+        this.place(i, slot);
+    }
+}
+/** A scheduler on the caller's clock; see the module comment. */
+export function createScheduler() {
+    return new SchedulerImpl();
+}

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

@@ -0,0 +1,29 @@
+/** Floats per billboard instance in the storage buffer (`BILLBOARD_BYTES` / 4). */
+export declare const BILLBOARD_FLOATS = 20;
+export declare const BILLBOARD_BYTES: number;
+/** Instance flag bits, in `pos.w` as a float. */
+export declare const BB_FLAG_PX = 1;
+export declare const BB_FLAG_YAW = 2;
+export declare const BB_FLAG_TEXTURED = 4;
+export declare const BB_FLAG_BAR = 8;
+/**
+ * The billboard batch's shader: six vertices per instance, read from a storage buffer.
+ *
+ * - `pos.xyz` is the world anchor (position plus offset); `pos.w` carries the flags above.
+ * - `size.xy` is the quad size: world units, or logical px with `BB_FLAG_PX` (then the quad is
+ *   screen-aligned and sized from `globals.logicalSize`, `globals.targetSize` and the view's
+ *   `camera.viewport`, so it keeps its px size at any distance). `size.z` is the bar fraction.
+ * - World-unit quads face the camera (`camera.view` rows 0 and 1), or turn only about y with
+ *   `BB_FLAG_YAW` (right = the view's right flattened onto xz, up = +y).
+ * - `color` multiplies the atlas sample (`BB_FLAG_TEXTURED`) or stands alone; with `BB_FLAG_BAR`
+ *   the fragment is `color` where `uv.x < size.z` and `color2` beyond.
+ */
+export declare const BILLBOARD_WGSL = "\n\nstruct EngineGlobals {\n  logicalSize: vec2f,\n  targetSize: vec2f,\n  time: f32,\n  dt: f32,\n  _pad: vec2f,\n};\n@group(0) @binding(0) var<uniform> globals: EngineGlobals;\nstruct EngineCamera {\n  view: mat4x4f,\n  proj: mat4x4f,\n  view_proj: mat4x4f,\n  camera_pos: vec4f,\n  viewport: vec4f,\n  view_index: u32,\n  _pad0: u32, _pad1: u32, _pad2: u32,\n  inv_view_proj: mat4x4f,\n  prev_view_proj: mat4x4f,\n  prev_view: mat4x4f,\n  jitter: vec4f,\n};\n@group(0) @binding(1) var<uniform> camera: EngineCamera;\n\nstruct Billboard {\n  pos: vec4f,\n  size: vec4f,\n  uv: vec4f,\n  color: vec4f,\n  color2: vec4f,\n};\n@group(1) @binding(0) var<storage, read> billboards: array<Billboard>;\n@group(1) @binding(1) var atlas_sampler: sampler;\n@group(1) @binding(2) var atlas: texture_2d<f32>;\n\nstruct VSOut {\n  @builtin(position) clip: vec4f,\n  @location(0) uv: vec2f,\n  @location(1) q: vec2f,\n  @location(2) color: vec4f,\n  @location(3) color2: vec4f,\n  @location(4) @interpolate(flat) flags: u32,\n  @location(5) fraction: f32,\n};\nstruct FragOut {\n  @location(0) color: vec4f,\n  @location(1) emissive: vec4f,\n};\n\nfn view_row(r: u32) -> vec3f {\n  return vec3f(camera.view[0][r], camera.view[1][r], camera.view[2][r]);\n}\n\n@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {\n  var o: VSOut;\n  let b = billboards[ii];\n  var corners = array<vec2f, 6>(\n    vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),\n    vec2f(-1.0, -1.0), vec2f(1.0, 1.0), vec2f(-1.0, 1.0)\n  );\n  let q = corners[vi];\n  let flags = u32(b.pos.w + 0.5);\n  let half = b.size.xy * 0.5;\n  if ((flags & 1u) != 0u) {\n    var clip = camera.view_proj * vec4f(b.pos.xyz, 1.0);\n    // Logical px \u2192 target px \u2192 NDC, scaled by w so the division leaves the px size intact.\n    let px_per_logical = globals.targetSize / globals.logicalSize;\n    let ndc = (q * half * px_per_logical) / max(camera.viewport.zw, vec2f(1.0)) * 2.0;\n    clip = vec4f(clip.xy + ndc * clip.w, clip.zw);\n    o.clip = clip;\n  } else {\n    var right = view_row(0u);\n    var up = view_row(1u);\n    if ((flags & 2u) != 0u) {\n      let flat = vec3f(right.x, 0.0, right.z);\n      let len = length(flat);\n      right = select(vec3f(1.0, 0.0, 0.0), flat / max(len, 1e-6), len > 1e-6);\n      up = vec3f(0.0, 1.0, 0.0);\n    }\n    let world = b.pos.xyz + right * (q.x * half.x) + up * (q.y * half.y);\n    o.clip = camera.view_proj * vec4f(world, 1.0);\n  }\n  // Canvas uv: v grows downward, so the top of the quad (q.y = 1) samples v0.\n  let t = q * 0.5 + 0.5;\n  o.uv = vec2f(mix(b.uv.x, b.uv.z, t.x), mix(b.uv.w, b.uv.y, t.y));\n  o.q = t;\n  o.color = b.color;\n  o.color2 = b.color2;\n  o.flags = flags;\n  o.fraction = b.size.z;\n  return o;\n}\n\n@fragment fn fs(in: VSOut) -> FragOut {\n  var c = in.color;\n  if ((in.flags & 8u) != 0u) {\n    c = select(in.color2, in.color, in.q.x < in.fraction);\n  }\n  // Sampled unconditionally: textureSample needs uniform control flow.\n  let s = textureSample(atlas, atlas_sampler, in.uv);\n  c *= select(vec4f(1.0), s, (in.flags & 4u) != 0u);\n  var o: FragOut;\n  o.color = c;\n  o.emissive = vec4f(0.0, 0.0, 0.0, c.a);\n  return o;\n}\n";
+/**
+ * `BILLBOARD_WGSL`, or with `velocity` (the velocity attachment's fragment location, 2 or 3)
+ * the build that writes its own motion (ws/render-11): binding 3 holds each sorted instance's
+ * previous anchor (`xyz`, `w` = 1 when known), the vertex stage projects the same corner of
+ * last frame's quad through `camera.prev_view_proj` / `prev_view`, and the fragment writes
+ * `vec4f(engine_motion(..), 0, alpha)` there. Internal; `0` is the exported string itself.
+ */
+export declare function billboardWgsl(velocity: number): string;