@driftengine/core 3.61.0

package/dist/render/orderIndependent.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Order-independent transparency: the arithmetic, so it can be asserted without a device.
+ *
+ * **Two panes of glass should not depend on which was submitted first.** Sorted alpha blending is
+ * order-dependent by construction — `over` does not commute — so a translucent set is drawn back to
+ * front and anything the sort cannot separate flickers or wins arbitrarily: two panes that
+ * intersect, a pane containing another, a pane and the smoke inside it. A consumer's answer is
+ * usually to sort harder, which cannot fix an intersection at all.
+ *
+ * **Weighted blending replaces the ordering with a sum.** Each fragment contributes its colour
+ * scaled by a weight that falls off with distance, and separately multiplies a running
+ * transmittance. A sum and a product both commute, so the frame does not depend on the order the
+ * fragments arrived in — which is the property the census row asks for, and it is asserted here
+ * against numbers rather than argued about.
+ *
+ * **It is an approximation of the ordering and exact for one layer**, which is the honest way to
+ * state what it buys: with a single translucent surface there is no ordering to approximate and
+ * this reproduces `over` precisely, and the test beside it pins that. With several, near layers
+ * count for more than far ones and the result is plausible rather than correct — which is what a
+ * pane of glass needs and what a stained-glass window with eight overlapping leaves does not.
+ *
+ * McGuire and Bavoil, *Weighted Blended Order-Independent Transparency*, JCGT 2013 — equation 9
+ * for the weight, and its recommended constants, which are what the clamps below are.
+ *
+ * The one thing here that is not arithmetic is `OIT_MULTISAMPLE_REFUSAL`, and it is here for the
+ * same reason: it is a decision both backends take, so it is written once where neither owns it.
+ */
+/** A colour the accumulation is working on, as three numbers rather than a texture fetch. */
+export type Rgb = readonly [number, number, number];
+/**
+ * What the two targets hold between them.
+ *
+ * `accum` is the weighted sum of premultiplied colour with the weighted alpha in its fourth
+ * channel; `reveal` is the running product of what each layer let through. On a GPU these are two
+ * render targets with two blend states — additive for one, multiplicative for the other — and this
+ * object is the same numbers on the CPU so the algebra has somewhere to be tested.
+ */
+export interface OitAccumulator {
+    accum: [number, number, number, number];
+    /** One is "nothing has covered this pixel yet", which is why it is not zero. */
+    reveal: number;
+}
+/** An empty pixel: nothing accumulated, everything still revealed. */
+export declare function newOitAccumulator(): OitAccumulator;
+/**
+ * How much a fragment at `viewDepth` metres and this alpha counts for.
+ *
+ * **A near fragment must count for more than a far one**, or the accumulation is an unweighted
+ * average: a pane thirty metres away would contribute as much as one against the camera, which
+ * reads as fog rather than as glass.
+ *
+ * **Clamped at both ends, and the clamp is what keeps this stable in float.** Without a ceiling a
+ * fragment on the near plane takes a weight large enough to swamp every other layer, and their
+ * contributions are then lost to rounding inside a 16-bit target; without a floor a distant one
+ * rounds to nothing and vanishes rather than fading.
+ */
+export declare function oitWeight(viewDepth: number, alpha: number): number;
+/**
+ * Fold one fragment in.
+ *
+ * **A sum and a product, which is the whole mechanism**: both commute, so the pixel does not
+ * depend on the order its fragments arrived in. A change that made either depend on order — an
+ * `if` on what is already there, a max instead of a sum — breaks the row this exists to close, and
+ * the test beside this fails before it reaches a GPU.
+ */
+export declare function accumulateOit(state: OitAccumulator, colour: Rgb, alpha: number, viewDepth: number): void;
+/**
+ * The two targets composited over what is behind them.
+ *
+ * The weighted sum divided by the weighted alpha is the average colour the layers make; `reveal`
+ * says how much of the background still shows through. For one layer that reduces exactly to
+ * `colour * alpha + background * (1 - alpha)`, which is `over` — the anchor the test asserts.
+ */
+export declare function resolveOit(state: OitAccumulator, background: Rgb): [number, number, number];
+/**
+ * What both backends say when a profile asks for this and multisampling excludes it.
+ *
+ * **One string rather than one per backend, and that is rule 1 of the parity hard rule**:
+ * decisions live in backend-neutral code and only the binding is per-backend. The engine already
+ * paid for the other arrangement — `compositeWantsDepth` was two copies of one expression, depth
+ * of field was added to one of them, and the effect then ran against a discarded attachment. A
+ * refusal is a smaller thing than a depth attachment and drifts exactly as easily: the decal and
+ * reflection refusals beside this one are duplicated literals whose two halves have to be diffed
+ * by eye to know they still agree.
+ *
+ * **Why the effect is excluded rather than degraded.** Both passes attach the scene target's own
+ * depth and test against it, and above one sample the frame is not drawn into that texture — it
+ * is drawn into a multisampled renderbuffer, and the texture receives a copy at the end of the
+ * frame if anything asked for one. So the panes would be rejected against the frame before, or
+ * against a texture nothing has ever written.
+ */
+export declare const OIT_MULTISAMPLE_REFUSAL: string;

package/dist/render/orderIndependent.js

@@ -0,0 +1,108 @@
+/**
+ * Order-independent transparency: the arithmetic, so it can be asserted without a device.
+ *
+ * **Two panes of glass should not depend on which was submitted first.** Sorted alpha blending is
+ * order-dependent by construction — `over` does not commute — so a translucent set is drawn back to
+ * front and anything the sort cannot separate flickers or wins arbitrarily: two panes that
+ * intersect, a pane containing another, a pane and the smoke inside it. A consumer's answer is
+ * usually to sort harder, which cannot fix an intersection at all.
+ *
+ * **Weighted blending replaces the ordering with a sum.** Each fragment contributes its colour
+ * scaled by a weight that falls off with distance, and separately multiplies a running
+ * transmittance. A sum and a product both commute, so the frame does not depend on the order the
+ * fragments arrived in — which is the property the census row asks for, and it is asserted here
+ * against numbers rather than argued about.
+ *
+ * **It is an approximation of the ordering and exact for one layer**, which is the honest way to
+ * state what it buys: with a single translucent surface there is no ordering to approximate and
+ * this reproduces `over` precisely, and the test beside it pins that. With several, near layers
+ * count for more than far ones and the result is plausible rather than correct — which is what a
+ * pane of glass needs and what a stained-glass window with eight overlapping leaves does not.
+ *
+ * McGuire and Bavoil, *Weighted Blended Order-Independent Transparency*, JCGT 2013 — equation 9
+ * for the weight, and its recommended constants, which are what the clamps below are.
+ *
+ * The one thing here that is not arithmetic is `OIT_MULTISAMPLE_REFUSAL`, and it is here for the
+ * same reason: it is a decision both backends take, so it is written once where neither owns it.
+ */
+/** An empty pixel: nothing accumulated, everything still revealed. */
+export function newOitAccumulator() {
+    return { accum: [0, 0, 0, 0], reveal: 1 };
+}
+/**
+ * How much a fragment at `viewDepth` metres and this alpha counts for.
+ *
+ * **A near fragment must count for more than a far one**, or the accumulation is an unweighted
+ * average: a pane thirty metres away would contribute as much as one against the camera, which
+ * reads as fog rather than as glass.
+ *
+ * **Clamped at both ends, and the clamp is what keeps this stable in float.** Without a ceiling a
+ * fragment on the near plane takes a weight large enough to swamp every other layer, and their
+ * contributions are then lost to rounding inside a 16-bit target; without a floor a distant one
+ * rounds to nothing and vanishes rather than fading.
+ */
+export function oitWeight(viewDepth, alpha) {
+    const z = Math.max(0, viewDepth) / 200;
+    const falloff = 0.03 / (1e-5 + z * z * z * z);
+    return alpha * Math.min(3e3, Math.max(1e-2, falloff));
+}
+/**
+ * Fold one fragment in.
+ *
+ * **A sum and a product, which is the whole mechanism**: both commute, so the pixel does not
+ * depend on the order its fragments arrived in. A change that made either depend on order — an
+ * `if` on what is already there, a max instead of a sum — breaks the row this exists to close, and
+ * the test beside this fails before it reaches a GPU.
+ */
+export function accumulateOit(state, colour, alpha, viewDepth) {
+    const w = oitWeight(viewDepth, alpha);
+    state.accum[0] += colour[0] * alpha * w;
+    state.accum[1] += colour[1] * alpha * w;
+    state.accum[2] += colour[2] * alpha * w;
+    state.accum[3] += alpha * w;
+    state.reveal *= 1 - alpha;
+}
+/**
+ * The two targets composited over what is behind them.
+ *
+ * The weighted sum divided by the weighted alpha is the average colour the layers make; `reveal`
+ * says how much of the background still shows through. For one layer that reduces exactly to
+ * `colour * alpha + background * (1 - alpha)`, which is `over` — the anchor the test asserts.
+ */
+export function resolveOit(state, background) {
+    /* Guarded because a pixel no fragment touched has a weighted alpha of zero, and the reveal of
+       one below then discards whatever this produced anyway. */
+    const weight = Math.max(state.accum[3], 1e-5);
+    const average = [
+        state.accum[0] / weight,
+        state.accum[1] / weight,
+        state.accum[2] / weight,
+    ];
+    const covered = 1 - state.reveal;
+    return [
+        average[0] * covered + background[0] * state.reveal,
+        average[1] * covered + background[1] * state.reveal,
+        average[2] * covered + background[2] * state.reveal,
+    ];
+}
+/**
+ * What both backends say when a profile asks for this and multisampling excludes it.
+ *
+ * **One string rather than one per backend, and that is rule 1 of the parity hard rule**:
+ * decisions live in backend-neutral code and only the binding is per-backend. The engine already
+ * paid for the other arrangement — `compositeWantsDepth` was two copies of one expression, depth
+ * of field was added to one of them, and the effect then ran against a discarded attachment. A
+ * refusal is a smaller thing than a depth attachment and drifts exactly as easily: the decal and
+ * reflection refusals beside this one are duplicated literals whose two halves have to be diffed
+ * by eye to know they still agree.
+ *
+ * **Why the effect is excluded rather than degraded.** Both passes attach the scene target's own
+ * depth and test against it, and above one sample the frame is not drawn into that texture — it
+ * is drawn into a multisampled renderbuffer, and the texture receives a copy at the end of the
+ * frame if anything asked for one. So the panes would be rejected against the frame before, or
+ * against a texture nothing has ever written.
+ */
+export const OIT_MULTISAMPLE_REFUSAL = "driftengine: order-independent transparency attaches the scene target's own depth and tests " +
+    'against it, and a multisampled frame is not drawn into that texture — so translucent draws ' +
+    'stay sorted and blended wherever `sceneSamples` is above one. Antialiasing and this effect ' +
+    'are a choice of one.';

package/dist/render/particleBatch.d.ts

@@ -0,0 +1,140 @@
+import { type ParticleMaterial } from './particleMaterial.ts';
+import type { ParticleInstances } from './particlePool.ts';
+/**
+ * One draw call for a live particle pool: one camera-facing quad per particle, or a
+ * crossed pair of world-fixed ones when `facing` asks for them.
+ *
+ * Instanced: the cross is uploaded once as eight vertices, and each frame only the
+ * per-particle stream is re-sent. That is the difference between this and the
+ * scatter path it replaces — `InstancedMesh` is built for data that never changes
+ * after placement, and a particle system's data changes entirely every frame.
+ *
+ * Blending and depth are the batch's own decision because they are a property of
+ * the *material*: smoke occludes what is behind it and sparks add to it, and a
+ * caller that had to remember which would eventually forget. Neither writes depth
+ * — a soft particle that did would punch a hole in everything drawn after it.
+ */
+export type ParticleBlend = 'additive' | 'alpha';
+/**
+ * How a particle's quads are turned.
+ *
+ * `'camera'` is one quad facing the viewer, and the default. `'cross'` is the pair of
+ * world-fixed blades this batch drew before the option existed — see `uCameraFacing` in
+ * `shaders/particle.ts` for the artifact that made the default the other one, and for what
+ * the cross still buys a caller who wants it back.
+ */
+export type ParticleFacing = 'camera' | 'cross';
+export interface ParticleBatchOptions {
+    /**
+     * Which particle this is, by name.
+     *
+     * **This replaced a GLSL source string on 2026-08-13**, the same change and for the same
+     * reason as `PlumeOptions.material`: a caller-supplied shader is a capability that can only
+     * ever exist on WebGL2, and naming the material lets each backend resolve what it can
+     * compile. See `particleMaterial.ts`.
+     */
+    material: ParticleMaterial;
+    blend: ParticleBlend;
+    /**
+     * Seconds of travel a particle is stretched along. 0 for smoke.
+     *
+     * **The velocity it stretches along is a direction to be drawn on, not a motion being
+     * simulated, and it must stay that way.** Nothing here integrates it: a caller writes both
+     * position and velocity every frame, so a deterministic consumer that computes where a
+     * particle *is* from its own plan can still ask for the streak that a moving thing has. That
+     * is load-bearing outside this repository, where a corona's streamers are the spark material
+     * stretched radially and nothing about them moves. Advancing position from this would take
+     * the feature away from every caller that is not running a simulation.
+     */
+    stretchSec?: number;
+    /** How hard the noise erodes a puff, 0 to 1. Ignored by the spark and mote materials. */
+    erosion?: number;
+    /** How far past white a spark's core may go. Ignored by the smoke and mote materials. */
+    coreGain?: number;
+    /**
+     * Whether the medium's fog and underwater tint reach this pool. Ignored by the spark and
+     * smoke materials, which stay unconditionally fogged — a real ember and real grit belong in
+     * the same haze as the rest of the world, matching every particle drawn before this option
+     * existed. Defaults to false, because a caller reaching for `'mote'` over `'spark'`/`'smoke'`
+     * is usually asking for exactly what those two cannot draw: an unlit point exactly its own
+     * colour, untouched by distance. See `PARTICLE_MOTE_FRAG`'s own comment on `uFogEnabled`.
+     */
+    fog?: boolean;
+    /**
+     * Whether each particle is one camera-facing quad or a world-fixed cross of two.
+     *
+     * Defaults to `'camera'`, and **this default changed** — every particle drawn before it
+     * was a cross. A cross has a blade edge-on down each of two world axes, and a sprite
+     * squeezed into a one-pixel column spends its whole brightness there: a bright straight
+     * line through the middle, worst on the additive materials, and a pair of them from
+     * directly above. Consider `'cross'` when the camera stays near horizontal and the
+     * parallax of two blades is worth more than a stable brightness, which is the trade the
+     * shader's own comment on `uCameraFacing` lays out.
+     */
+    facing?: ParticleFacing;
+    /**
+     * Another batch whose compiled program this one should reuse.
+     *
+     * Several pools legitimately share a *material* while needing their own buffers —
+     * a game may have four kinds of smoke, each with its own colours, lifetime and
+     * capacity, all drawn by one fragment shader. Without this each of them compiles
+     * the same source again, which is pure boot time on the device where boot time is
+     * scarcest. The per-material constants stay per batch, because they are the point
+     * of having several.
+     *
+     * Only valid for the same `material`, and **that is now checked** — it was not, and could
+     * not be, while the material was an opaque source string a caller supplied. Naming it made
+     * the constraint expressible, so a spark batch reusing a smoke program fails at construction
+     * with both names rather than drawing sparks that look like smoke.
+     */
+    reuse?: ParticleBatch;
+}
+export declare class ParticleBatch {
+    readonly program: WebGLProgram;
+    readonly uniforms: Record<string, WebGLUniformLocation>;
+    private readonly vao;
+    private readonly buffers;
+    private readonly positionBuffer;
+    private readonly sizeBuffer;
+    private readonly spinBuffer;
+    private readonly colorBuffer;
+    private readonly alphaBuffer;
+    private readonly ageBuffer;
+    private readonly seedBuffer;
+    private readonly velocityBuffer;
+    private readonly blend;
+    private readonly stretchSec;
+    private readonly erosion;
+    private readonly coreGain;
+    private readonly fog;
+    private readonly facing;
+    /** False when the program belongs to another batch, so `dispose` leaves it alone. */
+    private readonly ownsProgram;
+    /** Which material compiled this batch's program, so `reuse` can be checked. */
+    readonly material: ParticleMaterial;
+    constructor(gl: WebGL2RenderingContext, capacity: number, options: ParticleBatchOptions);
+    /**
+     * Send this frame's particles.
+     *
+     * Only the live prefix of each array, which is what the pool's compaction
+     * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
+     */
+    upload(gl: WebGL2RenderingContext, data: ParticleInstances): void;
+    /** Bind this material's own constants. Called once per draw, before `drawTo`. */
+    bindMaterial(gl: WebGL2RenderingContext): void;
+    /**
+     * Draw the live particles.
+     *
+     * Depth *tested* but not written, so a puff is correctly hidden behind the deck
+     * and never hides a puff behind it. Culling off, because a blade seen from
+     * behind is exactly as valid as one seen from the front.
+     */
+    drawTo(gl: WebGL2RenderingContext, count: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    private send;
+    /**
+     * One attribute buffer. `divisor` 0 is per-vertex, 1 is per-instance — the whole
+     * mechanism by which eight vertices draw a thousand particles.
+     */
+    private attach;
+}

package/dist/render/particleBatch.js

@@ -0,0 +1,186 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { particleShaders } from './particleMaterial.js';
+import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.js';
+/** Corners of one blade, as a triangle-strip-friendly quad. */
+const CORNERS = [
+    [-1, -1],
+    [1, -1],
+    [1, 1],
+    [-1, 1],
+];
+export class ParticleBatch {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    positionBuffer;
+    sizeBuffer;
+    spinBuffer;
+    colorBuffer;
+    alphaBuffer;
+    ageBuffer;
+    seedBuffer;
+    velocityBuffer;
+    blend;
+    stretchSec;
+    erosion;
+    coreGain;
+    fog;
+    facing;
+    /** False when the program belongs to another batch, so `dispose` leaves it alone. */
+    ownsProgram;
+    /** Which material compiled this batch's program, so `reuse` can be checked. */
+    material;
+    constructor(gl, capacity, options) {
+        /* The vertex stage comes with the material now; it used to be a separate argument that
+           every caller passed the same value for. */
+        const shaders = particleShaders(options.material);
+        const shared = options.reuse;
+        if (shared !== undefined && shared.material !== options.material) {
+            throw new Error(`createParticles: cannot reuse a "${shared.material}" program for a ` +
+                `"${options.material}" batch. \`reuse\` shares one compiled material between pools.`);
+        }
+        this.ownsProgram = shared === undefined;
+        this.material = options.material;
+        this.program =
+            shared?.program ??
+                compileProgram(gl, shaders.vertexSource, shaders.fragmentSource, shaders.label);
+        this.uniforms = shared?.uniforms ?? uniformLocations(gl, this.program, 'particleBatch');
+        this.blend = options.blend;
+        this.stretchSec = options.stretchSec ?? 0;
+        this.erosion = options.erosion ?? 0;
+        this.coreGain = options.coreGain ?? 1;
+        this.fog = options.fog ?? false;
+        this.facing = options.facing ?? 'camera';
+        const corners = new Float32Array(PARTICLE_VERTS * 2);
+        const blades = new Float32Array(PARTICLE_VERTS);
+        const indices = new Uint16Array(PARTICLE_INDICES);
+        for (let b = 0; b < PARTICLE_BLADES; b++) {
+            for (let c = 0; c < 4; c++) {
+                const v = b * 4 + c;
+                const corner = CORNERS[c] ?? [0, 0];
+                corners[v * 2] = corner[0];
+                corners[v * 2 + 1] = corner[1];
+                blades[v] = b;
+            }
+            const base = b * 4;
+            const i = b * 6;
+            indices[i] = base;
+            indices[i + 1] = base + 1;
+            indices[i + 2] = base + 2;
+            indices[i + 3] = base;
+            indices[i + 4] = base + 2;
+            indices[i + 5] = base + 3;
+        }
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error(`${shaders.label}: createVertexArray failed`);
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        this.attach(gl, 0, corners, 2, 0, shaders.label);
+        this.attach(gl, 1, blades, 1, 0, shaders.label);
+        this.positionBuffer = this.attach(gl, 2, capacity * 3, 3, 1, shaders.label);
+        this.sizeBuffer = this.attach(gl, 3, capacity, 1, 1, shaders.label);
+        this.spinBuffer = this.attach(gl, 4, capacity, 1, 1, shaders.label);
+        this.colorBuffer = this.attach(gl, 5, capacity * 3, 3, 1, shaders.label);
+        this.alphaBuffer = this.attach(gl, 6, capacity, 1, 1, shaders.label);
+        this.ageBuffer = this.attach(gl, 7, capacity, 1, 1, shaders.label);
+        this.seedBuffer = this.attach(gl, 8, capacity, 1, 1, shaders.label);
+        this.velocityBuffer = this.attach(gl, 9, capacity * 3, 3, 1, shaders.label);
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error(`${shaders.label}: createBuffer failed`);
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Send this frame's particles.
+     *
+     * Only the live prefix of each array, which is what the pool's compaction
+     * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
+     */
+    upload(gl, data) {
+        const n = data.count;
+        if (n === 0)
+            return;
+        this.send(gl, this.positionBuffer, data.positions, n * 3);
+        this.send(gl, this.sizeBuffer, data.sizes, n);
+        this.send(gl, this.spinBuffer, data.spins, n);
+        this.send(gl, this.colorBuffer, data.colors, n * 3);
+        this.send(gl, this.alphaBuffer, data.alphas, n);
+        this.send(gl, this.ageBuffer, data.ages, n);
+        this.send(gl, this.seedBuffer, data.seeds, n);
+        this.send(gl, this.velocityBuffer, data.velocities, n * 3);
+    }
+    /** Bind this material's own constants. Called once per draw, before `drawTo`. */
+    bindMaterial(gl) {
+        const u = this.uniforms;
+        gl.uniform1f(u['uStretchSec'] ?? null, this.stretchSec);
+        gl.uniform1f(u['uCameraFacing'] ?? null, this.facing === 'camera' ? 1 : 0);
+        gl.uniform1f(u['uErosion'] ?? null, this.erosion);
+        gl.uniform1f(u['uCoreGain'] ?? null, this.coreGain);
+        /* Only the mote program declares uFogEnabled, so this is a no-op — not a leak into the
+           next draw — on the other two: `u['uFogEnabled']` is undefined there and gl.uniform1i
+           silently ignores a null location. */
+        gl.uniform1i(u['uFogEnabled'] ?? null, this.fog ? 1 : 0);
+    }
+    /**
+     * Draw the live particles.
+     *
+     * Depth *tested* but not written, so a puff is correctly hidden behind the deck
+     * and never hides a puff behind it. Culling off, because a blade seen from
+     * behind is exactly as valid as one seen from the front.
+     */
+    drawTo(gl, count) {
+        if (count === 0)
+            return;
+        gl.enable(gl.BLEND);
+        if (this.blend === 'additive')
+            gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        else
+            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawElementsInstanced(gl.TRIANGLES, PARTICLE_INDICES, gl.UNSIGNED_SHORT, 0, count);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        this.buffers.length = 0;
+        gl.deleteVertexArray(this.vao);
+        if (this.ownsProgram)
+            gl.deleteProgram(this.program);
+    }
+    send(gl, buffer, data, length) {
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, data, 0, length);
+    }
+    /**
+     * One attribute buffer. `divisor` 0 is per-vertex, 1 is per-instance — the whole
+     * mechanism by which eight vertices draw a thousand particles.
+     */
+    attach(gl, location, dataOrFloats, size, divisor, label) {
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error(`${label}: createBuffer failed`);
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        if (typeof dataOrFloats === 'number') {
+            gl.bufferData(gl.ARRAY_BUFFER, dataOrFloats * 4, gl.DYNAMIC_DRAW);
+        }
+        else {
+            gl.bufferData(gl.ARRAY_BUFFER, dataOrFloats, gl.STATIC_DRAW);
+        }
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        gl.vertexAttribDivisor(location, divisor);
+        return buffer;
+    }
+}

package/dist/render/particleMaterial.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which particle material a caller wants, by name rather than by source.
+ *
+ * **The same change `PlumeMaterial` documents, for the same reason.**
+ * `ParticleBatchOptions.fragmentSource` was a GLSL string, and a caller-supplied GLSL string
+ * is a capability that can only ever exist on WebGL2 — WebGPU has no runtime compiler and this
+ * package must never ship one. Naming the material lets each backend resolve what it can
+ * compile.
+ *
+ * **The three are not interchangeable and never were**, which is why the names read as
+ * materials rather than as shaders: `erosion` is ignored by the spark and the mote, `coreGain`
+ * by the smoke and the mote, and `fog` by the spark and the smoke — and the options already
+ * document that. Naming them makes the pairing explicit instead of leaving it to a caller to
+ * match a source with the constants that suit it.
+ */
+export type ParticleMaterial = 'smoke' | 'spark' | 'mote';
+/** Both compilations of one material, and what the generator recorded about each stage. */
+export interface ParticleShaders {
+    readonly label: string;
+    readonly vertexSource: string;
+    readonly fragmentSource: string;
+    readonly vertexWgsl: string;
+    readonly fragmentWgsl: string;
+}
+/** What the generator recorded about the shared vertex stage. */
+export declare const PARTICLE_VERT_BINDINGS: {
+    readonly uniforms: 0;
+    readonly uniformSize: 96;
+    readonly fields: {
+        readonly uViewProj: {
+            readonly offset: 0;
+            readonly size: 64;
+            readonly type: "mat4";
+        };
+        readonly uCameraPos: {
+            readonly offset: 64;
+            readonly size: 12;
+            readonly type: "vec3";
+        };
+        readonly uStretchSec: {
+            readonly offset: 76;
+            readonly size: 4;
+            readonly type: "float";
+        };
+        readonly uCameraFacing: {
+            readonly offset: 80;
+            readonly size: 4;
+            readonly type: "float";
+        };
+    };
+    readonly textures: {};
+};
+/** Resolve a material name, or say which names exist. */
+export declare function particleShaders(material: ParticleMaterial): ParticleShaders;

package/dist/render/particleMaterial.js

@@ -0,0 +1,42 @@
+import { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './shaders/particle.js';
+import { PARTICLE_BINDINGS, PARTICLE_MOTE_FRAG_WGSL, PARTICLE_SMOKE_FRAG_WGSL, PARTICLE_SPARK_FRAG_WGSL, PARTICLE_VERT_WGSL, } from './shaders/generated/particle.wgsl.js';
+/**
+ * Every particle material this engine ships.
+ *
+ * One table with both compilations, rather than a lookup per backend — a material present in
+ * one and absent from the other is the drift the 2026-08-13 rule in `AGENTS.md` prevents.
+ */
+const MATERIALS = {
+    smoke: {
+        label: 'particle:smoke',
+        vertexSource: PARTICLE_VERT,
+        fragmentSource: PARTICLE_SMOKE_FRAG,
+        vertexWgsl: PARTICLE_VERT_WGSL,
+        fragmentWgsl: PARTICLE_SMOKE_FRAG_WGSL,
+    },
+    spark: {
+        label: 'particle:spark',
+        vertexSource: PARTICLE_VERT,
+        fragmentSource: PARTICLE_SPARK_FRAG,
+        vertexWgsl: PARTICLE_VERT_WGSL,
+        fragmentWgsl: PARTICLE_SPARK_FRAG_WGSL,
+    },
+    mote: {
+        label: 'particle:mote',
+        vertexSource: PARTICLE_VERT,
+        fragmentSource: PARTICLE_MOTE_FRAG,
+        vertexWgsl: PARTICLE_VERT_WGSL,
+        fragmentWgsl: PARTICLE_MOTE_FRAG_WGSL,
+    },
+};
+/** What the generator recorded about the shared vertex stage. */
+export const PARTICLE_VERT_BINDINGS = PARTICLE_BINDINGS.PARTICLE_VERT;
+/** Resolve a material name, or say which names exist. */
+export function particleShaders(material) {
+    const found = MATERIALS[material];
+    if (found === undefined) {
+        throw new Error(`createParticles: unknown particle material "${String(material)}". ` +
+            `Known materials: ${Object.keys(MATERIALS).join(', ')}.`);
+    }
+    return found;
+}