@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/particles.d.ts

@@ -0,0 +1,566 @@
+import type { Random } from '../core/random.js';
+import type { Drawable, Frame, ViewInfo } from '../render/frame.js';
+import type { Renderer } from '../render/renderer.js';
+import type { SceneTarget } from '../render/scene-target.js';
+import type { TextureLike } from '../render/texture.js';
+/** Most stops a `sizeCurve`/`colorCurve` may have. */
+export declare const MAX_CURVE_STOPS = 8;
+/** A `[min, max]` pair. */
+export type Range = readonly [number, number];
+export type EmitShape = {
+    kind: 'point';
+}
+/** Disc of `radius` in the XY plane. */
+ | {
+    kind: 'circle';
+    radius: number;
+}
+/** Rectangle centred on (x, y) in the XY plane. */
+ | {
+    kind: 'rect';
+    width: number;
+    height: number;
+}
+/** Segment from (x, y, z) to (x + dx, y + dy, z + dz). `dz` is world space only. */
+ | {
+    kind: 'line';
+    dx: number;
+    dy: number;
+    dz?: number;
+}
+/** Box centred on (x, y, z). In 2D it is a `rect` of `width × height`. */
+ | {
+    kind: 'box';
+    width: number;
+    height: number;
+    depth: number;
+}
+/** Ball of `radius` around (x, y, z). In 2D it is a `circle`. */
+ | {
+    kind: 'sphere';
+    radius: number;
+}
+/**
+ * The surface of a triangle mesh (area-weighted), offset by (x, y, z); extended kernel only.
+ * `alongNormal` launches along the surface normal. Pass a `buildEmitSurface` result to skip
+ * the table build; raw arrays are built (and cached by object identity) on first use.
+ */
+ | {
+    kind: 'mesh';
+    positions: ArrayLike<number>;
+    normals?: ArrayLike<number>;
+    indices?: ArrayLike<number>;
+    alongNormal?: boolean;
+};
+/**
+ * How new particles are born. Colours are linear RGBA (HDR ok). Units: logical px and seconds
+ * in 2D; world units and seconds in world space (defaults differ, see each field).
+ *
+ * The fields from `tile` on need the extended kernel (world space, or a 2D system with
+ * `extended`, `texture`, `forces` or `collide`); a plain 2D system ignores them with a warning.
+ */
+export interface EmitParams {
+    x: number;
+    y: number;
+    /** World space only. Default 0. */
+    z?: number;
+    shape?: EmitShape;
+    /**
+     * Launch direction in radians, in the XY plane. 2D: 0 = right, -π/2 = up (y down); default
+     * -π/2. World space (y up): π/2 = up, -π/2 = down; default π/2.
+     */
+    angle?: number;
+    /**
+     * Full cone width in radians around `angle`. Default 2π: all directions (a circle in 2D, a
+     * sphere in world space).
+     */
+    spread?: number;
+    /** [min, max] speed. Default [80, 300] px/s in 2D, [0.5, 2] units/s in world space. */
+    speed?: Range;
+    /** World space only: added to every launch velocity's z (units/s). Default 0. */
+    vz?: number;
+    /** [min, max] seconds. Default [0.5, 1.2]. */
+    life?: Range;
+    /** Size at [birth, death]. Default [6, 1] px in 2D, [0.1, 0.02] units in world space. */
+    size?: Range;
+    colorStart: ArrayLike<number>;
+    /** Default: `colorStart` with alpha 0. */
+    colorEnd?: ArrayLike<number>;
+    /**
+     * Acceleration. 2D: [x, y] px/s², default [0, 400] (falls). World space: [x, y, z] units/s²
+     * (a pair has z 0), default [0, -9.8, 0].
+     */
+    gravity?: readonly [number, number] | readonly [number, number, number];
+    /**
+     * World space only: the air's velocity [x, y, z] (units/s), which `drag` pulls particles
+     * toward. Default [0, 0, 0] (drag slows them to rest, as in 2D).
+     */
+    wind?: readonly [number, number, number];
+    /** Linear drag per second. Default 1. */
+    drag?: number;
+    /** How much the particle also feeds bloom (0..). Default 1. */
+    emissive?: number;
+    /**
+     * Sprite-sheet tile (row-major index into the system's `atlas`): one tile, or `[from, to]`
+     * played over the particle's life (or at `tileRate`). Default 0.
+     */
+    tile?: number | Range;
+    /** Tile frames per second for a `[from, to]` range, looping. Default 0: once over life. */
+    tileRate?: number;
+    /** Initial rotation [min, max] radians about the view axis. Default [0, 0]. */
+    rotation?: Range;
+    /** Angular velocity [min, max] rad/s. Default [0, 0]. */
+    spin?: Range;
+    /**
+     * Point the quad along the velocity (with `stretch`). Default true, the original streaks;
+     * false keeps the quad upright (plus `rotation`), for sprites.
+     */
+    alignToVelocity?: boolean;
+    /**
+     * Size over life as 2..8 evenly spaced stops (replaces `size`; the per-particle size jitter
+     * still applies). Cached by array identity: mutate the array, not its reference, to animate.
+     */
+    sizeCurve?: readonly number[];
+    /** Colour over life as 2..8 evenly spaced RGBA stops (replaces `colorStart`/`colorEnd`). */
+    colorCurve?: readonly ArrayLike<number>[];
+    /** Emit `count` particles of `params` where this particle dies (one level deep). */
+    onDeath?: {
+        params: EmitParams;
+        count: number;
+    };
+    /** Emit `params` at `rate` per second along this particle's path (one level deep). */
+    onLife?: {
+        params: EmitParams;
+        rate: number;
+    };
+    /** Fraction of the parent's velocity its children inherit. Default 0. */
+    inherit?: number;
+}
+/** How an `attract` force scales with distance (see `ParticleForce`). */
+export type AttractFalloff = 'constant' | 'linear' | 'inverse-square';
+/** A force applied to every particle each frame (`ParticleSystem.forces`). */
+export type ParticleForce = 
+/**
+ * Pull toward (x, y, z), fading linearly to 0 at `radius` (0 = everywhere). `falloff` shapes it
+ * by the distance r: `'constant'` (default) pulls at `strength` units/s² everywhere, so with
+ * light drag particles fly through the point and orbit it; `'linear'` pulls at `strength × r`
+ * (a spring: with drag they settle on the point); `'inverse-square'` at `strength / r²`
+ * (gravity-like). Nothing pulls inside `deadZone` (0) units, which also keeps
+ * `'inverse-square'` finite.
+ */
+{
+    kind: 'attract';
+    x: number;
+    y: number;
+    z?: number;
+    strength: number;
+    radius?: number;
+    falloff?: AttractFalloff;
+    deadZone?: number;
+}
+/** Swirl about the `axis` through (x, y, z) at `strength` units/s², fading to 0 at `radius`. */
+ | {
+    kind: 'vortex';
+    axis: readonly [number, number, number];
+    x: number;
+    y: number;
+    z?: number;
+    strength: number;
+    radius?: number;
+}
+/** Curl of value noise at `frequency` (1/units) scaled by `strength` units/s²: divergence-free gusts. */
+ | {
+    kind: 'turbulence';
+    frequency: number;
+    strength: number;
+    seed?: number;
+}
+/** Extra linear drag per second on top of each particle's own. */
+ | {
+    kind: 'drag';
+    amount: number;
+};
+export interface ParticleSystemOptions {
+    /**
+     * `'2d'` (default): logical px in the XY plane, the original behaviour, pixel for pixel.
+     * `'world'`: particles in 3D world space, drawn as quads facing the camera (`size` in world
+     * units), with distance and soft-depth fades and optional lighting.
+     */
+    space?: '2d' | 'world';
+    /**
+     * 2D only: use the extended kernel (sprite sheets, spin, curves, forces, sub-emission, mesh
+     * emission) instead of the pixel-pinned original. Implied by `texture`, `forces` and
+     * `collide`; world space always has it. Default false.
+     */
+    extended?: boolean;
+    /** Max live particles (ring buffer). Default 65536. */
+    capacity?: number;
+    /** Max emit() calls between frames (also the sub-emission request budget per frame). Default 256. */
+    maxSpawnsPerFrame?: number;
+    /**
+     * A bouncy floor. 2D: the logical y below which particles bounce (y down). World: the plane
+     * y = `floorY` (y up). Default none.
+     */
+    floorY?: number;
+    /** Floor restitution 0..1. Default 0.35. */
+    bounce?: number;
+    /** Seconds of velocity added to the quad length (motion streaks). Default 0.02. */
+    stretch?: number;
+    /**
+     * `'additive'` (default): colour adds, for sparks, embers and rain. `'alpha'`: premultiplied
+     * alpha over the scene, for smoke and dust that should cover what is behind.
+     */
+    blend?: 'additive' | 'alpha';
+    /**
+     * World space only: shade each particle as a small sphere through the lighting block
+     * (`engine_lambert`, so `frame.lights` ambient, sun and point lights apply). Default false.
+     */
+    lit?: boolean;
+    /**
+     * World space only: fade out with distance to the camera: whole nearer than `near`, gone
+     * beyond `far` (world units). Default none.
+     */
+    fade?: {
+        near: number;
+        far: number;
+    };
+    /**
+     * World space only: soft particles. Within this view-space distance (world units) of the
+     * scene's depth a particle fades out, so quads do not cut hard lines into geometry. Needs a
+     * depth camera; 0 turns it off. Default 0.25.
+     */
+    softness?: number;
+    /** World space only: the scene target whose depth soft particles read. Default `renderer.target`. */
+    depthTarget?: SceneTarget;
+    /**
+     * World space only: take this frame's opaque depth from the renderer's depth hook
+     * (`Drawable.readsDepth`, ws/render-hooks) instead of copying the previous frame's in
+     * `prepare`. Only a view with `depthTest` splits for it; elsewhere the fade is then off (no
+     * copy of the system's own). Default false.
+     */
+    readsDepth?: boolean;
+    /**
+     * Count live particles on the GPU and read the count back into `alive` (a few frames late).
+     * Costs one small dispatch per frame and an 8-byte readback every other frame. Default false.
+     */
+    countAlive?: boolean;
+    /** With `countAlive`: also count live particles whose y is below this into `below`. */
+    countBelowY?: number;
+    /**
+     * Sprite sheet (extended kernel): each particle draws a tile of this texture instead of the
+     * radial falloff; its alpha and colour multiply the particle's. Both blend modes sample it.
+     */
+    texture?: TextureLike;
+    /** The sprite sheet's grid, row-major from the top left. Default 1 × 1. */
+    atlas?: {
+        columns: number;
+        rows: number;
+    };
+    /** Initial `forces` (extended kernel; the array is live afterwards). */
+    forces?: ParticleForce[];
+    /**
+     * World space with `readsDepth`: collide with this frame's opaque depth. Particles found
+     * behind the scene (within `thickness` units along the view ray, default 1, or deeper when
+     * they were in front of it one step back) are pushed back onto the surface and bounce:
+     * `bounce` scales the normal velocity, `friction` (0..1) damps the tangential.
+     */
+    collide?: {
+        bounce: number;
+        friction: number;
+        thickness?: number;
+    };
+    /** Distinct `onDeath`/`onLife` descriptors the system can hold at once. Default 16. */
+    maxSubEmitters?: number;
+    /** Distinct `sizeCurve` plus `colorCurve` arrays the system can hold at once. Default 32 each. */
+    maxCurves?: number;
+    /**
+     * The stream every emit draws its spawn seed from (ws/fx-4). Default: a fork of the fx
+     * module default (`FX_DEFAULT_SEED`), named by creation order.
+     */
+    random?: Random;
+    /**
+     * Allow `debugReadback()` (ws/fx-6): the particle buffer gains `COPY_SRC` and a mapped
+     * staging buffer of the same size is made. Off (default): no staging buffer, no cost.
+     */
+    debug?: boolean;
+}
+/**
+ * What `ParticleSystem.debugReadback()` resolves to: the live particles (age < lifetime) at
+ * the copy, in slot order. Fresh arrays each call; a debugging aid, not a frame path.
+ */
+export interface ParticleReadback {
+    /** Live particles in the copy. */
+    alive: number;
+    /** xyz per live particle (`alive × 3`); 2D systems: logical px, z 0 on the original kernel. */
+    positions: Float32Array;
+    /** Velocity xyz per live particle (`alive × 3`), units per second. */
+    velocities: Float32Array;
+    /**
+     * The ring-buffer slot of each live particle. A slot keeps its particle until the ring wraps
+     * (`capacity` emits later), so two readbacks can be matched slot by slot.
+     */
+    slots: Uint32Array;
+    /** The system's simulated time (s, the sum of the clamped steps) when the copy was made. */
+    time: number;
+}
+/**
+ * What `ParticleSystem.readbackFields()` resolves to (ws/fx-7): every field of the live
+ * particles (age < lifetime) at the copy, one named typed array each, in slot order, so a reader
+ * needs no knowledge of the GPU packing. Vector fields are interleaved (`alive × n`); the rest
+ * hold one number per live particle. Fields the original 2D kernel does not carry are 0 there
+ * (`curveSlots` -1). Fresh arrays each call; a debugging aid, not a frame path.
+ */
+export interface ParticleFields {
+    /** Live particles in the copy; every array below is sized for it. */
+    alive: number;
+    /** The ring-buffer slot of each live particle (as `ParticleReadback.slots`). */
+    slots: Uint32Array;
+    /** The system's simulated time (s) when the copy was made. */
+    time: number;
+    /** xyz (`alive × 3`); z 0 on the original 2D kernel. */
+    position: Float32Array;
+    /** Velocity xyz (`alive × 3`), units per second; z 0 on the original 2D kernel. */
+    velocity: Float32Array;
+    /** Seconds since birth. */
+    age: Float32Array;
+    /** Lifetime in seconds (the particle dies when `age` reaches it). */
+    life: Float32Array;
+    /**
+     * Half the drawn size at this age: the size curve (by the system's current curve table) or the
+     * start-to-end lerp, clamped at 0, as the render shader computes it.
+     */
+    radius: Float32Array;
+    /** Size at birth (with a size curve: the curve's scale). */
+    sizeStart: Float32Array;
+    /** Size at death (unused with a size curve). */
+    sizeEnd: Float32Array;
+    /** Colour at birth, RGBA (`alive × 4`). */
+    color0: Float32Array;
+    /** Colour at death, RGBA (`alive × 4`). */
+    color1: Float32Array;
+    /** Gravity xyz (`alive × 3`); z 0 on the original 2D kernel. */
+    gravity: Float32Array;
+    drag: Float32Array;
+    emissive: Float32Array;
+    /** Rotation (rad). */
+    rotation: Float32Array;
+    /** Spin (rad/s). */
+    spin: Float32Array;
+    /** Wind xyz (`alive × 3`). */
+    wind: Float32Array;
+    /** Tile from, tile to, tile rate (fps, 0 = over life), flags (1 align to velocity) (`alive × 4`). */
+    tile: Float32Array;
+    /** Curve table slots: size, colour, death, life (`alive × 4`; -1 none). */
+    curveSlots: Int32Array;
+    /** Sub-emission: death count, life rate, life carry (`alive × 3`). */
+    sub: Float32Array;
+}
+/**
+ * GPU particles: spawn + integrate in compute, rendered as additive (or alpha) quads into both
+ * scene targets (colour + emissive → bloom). Draw with `frame.drawable(system)`.
+ *
+ * In 2D (`space: '2d'`, the default) quads are velocity-stretched in the XY plane. In world
+ * space they face the camera, stretch along the velocity's projection on the view plane,
+ * test depth, fade by distance and near scene geometry, and may be lit.
+ *
+ * The extended kernel (world space, or 2D with `extended`) adds sprite sheets, spin, curves,
+ * `forces`, depth collision, sub-emission and mesh emission; the plain 2D kernel stays what it
+ * was, pixel for pixel.
+ *
+ * Particles live in a ring buffer: when full, the oldest are overwritten.
+ */
+export declare class ParticleSystem implements Drawable {
+    readonly capacity: number;
+    readonly space: '2d' | 'world';
+    /** Whether this system runs the extended kernel. */
+    readonly extended: boolean;
+    /** Multiplier on every emit count (set < 1 for prefers-reduced-motion). */
+    spawnScale: number;
+    floorY: number;
+    bounce: number;
+    stretch: number;
+    /** World space only: see `ParticleSystemOptions.lit`. */
+    lit: boolean;
+    /** World space only: see `ParticleSystemOptions.fade` (null = no distance fade). */
+    fade: {
+        near: number;
+        far: number;
+    } | null;
+    /** World space only: see `ParticleSystemOptions.softness`. */
+    softness: number;
+    /** World space only: the target soft particles read depth from (null = `renderer.target`). */
+    depthTarget: SceneTarget | null;
+    /** See `ParticleSystemOptions.readsDepth`. Live. */
+    readsDepth: boolean;
+    /** Live particles at the last readback (`countAlive` only; -1 before the first). */
+    alive: number;
+    /** Live particles below `countBelowY` at the last readback (`countAlive` only; -1 before the first). */
+    below: number;
+    /** Live: the forces applied each frame (extended kernel; the first `MAX_FORCES` count). */
+    readonly forces: ParticleForce[];
+    /** Live: depth collision parameters (world, `readsDepth`; null = off). */
+    collide: {
+        bounce: number;
+        friction: number;
+        thickness?: number;
+    } | null;
+    /** Live: the stream `emit` draws spawn seeds from (see `ParticleSystemOptions.random`). */
+    random: Random;
+    private readonly renderer;
+    private readonly device;
+    private readonly particleBuffer;
+    private readonly spawnBuffer;
+    private readonly simBuffer;
+    private readonly spawnData;
+    private readonly simData;
+    private readonly spawnFloats;
+    private readonly maxSpawns;
+    private readonly spawnPipeline;
+    private readonly updatePipeline;
+    /**
+     * Render pipelines per depth format (null: none; a depth one tests without writing) × the
+     * view target's aux key, made on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    private readonly pipelines;
+    private readonly renderDesc;
+    private readonly blend;
+    /** World space: the velocity builds of the render shader by fragment location (ws/render-11). */
+    private readonly motionModules;
+    private computeGroup;
+    private readonly renderGroup;
+    private readonly soft;
+    private readonly counter;
+    private readonly fx;
+    private readonly collider;
+    /** `debug`: the staging buffer `debugReadback` copies the particles into. */
+    private readonly debugRead;
+    /** The copy in flight, shared by `debugReadback` and `readbackFields` calls made meanwhile. */
+    private debugJob;
+    /** Whether this frame's `prepare` copied scene depth (world space). */
+    private softActive;
+    /** The renderer's `depthCopy` view `hookGroup` was made for (`readsDepth`). */
+    private hookView;
+    private hookGroup;
+    /** The group `draw` binds: own copy, the renderer's copy, or the stand-in. */
+    private depthGroup;
+    private spawnCount;
+    private maxSpawnInCmd;
+    private head;
+    private pendingDt;
+    private time;
+    private warnedOverflow;
+    private warnedExtended;
+    private clearPending;
+    constructor(renderer: Renderer, opts?: ParticleSystemOptions);
+    /** A render bind group: the particles and sim, the depth view (world), the fx table/sheet. */
+    private makeRenderGroup;
+    private makeFx;
+    private makeComputeGroup;
+    private makeSoftDepth;
+    private makeCollider;
+    private makeCounter;
+    /**
+     * Queue `count` new particles. Cheap: one small record, spawned on the GPU next frame. The
+     * record's seed (every per-particle random on the GPU derives from it) is drawn from `random`,
+     * default the system's own stream.
+     */
+    emit(p: EmitParams, count: number, random?: Random): void;
+    private writeSpawn;
+    /**
+     * An extended spawn record at `at` of `d`: `n` particles from `start` (relative to the
+     * frame's ring head). `depth` 1 writes a sub-emitter record (no sub-emitters of its own).
+     */
+    private writeFxSpawn;
+    /** The curve table slot of `stops` (by identity; rewritten on every emit, so edits are live). */
+    private internCurve;
+    /** The sub-emitter record slot of `key` (by identity; rewritten on every parent emit). */
+    private internSub;
+    /** The surface table range of a mesh shape (built and appended on first sight). */
+    private internSurface;
+    /** Advance simulation time. Call from fixed update; integration happens on the GPU. */
+    update(dt: number): void;
+    prepare(encoder: GPUCommandEncoder, frame?: Frame): void;
+    /** Pack `forces` (the first `MAX_FORCES`) into the sim block; returns how many. */
+    private writeForces;
+    /** Upload the dirty curve, sub-emitter and surface tables (the surface buffer may grow). */
+    private uploadTables;
+    /**
+     * Map last frame's count (its commands were submitted by now). This frame records nothing
+     * into the readback buffer, so mapping it while this frame is encoded is valid.
+     */
+    private readAlive;
+    /**
+     * World space: copy the scene's depth into this system's own depth32float texture, which the
+     * fragment shader samples for the soft fade. It runs before this frame's scene pass, so it
+     * holds what the target's depth held then: the previous frame's, or that of an earlier
+     * `render` call this frame (draw the particles on their own layer in a second view of the
+     * same camera for a same-frame fade). Returns false (soft fade off) without depth.
+     */
+    private copyDepth;
+    /**
+     * Draw inside the scene pass. With a depth camera (`frame.depthFormat` set) the pipeline
+     * tests against depth without writing it, like any blended material.
+     */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    /**
+     * The renderer's depth hook (`readsDepth`, world space): with `softness` > 0 bind this
+     * frame's opaque depth copy and flip the shader's soft flag on (a 4-byte write that lands
+     * before the frame's commands run); with `collide` run the collision kernel against the same
+     * depth. New bind groups only when the copy texture changed.
+     */
+    afterOpaque(encoder: GPUCommandEncoder, view: ViewInfo): void;
+    private pipelineFor;
+    private motionModule;
+    /**
+     * Kill every particle (e.g. on scene change), including emits queued earlier this frame.
+     * The buffer is zeroed on the GPU at the start of the next `prepare` (no CPU allocation);
+     * particles emitted after `clear()` survive.
+     */
+    clear(): void;
+    /**
+     * Copy the particle buffer into the staging buffer, map it and return the live particles
+     * (`debug: true` only; rejects otherwise). Never runs on its own. The copy is submitted at
+     * once, so call it outside a frame (after `endFrame`): it then holds every frame submitted so
+     * far. A call while one is in flight returns that one's promise.
+     */
+    debugReadback(): Promise<ParticleReadback>;
+    /**
+     * As `debugReadback`, but resolves to every field of the live particles by name
+     * (`ParticleFields`), unpacked from the kernel's layout (ws/fx-7). `debug: true` only. Calls
+     * made while a copy is in flight share it with each other and with `debugReadback`, so both
+     * forms called back to back describe the same copy.
+     */
+    readbackFields(): Promise<ParticleFields>;
+    /** The copy in flight, or a new one submitted now; null without `debug`. */
+    private debugCopy;
+    /** `parseFields` with this system's layout and curve table. */
+    private parseFields;
+    destroy(): void;
+}
+/**
+ * The CPU reference of the kernel's curve lookup: piecewise-linear over `stops` (2..8) spread
+ * evenly on 0..1, each stop `stride` numbers (1 for a size curve, 4 for RGBA), written to `out`.
+ */
+export declare function evaluateCurve(stops: ArrayLike<number>, stride: number, t: number, out: Float32Array): Float32Array;
+/**
+ * The CPU reference of the kernel's force step: accelerate `vel` (xyz) by `forces` at `pos`
+ * over `dt` and apply the extra drag (the particle's own gravity, drag and wind are not
+ * included). For tests and shadow simulations; the GPU does the real work.
+ */
+export declare function applyForces(forces: readonly ParticleForce[], pos: ArrayLike<number>, vel: Float32Array | number[], dt: number): void;
+/**
+ * Continuous emission at `rate` particles/second, plus bursts. Mutate `params` freely. With
+ * `random` the emitter's spawn seeds come from that stream instead of the system's (ws/fx-4).
+ */
+export declare class ParticleEmitter {
+    readonly system: ParticleSystem;
+    params: EmitParams;
+    rate: number;
+    active: boolean;
+    /** Live: the stream this emitter's emits draw from; null uses the system's `random`. */
+    random: Random | null;
+    private carry;
+    constructor(system: ParticleSystem, params: EmitParams, rate?: number, random?: Random);
+    update(dt: number): void;
+    burst(count: number, overrides?: Partial<EmitParams>): void;
+}