@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/effect.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Effects (ws/fx-3): a data-driven bundle of particle systems and emitters, played as
+ * instances at a point or attached to a moving one. A descriptor is plain JSON (textures by
+ * name), so an effect loads through the asset manifest as `{ kind: 'json', uri }` and is
+ * validated with `validateEffectDesc` before `createEffect`.
+ */
+import type { Random } from '../core/random.js';
+import type { Frame } from '../render/frame.js';
+import type { Renderer } from '../render/renderer.js';
+import type { TextureLike } from '../render/texture.js';
+import { type EmitParams, ParticleSystem, type ParticleSystemOptions } from './particles.js';
+/** One emitter of an effect system: continuous at `rate`, a `burst` at `delay`, or both. */
+export interface EffectEmitterDesc {
+    params: EmitParams;
+    /** Particles per second while active. Default 0. */
+    rate?: number;
+    /** Seconds after `delay` the emitter stays active. Default: until the effect ends. */
+    duration?: number;
+    /** Seconds after the instance starts before this emitter begins. Default 0. */
+    delay?: number;
+    /** Particles emitted once at `delay`. Default 0. */
+    burst?: number;
+}
+/** A system's options in a descriptor: textures by name, no scene-target references. */
+export type EffectSystemOptions = Omit<ParticleSystemOptions, 'texture' | 'depthTarget' | 'random'> & {
+    /** A key of the `textures` map given to `createEffect`. */
+    texture?: string;
+};
+export interface EffectSystemDesc {
+    name: string;
+    options?: EffectSystemOptions;
+    emitters: EffectEmitterDesc[];
+}
+export interface EffectDesc {
+    systems: EffectSystemDesc[];
+    /** Seconds an instance lives. Default: when the last emitter ends (forever if none ends). */
+    duration?: number;
+    /** Restart each instance at `duration` instead of finishing it. Default false. */
+    loop?: boolean;
+}
+/** Where an instance plays: a point, moved by `attach`. */
+export interface EffectPoint {
+    x: number;
+    y: number;
+    z?: number;
+}
+/** Fills `out` (xyz) with where an attached instance should be this frame. */
+export type EffectFollow = (out: Float32Array) => void;
+/**
+ * Check a parsed effect JSON. Returns the problems found, each with its path (empty = valid).
+ * With `textures` (names, or the map `createEffect` will get) unknown texture names are errors.
+ */
+export declare function validateEffectDesc(json: unknown, opts?: {
+    textures?: readonly string[] | Record<string, TextureLike>;
+}): string[];
+/** An emitter's per-instance state. */
+interface EmitterState {
+    /** This instance's copy of the params (position overwritten each frame). */
+    params: EmitParams;
+    carry: number;
+    fired: boolean;
+}
+/** One playing of an effect: at a point, or following `attach`. */
+export declare class EffectInstance {
+    /** World (or logical) position, xyz. */
+    readonly position: Float32Array<ArrayBuffer>;
+    /** Seconds since it started (wraps when the effect loops). */
+    time: number;
+    /** Set once it has finished emitting (or `stop()` was called); the effect drops it then. */
+    done: boolean;
+    /** @internal */
+    follow: EffectFollow | null;
+    /** @internal per system, per emitter. */
+    readonly states: EmitterState[][];
+    /** Keep the instance at wherever `getPosition` says each update. */
+    attach(getPosition: EffectFollow): this;
+    /** Stop emitting; the particles already born die on their own. */
+    stop(): void;
+}
+/**
+ * A playable effect built from an `EffectDesc`: its systems are created once; each `play` or
+ * `attach` adds an instance that drives the emitters. Call `update(dt)` once a frame, then
+ * `draw(frame)` to queue every system.
+ */
+export declare class Effect {
+    readonly systems: ParticleSystem[];
+    /** The instances now playing. */
+    readonly instances: EffectInstance[];
+    /** Seconds an instance lives (Infinity: until stopped). */
+    readonly duration: number;
+    readonly loop: boolean;
+    /**
+     * The effect's stream (ws/fx-4): system `name` draws from `random.fork(name)`, so the same
+     * seed plays the same particles whatever else the game draws.
+     */
+    readonly random: Random;
+    private readonly desc;
+    private readonly pool;
+    constructor(renderer: Renderer, desc: EffectDesc, textures?: Record<string, TextureLike>, random?: Random);
+    /** Start an instance at `at` (default the origin). */
+    play(at?: EffectPoint): EffectInstance;
+    /** Start an instance that follows `getPosition`. */
+    attach(getPosition: EffectFollow): EffectInstance;
+    /** Stop every instance (particles already born die on their own). */
+    stop(): void;
+    /** Drive the instances' emitters and the systems. Call once per frame. */
+    update(dt: number): void;
+    private emitFor;
+    /** Queue every system for drawing (`frame.drawable`). */
+    draw(frame: Frame, order?: number): void;
+    destroy(): void;
+    private makeInstance;
+}
+/** `createEffect` options. */
+export interface CreateEffectOptions {
+    /** Texture names the descriptor's systems refer to. */
+    textures?: Record<string, TextureLike>;
+    /**
+     * The effect's random stream (ws/fx-4; each system forks it by name). Default: a fork of the
+     * fx module default (`FX_DEFAULT_SEED`), named by creation order.
+     */
+    random?: Random;
+}
+/**
+ * Build an `Effect` from a descriptor, resolving texture names through `textures`. Throws a
+ * readable `Error` listing every problem `validateEffectDesc` finds.
+ */
+export declare function createEffect(renderer: Renderer, desc: EffectDesc, opts?: CreateEffectOptions): Effect;
+export {};

package/dist/fx/effect.js

@@ -0,0 +1,349 @@
+import { MAX_CURVE_STOPS, ParticleSystem, } from './particles.js';
+import { defaultFxRandom } from './random.js';
+const NUMBER_FIELDS = ['rate', 'duration', 'delay', 'burst'];
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isColor(v) {
+    return (Array.isArray(v) &&
+        v.length >= 3 &&
+        v.length <= 4 &&
+        v.every((n) => typeof n === 'number' && Number.isFinite(n)));
+}
+function isPair(v) {
+    return Array.isArray(v) && v.length === 2 && v.every((n) => typeof n === 'number');
+}
+function validateParams(p, at, textures, out, depth) {
+    if (!isRecord(p)) {
+        out.push(`${at}: params must be an object`);
+        return;
+    }
+    if (typeof p.x !== 'number' || typeof p.y !== 'number')
+        out.push(`${at}: x and y must be numbers`);
+    if (!isColor(p.colorStart))
+        out.push(`${at}: colorStart must be [r, g, b] or [r, g, b, a]`);
+    if (p.colorEnd !== undefined && !isColor(p.colorEnd))
+        out.push(`${at}: colorEnd must be a colour`);
+    for (const k of ['speed', 'life', 'size', 'rotation', 'spin']) {
+        if (p[k] !== undefined && !isPair(p[k]))
+            out.push(`${at}: ${k} must be [min, max]`);
+    }
+    if (p.sizeCurve !== undefined) {
+        const c = p.sizeCurve;
+        if (!Array.isArray(c) || c.length < 2 || c.length > MAX_CURVE_STOPS) {
+            out.push(`${at}: sizeCurve needs 2..${MAX_CURVE_STOPS} stops`);
+        }
+        else if (!c.every((n) => typeof n === 'number'))
+            out.push(`${at}: sizeCurve stops must be numbers`);
+    }
+    if (p.colorCurve !== undefined) {
+        const c = p.colorCurve;
+        if (!Array.isArray(c) || c.length < 2 || c.length > MAX_CURVE_STOPS) {
+            out.push(`${at}: colorCurve needs 2..${MAX_CURVE_STOPS} stops`);
+        }
+        else if (!c.every(isColor))
+            out.push(`${at}: colorCurve stops must be colours`);
+    }
+    if (p.tile !== undefined && typeof p.tile !== 'number' && !isPair(p.tile)) {
+        out.push(`${at}: tile must be a number or [from, to]`);
+    }
+    if (p.shape !== undefined) {
+        const s = p.shape;
+        if (!isRecord(s) || typeof s.kind !== 'string')
+            out.push(`${at}: shape needs a kind`);
+        else if (s.kind === 'mesh' && !Array.isArray(s.positions)) {
+            out.push(`${at}: a mesh shape needs positions`);
+        }
+    }
+    for (const k of ['onDeath', 'onLife']) {
+        const sub = p[k];
+        if (sub === undefined)
+            continue;
+        if (!isRecord(sub)) {
+            out.push(`${at}.${k}: must be { params, ${k === 'onDeath' ? 'count' : 'rate'} }`);
+            continue;
+        }
+        const amount = k === 'onDeath' ? sub.count : sub.rate;
+        if (typeof amount !== 'number' || amount < 0) {
+            out.push(`${at}.${k}: ${k === 'onDeath' ? 'count' : 'rate'} must be a number ≥ 0`);
+        }
+        if (depth > 0)
+            out.push(`${at}.${k}: sub-emitters go one level deep`);
+        else
+            validateParams(sub.params, `${at}.${k}`, textures, out, depth + 1);
+    }
+}
+/**
+ * Check a parsed effect JSON. Returns the problems found, each with its path (empty = valid).
+ * With `textures` (names, or the map `createEffect` will get) unknown texture names are errors.
+ */
+export function validateEffectDesc(json, opts = {}) {
+    const out = [];
+    const textures = opts.textures
+        ? Array.isArray(opts.textures)
+            ? opts.textures
+            : Object.keys(opts.textures)
+        : null;
+    if (!isRecord(json))
+        return ['effect: must be an object'];
+    if (json.duration !== undefined && !(typeof json.duration === 'number' && json.duration > 0)) {
+        out.push('effect: duration must be a number > 0');
+    }
+    if (json.loop !== undefined && typeof json.loop !== 'boolean')
+        out.push('effect: loop must be a boolean');
+    if (!Array.isArray(json.systems) || json.systems.length === 0) {
+        out.push('effect: systems must be a non-empty array');
+        return out;
+    }
+    const names = new Set();
+    json.systems.forEach((sys, i) => {
+        const at = `systems[${i}]`;
+        if (!isRecord(sys)) {
+            out.push(`${at}: must be an object`);
+            return;
+        }
+        if (typeof sys.name !== 'string' || sys.name === '')
+            out.push(`${at}: name must be a string`);
+        else if (names.has(sys.name))
+            out.push(`${at}: duplicate name "${sys.name}"`);
+        else
+            names.add(sys.name);
+        if (sys.options !== undefined) {
+            const o = sys.options;
+            if (!isRecord(o))
+                out.push(`${at}.options: must be an object`);
+            else {
+                if (o.space !== undefined && o.space !== '2d' && o.space !== 'world') {
+                    out.push(`${at}.options: space must be '2d' or 'world'`);
+                }
+                if (o.blend !== undefined && o.blend !== 'additive' && o.blend !== 'alpha') {
+                    out.push(`${at}.options: blend must be 'additive' or 'alpha'`);
+                }
+                if (o.texture !== undefined) {
+                    if (typeof o.texture !== 'string')
+                        out.push(`${at}.options: texture must be a name`);
+                    else if (textures && !textures.includes(o.texture)) {
+                        out.push(`${at}.options: unknown texture "${o.texture}"`);
+                    }
+                }
+                if (o.atlas !== undefined) {
+                    const a = o.atlas;
+                    if (!isRecord(a) || typeof a.columns !== 'number' || typeof a.rows !== 'number') {
+                        out.push(`${at}.options: atlas must be { columns, rows }`);
+                    }
+                }
+                if (o.depthTarget !== undefined)
+                    out.push(`${at}.options: depthTarget is not serialisable`);
+            }
+        }
+        if (!Array.isArray(sys.emitters) || sys.emitters.length === 0) {
+            out.push(`${at}: emitters must be a non-empty array`);
+            return;
+        }
+        sys.emitters.forEach((em, j) => {
+            const ea = `${at}.emitters[${j}]`;
+            if (!isRecord(em)) {
+                out.push(`${ea}: must be an object`);
+                return;
+            }
+            for (const k of NUMBER_FIELDS) {
+                const v = em[k];
+                if (v !== undefined && !(typeof v === 'number' && Number.isFinite(v) && v >= 0)) {
+                    out.push(`${ea}: ${k} must be a number ≥ 0`);
+                }
+            }
+            if (!em.rate && !em.burst)
+                out.push(`${ea}: needs a rate or a burst`);
+            validateParams(em.params, ea, textures, out, 0);
+        });
+    });
+    return out;
+}
+/** One playing of an effect: at a point, or following `attach`. */
+export class EffectInstance {
+    /** World (or logical) position, xyz. */
+    position = new Float32Array(3);
+    /** Seconds since it started (wraps when the effect loops). */
+    time = 0;
+    /** Set once it has finished emitting (or `stop()` was called); the effect drops it then. */
+    done = false;
+    /** @internal */
+    follow = null;
+    /** @internal per system, per emitter. */
+    states = [];
+    /** Keep the instance at wherever `getPosition` says each update. */
+    attach(getPosition) {
+        this.follow = getPosition;
+        return this;
+    }
+    /** Stop emitting; the particles already born die on their own. */
+    stop() {
+        this.done = true;
+    }
+}
+/**
+ * A playable effect built from an `EffectDesc`: its systems are created once; each `play` or
+ * `attach` adds an instance that drives the emitters. Call `update(dt)` once a frame, then
+ * `draw(frame)` to queue every system.
+ */
+export class Effect {
+    systems = [];
+    /** The instances now playing. */
+    instances = [];
+    /** Seconds an instance lives (Infinity: until stopped). */
+    duration;
+    loop;
+    /**
+     * The effect's stream (ws/fx-4): system `name` draws from `random.fork(name)`, so the same
+     * seed plays the same particles whatever else the game draws.
+     */
+    random;
+    desc;
+    pool = [];
+    constructor(renderer, desc, textures = {}, random) {
+        const problems = validateEffectDesc(desc, { textures });
+        if (problems.length)
+            throw new Error(`createEffect: ${problems.join('; ')}`);
+        this.desc = desc;
+        this.loop = desc.loop ?? false;
+        this.random = random ?? defaultFxRandom('effect');
+        let end = 0;
+        for (const sys of desc.systems) {
+            const { texture, ...rest } = sys.options ?? {};
+            const options = {
+                ...rest,
+                extended: true,
+                random: this.random.fork(sys.name),
+            };
+            if (texture)
+                options.texture = textures[texture];
+            this.systems.push(new ParticleSystem(renderer, options));
+            for (const em of sys.emitters) {
+                const emEnd = em.duration === undefined ? Infinity : (em.delay ?? 0) + em.duration;
+                if (emEnd > end)
+                    end = emEnd;
+            }
+        }
+        this.duration = desc.duration ?? (end > 0 ? end : Infinity);
+    }
+    /** Start an instance at `at` (default the origin). */
+    play(at) {
+        const inst = this.pool.pop() ?? this.makeInstance();
+        inst.time = 0;
+        inst.done = false;
+        inst.follow = null;
+        inst.position[0] = at?.x ?? 0;
+        inst.position[1] = at?.y ?? 0;
+        inst.position[2] = at?.z ?? 0;
+        for (const states of inst.states) {
+            for (const s of states) {
+                s.carry = 0;
+                s.fired = false;
+            }
+        }
+        this.instances.push(inst);
+        return inst;
+    }
+    /** Start an instance that follows `getPosition`. */
+    attach(getPosition) {
+        const inst = this.play();
+        inst.follow = getPosition;
+        getPosition(inst.position);
+        return inst;
+    }
+    /** Stop every instance (particles already born die on their own). */
+    stop() {
+        for (const inst of this.instances)
+            inst.done = true;
+    }
+    /** Drive the instances' emitters and the systems. Call once per frame. */
+    update(dt) {
+        const instances = this.instances;
+        for (let i = instances.length - 1; i >= 0; i--) {
+            const inst = instances[i];
+            if (inst.done) {
+                instances[i] = instances[instances.length - 1];
+                instances.pop();
+                this.pool.push(inst);
+                continue;
+            }
+            if (inst.follow)
+                inst.follow(inst.position);
+            const t0 = inst.time;
+            inst.time += dt;
+            this.emitFor(inst, t0, inst.time);
+            if (inst.time >= this.duration) {
+                if (this.loop) {
+                    inst.time -= this.duration;
+                    for (const states of inst.states)
+                        for (const s of states)
+                            s.fired = false;
+                }
+                else {
+                    inst.done = true;
+                }
+            }
+        }
+        for (const sys of this.systems)
+            sys.update(dt);
+    }
+    emitFor(inst, t0, t1) {
+        const x = inst.position[0];
+        const y = inst.position[1];
+        const z = inst.position[2];
+        const descs = this.desc.systems;
+        for (let si = 0; si < descs.length; si++) {
+            const sys = descs[si];
+            const system = this.systems[si];
+            const states = inst.states[si];
+            for (let ei = 0; ei < sys.emitters.length; ei++) {
+                const em = sys.emitters[ei];
+                const st = states[ei];
+                const delay = em.delay ?? 0;
+                const end = em.duration === undefined ? Infinity : delay + em.duration;
+                const p = st.params;
+                p.x = x + (em.params.x ?? 0);
+                p.y = y + (em.params.y ?? 0);
+                p.z = z + (em.params.z ?? 0);
+                if (!st.fired && t1 >= delay) {
+                    st.fired = true;
+                    if (em.burst)
+                        system.emit(p, em.burst);
+                }
+                if (em.rate && t1 > delay && t0 < end) {
+                    const active = Math.min(t1, end) - Math.max(t0, delay);
+                    st.carry += em.rate * active;
+                    const n = Math.floor(st.carry);
+                    if (n > 0) {
+                        st.carry -= n;
+                        system.emit(p, n);
+                    }
+                }
+            }
+        }
+    }
+    /** Queue every system for drawing (`frame.drawable`). */
+    draw(frame, order = 0) {
+        for (const sys of this.systems)
+            frame.drawable(sys, order);
+    }
+    destroy() {
+        for (const sys of this.systems)
+            sys.destroy();
+        this.instances.length = 0;
+    }
+    makeInstance() {
+        const inst = new EffectInstance();
+        for (const sys of this.desc.systems) {
+            inst.states.push(sys.emitters.map((em) => ({ params: { ...em.params }, carry: 0, fired: false })));
+        }
+        return inst;
+    }
+}
+/**
+ * Build an `Effect` from a descriptor, resolving texture names through `textures`. Throws a
+ * readable `Error` listing every problem `validateEffectDesc` finds.
+ */
+export function createEffect(renderer, desc, opts = {}) {
+    return new Effect(renderer, desc, opts.textures ?? {}, opts.random);
+}

package/dist/fx/effects/hit-spark.json

@@ -0,0 +1,48 @@
+{
+    "duration": 0.4,
+    "systems": [
+        {
+            "name": "sparks",
+            "options": { "space": "2d", "blend": "additive", "stretch": 0.03 },
+            "emitters": [
+                {
+                    "burst": 40,
+                    "params": {
+                        "x": 0,
+                        "y": 0,
+                        "speed": [200, 600],
+                        "life": [0.2, 0.45],
+                        "sizeCurve": [5, 3, 0],
+                        "colorCurve": [[4, 3.2, 1.6, 1], [3, 1, 0.2, 1], [1, 0.2, 0.05, 0]],
+                        "gravity": [0, 900],
+                        "drag": 2,
+                        "emissive": 2,
+                        "colorStart": [4, 3.2, 1.6, 1]
+                    }
+                }
+            ]
+        },
+        {
+            "name": "flash",
+            "options": { "space": "2d", "blend": "additive", "stretch": 0 },
+            "emitters": [
+                {
+                    "burst": 1,
+                    "params": {
+                        "x": 0,
+                        "y": 0,
+                        "speed": [0, 0],
+                        "life": [0.12, 0.12],
+                        "sizeCurve": [10, 48, 20],
+                        "colorStart": [3, 2.4, 1.2, 1],
+                        "colorEnd": [3, 2.4, 1.2, 0],
+                        "gravity": [0, 0],
+                        "drag": 0,
+                        "emissive": 3,
+                        "alignToVelocity": false
+                    }
+                }
+            ]
+        }
+    ]
+}

package/dist/fx/effects/index.d.ts

@@ -0,0 +1,8 @@
+/** The built-in effect descriptors (`src/fx/effects/*.json`), typed as `EffectDesc`. */
+import type { EffectDesc } from '../effect.js';
+/** A 2D impact: a burst of bright sparks and a short flash. */
+export declare const HIT_SPARK_EFFECT: EffectDesc;
+/** A 2D alpha-blended smoke puff that grows, spins and fades. */
+export declare const SMOKE_PUFF_EFFECT: EffectDesc;
+/** A looping world-space aura: rising motes that trail sparkles (sub-emission). */
+export declare const MAGIC_AURA_EFFECT: EffectDesc;

package/dist/fx/effects/index.js

@@ -0,0 +1,9 @@
+import hitSpark from './hit-spark.json' with { type: 'json' };
+import magicAura from './magic-aura.json' with { type: 'json' };
+import smokePuff from './smoke-puff.json' with { type: 'json' };
+/** A 2D impact: a burst of bright sparks and a short flash. */
+export const HIT_SPARK_EFFECT = hitSpark;
+/** A 2D alpha-blended smoke puff that grows, spins and fades. */
+export const SMOKE_PUFF_EFFECT = smokePuff;
+/** A looping world-space aura: rising motes that trail sparkles (sub-emission). */
+export const MAGIC_AURA_EFFECT = magicAura;

package/dist/fx/effects/magic-aura.json

@@ -0,0 +1,47 @@
+{
+    "loop": true,
+    "duration": 1,
+    "systems": [
+        {
+            "name": "motes",
+            "options": { "space": "world", "blend": "additive", "stretch": 0.01, "softness": 0.15 },
+            "emitters": [
+                {
+                    "rate": 24,
+                    "params": {
+                        "x": 0,
+                        "y": 0,
+                        "z": 0,
+                        "shape": { "kind": "sphere", "radius": 0.35 },
+                        "angle": 1.5707963,
+                        "spread": 1.0,
+                        "speed": [0.4, 0.9],
+                        "life": [1.0, 1.6],
+                        "sizeCurve": [0.02, 0.08, 0.06, 0.0],
+                        "colorCurve": [[0.4, 0.6, 2.4, 1], [1.2, 0.5, 2.8, 1], [0.2, 0.9, 2.0, 0]],
+                        "gravity": [0, 0.6, 0],
+                        "drag": 0.8,
+                        "emissive": 2.5,
+                        "inherit": 0.5,
+                        "onLife": {
+                            "rate": 18,
+                            "params": {
+                                "x": 0,
+                                "y": 0,
+                                "z": 0,
+                                "speed": [0.02, 0.08],
+                                "life": [0.3, 0.5],
+                                "size": [0.03, 0.0],
+                                "colorStart": [0.6, 0.4, 2.0, 0.8],
+                                "gravity": [0, 0, 0],
+                                "drag": 2,
+                                "emissive": 1.5
+                            }
+                        },
+                        "colorStart": [0.4, 0.6, 2.4, 1]
+                    }
+                }
+            ]
+        }
+    ]
+}

package/dist/fx/effects/smoke-puff.json

@@ -0,0 +1,34 @@
+{
+    "duration": 2.5,
+    "systems": [
+        {
+            "name": "smoke",
+            "options": { "space": "2d", "blend": "alpha", "stretch": 0 },
+            "emitters": [
+                {
+                    "burst": 12,
+                    "rate": 30,
+                    "duration": 0.3,
+                    "params": {
+                        "x": 0,
+                        "y": 0,
+                        "shape": { "kind": "circle", "radius": 8 },
+                        "angle": -1.5707963,
+                        "spread": 1.2,
+                        "speed": [30, 90],
+                        "life": [1.2, 2.2],
+                        "sizeCurve": [12, 40, 56, 64],
+                        "colorCurve": [[0.6, 0.6, 0.6, 0.7], [0.45, 0.45, 0.47, 0.5], [0.35, 0.35, 0.38, 0]],
+                        "gravity": [0, -40],
+                        "drag": 1.5,
+                        "emissive": 0,
+                        "rotation": [-3.14, 3.14],
+                        "spin": [-1.2, 1.2],
+                        "alignToVelocity": false,
+                        "colorStart": [0.6, 0.6, 0.6, 0.7]
+                    }
+                }
+            ]
+        }
+    ]
+}

package/dist/fx/emit-surface.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Mesh emission surfaces (ws/fx-3): a triangle list with a cumulative-area table, so particles
+ * can be born uniformly over a mesh's surface (`EmitShape` `{ kind: 'mesh' }`). Pure arithmetic;
+ * the GPU kernel samples the same table (`SURFACE_TRI_FLOATS` per triangle).
+ */
+import type { Geometry } from '../geom/geometry.js';
+/** A triangle mesh by its arrays: `positions` xyz per vertex, optional `normals`, `indices`. */
+export interface MeshShapeSource {
+    positions: ArrayLike<number>;
+    normals?: ArrayLike<number>;
+    indices?: ArrayLike<number>;
+}
+/**
+ * A mesh emit shape with its sampling table built: usable as `EmitParams.shape` directly.
+ * `table` holds `SURFACE_TRI_FLOATS` per triangle: p0 (xyz + cumulative area 0..1), p1, p2,
+ * n0, n1, n2 (unit normals, each xyz + 0).
+ */
+export interface EmitSurface extends MeshShapeSource {
+    readonly kind: 'mesh';
+    /** Launch along the surface normal (instead of `angle`/`spread`). Default false. */
+    alongNormal?: boolean;
+    readonly table: Float32Array;
+    readonly triangles: number;
+    /** Total surface area (square units). */
+    readonly area: number;
+}
+/**
+ * Build the sampling table of a `Geometry` (xyz at 0, normal at 3 of each `layout.floats`
+ * vertex) or of raw `positions`/`normals`/`indices`. Without indices every three positions
+ * are a triangle; without normals the face normal is used. Allocates; build once per mesh.
+ */
+export declare function buildEmitSurface(src: Geometry | MeshShapeSource, opts?: {
+    alongNormal?: boolean;
+}): EmitSurface;
+/**
+ * The CPU mirror of the kernel's sampling: triangle by `u` (binary search of the cumulative
+ * areas), point by `v`, `w` (square-root barycentrics, uniform over the triangle). Writes
+ * position xyz then normal xyz into `out` (6 floats). Returns the triangle index.
+ */
+export declare function sampleEmitSurface(surface: EmitSurface, u: number, v: number, w: number, out: Float32Array): number;