@codexo/exojs-particles 0.15.2 → 0.16.0

package/dist/esm/ParticleSystem.js

@@ -1,569 +1,669 @@
-import { Drawable, Rectangle, Texture, Spritesheet } from '@codexo/exojs';
-import { ParticleGpuState } from './gpu/ParticleGpuState.js';
+import { ParticleGpuState } from "./gpu/ParticleGpuState.js";
+import { ParticleSlotWriter, ParticleStorage } from "./ParticleStorage.js";
+import { QuadParticles } from "./renderModes/QuadParticles.js";
+import { Drawable, Rectangle, Spritesheet, Texture } from "@codexo/exojs";
 
-/// <reference types="@webgpu/types" />
+//#region src/ParticleSystem.ts
 const defaultCapacity = 4096;
 /**
- * Lazily-initialised 1×1 opaque-white texture used as the default sprite
- * when a {@link ParticleSystem} is constructed without one. Particles
- * render as solid color quads (the per-particle `color` channel times
- * white-with-alpha-1). Shared across systems to avoid wasted texture
- * allocations.
- */
+* Lazily-initialised 1×1 opaque-white texture used as the default sprite
+* when a {@link ParticleSystem} is constructed without one. Particles
+* render as solid color quads (the per-particle `color` channel times
+* white-with-alpha-1). Shared across systems to avoid wasted texture
+* allocations.
+*/
 let defaultWhiteTexture = null;
 const getDefaultWhiteTexture = () => {
-    if (defaultWhiteTexture === null) {
-        const canvas = document.createElement('canvas');
-        canvas.width = 1;
-        canvas.height = 1;
-        const ctx = canvas.getContext('2d');
-        if (ctx !== null) {
-            ctx.fillStyle = '#ffffff';
-            ctx.fillRect(0, 0, 1, 1);
-        }
-        defaultWhiteTexture = new Texture(canvas);
-    }
-    return defaultWhiteTexture;
+	if (defaultWhiteTexture === null) {
+		const canvas = document.createElement("canvas");
+		canvas.width = 1;
+		canvas.height = 1;
+		const ctx = canvas.getContext("2d");
+		if (ctx !== null) {
+			ctx.fillStyle = "#ffffff";
+			ctx.fillRect(0, 0, 1, 1);
+		}
+		defaultWhiteTexture = new Texture(canvas);
+	}
+	return defaultWhiteTexture;
 };
 /**
- * The central coordinator of the particle pipeline. `ParticleSystem` is a
- * {@link Drawable} that owns:
- *
- * - **SoA particle storage** — one typed array per attribute (position,
- *   velocity, scale, rotation, color, lifetime, ...), sized to a fixed
- *   capacity at construction. User code reads/writes via
- *   `system.posX[slot]`, `system.velX[slot]`, etc.
- * - **Spawn modules** — write new particles into freshly allocated slots.
- * - **Update modules** — mutate the live range each frame (forces, color
- *   blends, scale curves, drag, ...). Built-in modules ship both CPU and
- *   WGSL implementations; custom modules can opt into GPU acceleration by
- *   implementing `wgsl()`.
- * - **Death modules** — fire once per dying particle, before its slot is
- *   recycled (sub-emitters, event hooks).
- *
- * **Auto-routing CPU vs GPU:** at first {@link update}, the system checks:
- * if a `WebGpuBackend` was supplied AND every registered update module has
- * `wgsl()`, the GPU path engages — a composite compute pipeline runs
- * integration plus all module bodies in one dispatch and writes directly
- * into the renderer's instance buffer (no CPU readback). Otherwise the CPU
- * path runs the existing per-module `apply()` loops.
- *
- * **Per-frame order in {@link update} (CPU mode):**
- * 1. Run every spawn module.
- * 2. Integrate position from velocity, rotation from rotationSpeed, advance `elapsed`.
- * 3. Run every update module on the live range.
- * 4. Compact: scan `[0, liveCount)` forward, fire death modules on expired
- *    slots, copy survivors down. `liveCount` shrinks to the survivor count.
- *
- * **Per-frame order in {@link update} (GPU mode):**
- * 1. Run every spawn module (CPU writes initial values into the spawn slot).
- * 2. Detect expiries on CPU (via `elapsed >= lifetime`); fire death modules;
- *    set `lifetime[slot] = -1` sentinel + clear `alive[slot]` so the GPU
- *    shader skips them. **No compaction** — slots are recycled on next spawn.
- * 3. Dispatch the composite compute pipeline. Integration + update modules
- *    + pack-instances run in one pass; the instance buffer is written
- *    directly. CPU SoA stays as-is for spawn writes.
- *
- * **Coordinate space:** particle positions are LOCAL to the system. The
- * system's `getGlobalTransform()` is applied on top during rendering — both
- * the WebGL2 and WebGPU shaders multiply `projection * translation * rotated`.
- * Setting world-space positions on individual particles double-translates.
- * Position the system itself via `system.setPosition(...)` and emit relative
- * to `(0, 0)`.
- *
- * @example
- * // Backend-agnostic — runs CPU on WebGL2, GPU on WebGPU automatically.
- * const system = new ParticleSystem(loader.get(Texture, 'spark'), {
- *     capacity: 8192,
- * });
- *
- * system.addSpawnModule(new RateSpawn({ rate: new Constant(60), ... }));
- * system.addUpdateModule(new ApplyForce(0, 980));     // gravity, GPU-eligible
- * system.addUpdateModule(new ColorOverLifetime(fireGradient));
- * scene.addChild(system);
- */
-class ParticleSystem extends Drawable {
-    /** Maximum particle count this system will store. Fixed at construction. */
-    capacity;
-    posX;
-    posY;
-    velX;
-    velY;
-    scaleX;
-    scaleY;
-    rotations;
-    rotationSpeeds;
-    color; // packed 0xAABBGGRR
-    elapsed; // seconds since spawn
-    lifetime; // total seconds before expiry; -1 sentinel for dead in GPU mode
-    textureIndex;
-    /**
-     * Number of currently live particles. In CPU mode this is exact: slots
-     * `[0, liveCount)` are all alive after each `update()`. In GPU mode
-     * this is a high-water mark — slots `[0, liveCount)` may contain dead
-     * holes (filled in by future spawns); use {@link aliveCount} for the
-     * actual alive count.
-     */
-    liveCount = 0;
-    /**
-     * Per-slot alive flag (1 = alive, 0 = dead). Maintained in both CPU
-     * and GPU mode. Custom modules iterating the live range should check
-     * this to skip dead slots in GPU mode.
-     */
-    alive;
-    _spawnModules = [];
-    _updateModules = [];
-    _deathModules = [];
-    _backend = null;
-    _device = null;
-    _gpuState = null;
-    _gpuMode = false;
-    _compiled = false;
-    _spawnHint = 0; // round-robin pointer for first-dead lookup in GPU mode
-    /**
-     * In GPU mode, slots whose CPU SoA values need re-uploading to the GPU
-     * (newly spawned, or just-expired with lifetime sentinel). Cleared
-     * after each compute dispatch. CPU never overwrites integrated GPU
-     * state — only dirty slots flow CPU → GPU.
-     */
-    _gpuDirtySlots = new Set();
-    _texture;
-    _frames = [];
-    _textureFrame = new Rectangle();
-    _vertices = new Float32Array(4);
-    _texCoords = new Uint32Array(4);
-    _updateTexCoords = true;
-    _updateVertices = true;
-    constructor(sourceOrOptions, framesOrOptions, finalOptions) {
-        super();
-        // Disambiguate the four valid call shapes via instanceof checks.
-        // The TS overloads above already prevent illegal combinations like
-        // `(texture, sheet)` or `(sheet, frames)` at compile time; this
-        // narrowing only sorts out the legal ones.
-        let texture = null;
-        let frames = null;
-        let options;
-        if (sourceOrOptions instanceof Texture) {
-            texture = sourceOrOptions;
-            if (Array.isArray(framesOrOptions)) {
-                frames = framesOrOptions;
-                options = finalOptions ?? {};
-            }
-            else {
-                options = framesOrOptions ?? {};
-            }
-        }
-        else if (sourceOrOptions instanceof Spritesheet) {
-            texture = sourceOrOptions.texture;
-            frames = [...sourceOrOptions.frames.values()];
-            options = framesOrOptions ?? {};
-        }
-        else {
-            options = sourceOrOptions ?? {};
-        }
-        const capacity = options.capacity ?? defaultCapacity;
-        if (capacity <= 0 || !Number.isInteger(capacity)) {
-            throw new Error(`ParticleSystem capacity must be a positive integer (got ${capacity}).`);
-        }
-        this.capacity = capacity;
-        this.posX = new Float32Array(capacity);
-        this.posY = new Float32Array(capacity);
-        this.velX = new Float32Array(capacity);
-        this.velY = new Float32Array(capacity);
-        this.scaleX = new Float32Array(capacity);
-        this.scaleY = new Float32Array(capacity);
-        this.rotations = new Float32Array(capacity);
-        this.rotationSpeeds = new Float32Array(capacity);
-        this.color = new Uint32Array(capacity);
-        this.elapsed = new Float32Array(capacity);
-        this.lifetime = new Float32Array(capacity);
-        this.textureIndex = new Uint16Array(capacity);
-        this.alive = new Uint8Array(capacity);
-        this._device = options.device ?? null;
-        this._texture = texture ?? getDefaultWhiteTexture();
-        if (frames !== null) {
-            for (const frame of frames) {
-                this._frames.push(frame.clone());
-            }
-        }
-        this.resetTextureFrame();
-    }
-    get texture() {
-        return this._texture;
-    }
-    set texture(texture) {
-        this.setTexture(texture);
-    }
-    get textureFrame() {
-        return this._textureFrame;
-    }
-    set textureFrame(frame) {
-        this.setTextureFrame(frame);
-    }
-    /**
-     * Atlas frames declared on this system, or empty when the texture is
-     * used as a single frame. Each particle's `textureIndex[i]` selects
-     * an entry from this list; out-of-range indices are clamped to 0.
-     */
-    get frames() {
-        return this._frames;
-    }
-    /** `true` when the system declares more than one atlas frame. */
-    get hasAtlas() {
-        return this._frames.length > 1;
-    }
-    get vertices() {
-        if (this._updateVertices) {
-            const { x, y, width, height } = this._textureFrame;
-            const offsetX = width / 2;
-            const offsetY = height / 2;
-            this._vertices[0] = x - offsetX;
-            this._vertices[1] = y - offsetY;
-            this._vertices[2] = width - offsetX;
-            this._vertices[3] = height - offsetY;
-            this._updateVertices = false;
-        }
-        return this._vertices;
-    }
-    get texCoords() {
-        if (this._updateTexCoords) {
-            const { width, height } = this._texture;
-            const { left, top, right, bottom } = this._textureFrame;
-            const minX = ((left / width) * 65535) & 65535;
-            const minY = (((top / height) * 65535) & 65535) << 16;
-            const maxX = ((right / width) * 65535) & 65535;
-            const maxY = (((bottom / height) * 65535) & 65535) << 16;
-            if (this._texture.flipY) {
-                this._texCoords[0] = maxY | minX;
-                this._texCoords[1] = maxY | maxX;
-                this._texCoords[2] = minY | maxX;
-                this._texCoords[3] = minY | minX;
-            }
-            else {
-                this._texCoords[0] = minY | minX;
-                this._texCoords[1] = minY | maxX;
-                this._texCoords[2] = maxY | maxX;
-                this._texCoords[3] = maxY | minX;
-            }
-            this._updateTexCoords = false;
-        }
-        return this._texCoords;
-    }
-    /** `true` when the system is running on the GPU compute pipeline. */
-    get gpuMode() {
-        return this._gpuMode;
-    }
-    /** GPU-side state, or `null` in CPU mode. */
-    get gpuState() {
-        return this._gpuState;
-    }
-    /** Actual count of live particles (slots with `alive[i] === 1`). May differ from `liveCount` in GPU mode. */
-    get aliveCount() {
-        let count = 0;
-        for (let i = 0; i < this.liveCount; i++) {
-            if (this.alive[i] === 1)
-                count++;
-        }
-        return count;
-    }
-    get spawnModules() {
-        return this._spawnModules;
-    }
-    get updateModules() {
-        return this._updateModules;
-    }
-    get deathModules() {
-        return this._deathModules;
-    }
-    setTexture(texture) {
-        if (this._texture !== texture) {
-            this._texture = texture;
-            this.resetTextureFrame();
-        }
-        return this;
-    }
-    setTextureFrame(frame) {
-        this._textureFrame.copy(frame);
-        this._updateTexCoords = true;
-        this._updateVertices = true;
-        this.getLocalBounds().set(0, 0, frame.width, frame.height);
-        this._invalidateBoundsCascade();
-        return this;
-    }
-    resetTextureFrame() {
-        return this.setTextureFrame(Rectangle.temp.set(0, 0, this._texture.width, this._texture.height));
-    }
-    addSpawnModule(mod) {
-        this._spawnModules.push(mod);
-        return this;
-    }
-    addUpdateModule(mod) {
-        if (this._compiled) {
-            throw new Error('Cannot add update modules after the system has been compiled (first update). Register all modules before the first update().');
-        }
-        this._updateModules.push(mod);
-        return this;
-    }
-    addDeathModule(mod) {
-        this._deathModules.push(mod);
-        return this;
-    }
-    clearSpawnModules() {
-        for (const mod of this._spawnModules)
-            mod.destroy();
-        this._spawnModules.length = 0;
-        return this;
-    }
-    clearUpdateModules() {
-        for (const mod of this._updateModules)
-            mod.destroy();
-        this._updateModules.length = 0;
-        return this;
-    }
-    clearDeathModules() {
-        for (const mod of this._deathModules)
-            mod.destroy();
-        this._deathModules.length = 0;
-        return this;
-    }
-    /**
-     * Allocates a particle slot and returns its index. Returns `-1` when
-     * the system is at {@link capacity}.
-     *
-     * **CPU mode:** slots are dense in `[0, liveCount)`. `spawn()` returns
-     * the next sequential slot; `liveCount++`.
-     *
-     * **GPU mode:** slots may have dead holes. `spawn()` finds the first
-     * `alive[i] === 0` slot via a round-robin hint pointer (amortised O(1),
-     * worst case O(capacity) on full systems).
-     */
-    spawn() {
-        if (this._gpuMode) {
-            return this._spawnGpu();
-        }
-        return this._spawnCpu();
-    }
-    /** Resets the system to zero live particles without destroying it. */
-    clearParticles() {
-        this.liveCount = 0;
-        this._spawnHint = 0;
-        this.alive.fill(0);
-        this.lifetime.fill(0);
-        this.elapsed.fill(0);
-        return this;
-    }
-    /**
-     * @internal
-     *
-     * Collect-hook: captures the active backend before this node is emitted so
-     * the next `update()` can compile a GPU pipeline if the backend turned out
-     * to be `WebGpuBackend`. Re-captures and rebuilds when the backend
-     * reference changes (e.g. after device-loss recovery).
-     */
-    /** @internal */
-    _collect(builder, seq) {
-        const backend = builder.backend;
-        if (this._backend !== backend) {
-            this._backend = backend;
-            if (this._gpuState !== null) {
-                this._gpuState.destroy();
-                this._gpuState = null;
-            }
-            this._gpuMode = false;
-            this._compiled = false;
-        }
-        super._collect(builder, seq);
-    }
-    /** Per-frame entry point. Routes to CPU or GPU pipeline based on auto-detection at first call. */
-    update(delta) {
-        if (!this._compiled) {
-            this._compile();
-        }
-        const dt = delta.seconds;
-        // 1. Spawn (CPU writes SoA in both modes).
-        for (let i = 0; i < this._spawnModules.length; i++) {
-            this._spawnModules[i].apply(this, dt);
-        }
-        if (this._gpuMode) {
-            this._updateGpu(dt);
-        }
-        else {
-            this._updateCpu(dt);
-        }
-        return this;
-    }
-    destroy() {
-        super.destroy();
-        this.clearSpawnModules();
-        this.clearUpdateModules();
-        this.clearDeathModules();
-        if (this._gpuState !== null) {
-            this._gpuState.destroy();
-            this._gpuState = null;
-        }
-        for (const frame of this._frames) {
-            frame.destroy();
-        }
-        this._frames.length = 0;
-        this._gpuMode = false;
-        this._compiled = false;
-        this.liveCount = 0;
-        this.alive.fill(0);
-        this._textureFrame.destroy();
-    }
-    _compile() {
-        this._compiled = true;
-        // Duck-typed `instanceof WebGpuBackend` — avoids importing the
-        // backend class (which registers a renderer for ParticleSystem
-        // and would create a circular dependency). WebGl2Backend has no
-        // `device` field, so this naturally falls back to CPU mode.
-        const backendDevice = this._backend?.device ?? null;
-        const device = this._device ?? backendDevice;
-        if (device === null) {
-            return;
-        }
-        const allEligible = this._updateModules.every(m => typeof m.wgsl === 'function');
-        if (!allEligible) {
-            return;
-        }
-        this._gpuState = new ParticleGpuState(device, this.capacity, this._updateModules, this._frames, this._texture);
-        this._gpuMode = true;
-        // Mark every currently-alive slot dirty so the initial upload
-        // matches CPU state; subsequent frames only push deltas.
-        for (let i = 0; i < this.liveCount; i++) {
-            if (this.alive[i] === 1)
-                this._gpuDirtySlots.add(i);
-        }
-    }
-    _spawnCpu() {
-        if (this.liveCount >= this.capacity) {
-            return -1;
-        }
-        const slot = this.liveCount++;
-        this.alive[slot] = 1;
-        this.elapsed[slot] = 0;
-        return slot;
-    }
-    _spawnGpu() {
-        const capacity = this.capacity;
-        const alive = this.alive;
-        const start = this._spawnHint;
-        // Search forward from hint, then wrap.
-        for (let i = start; i < capacity; i++) {
-            if (alive[i] === 0) {
-                alive[i] = 1;
-                this.elapsed[i] = 0;
-                this._spawnHint = i + 1 === capacity ? 0 : i + 1;
-                if (i >= this.liveCount)
-                    this.liveCount = i + 1;
-                this._gpuDirtySlots.add(i);
-                return i;
-            }
-        }
-        for (let i = 0; i < start; i++) {
-            if (alive[i] === 0) {
-                alive[i] = 1;
-                this.elapsed[i] = 0;
-                this._spawnHint = i + 1;
-                if (i >= this.liveCount)
-                    this.liveCount = i + 1;
-                this._gpuDirtySlots.add(i);
-                return i;
-            }
-        }
-        return -1;
-    }
-    _updateCpu(dt) {
-        const { posX, posY, velX, velY, rotations, rotationSpeeds, elapsed } = this;
-        const liveCount = this.liveCount;
-        for (let i = 0; i < liveCount; i++) {
-            posX[i] = posX[i] + velX[i] * dt;
-            posY[i] = posY[i] + velY[i] * dt;
-            rotations[i] = rotations[i] + rotationSpeeds[i] * dt;
-            elapsed[i] = elapsed[i] + dt;
-        }
-        for (let i = 0; i < this._updateModules.length; i++) {
-            this._updateModules[i].apply(this, dt);
-        }
-        // Compact: forward pass, fire death modules on expired, copy survivors down.
-        const lifetime = this.lifetime;
-        const alive = this.alive;
-        const deathModules = this._deathModules;
-        let writeIndex = 0;
-        for (let readIndex = 0; readIndex < this.liveCount; readIndex++) {
-            if (elapsed[readIndex] >= lifetime[readIndex]) {
-                for (let m = 0; m < deathModules.length; m++) {
-                    deathModules[m].onDeath(this, readIndex);
-                }
-                alive[readIndex] = 0;
-                continue;
-            }
-            if (writeIndex !== readIndex) {
-                this._copySlot(readIndex, writeIndex);
-                alive[writeIndex] = 1;
-            }
-            writeIndex++;
-        }
-        for (let i = writeIndex; i < this.liveCount; i++) {
-            alive[i] = 0;
-        }
-        this.liveCount = writeIndex;
-    }
-    _updateGpu(dt) {
-        // CPU advances its own copy of `elapsed` for expire detection only.
-        // GPU's `timing[idx].x` is advanced independently inside the compute
-        // shader; the two are never synced after spawn. They tick at the
-        // same rate (both add `dt` per frame) so they stay equivalent in
-        // practice (modulo numerical drift).
-        const elapsed = this.elapsed;
-        const lifetime = this.lifetime;
-        const alive = this.alive;
-        const deathModules = this._deathModules;
-        const liveCount = this.liveCount;
-        for (let i = 0; i < liveCount; i++) {
-            if (alive[i] === 0)
-                continue;
-            elapsed[i] = elapsed[i] + dt;
-            if (elapsed[i] >= lifetime[i]) {
-                for (let m = 0; m < deathModules.length; m++) {
-                    deathModules[m].onDeath(this, i);
-                }
-                alive[i] = 0;
-                lifetime[i] = -1; // sentinel — GPU shader skips
-                this._gpuDirtySlots.add(i); // upload the sentinel so GPU sees the death
-            }
-        }
-        // Trim trailing dead slots.
-        let newLiveCount = this.liveCount;
-        while (newLiveCount > 0 && alive[newLiveCount - 1] === 0) {
-            newLiveCount--;
-        }
-        this.liveCount = newLiveCount;
-        // Push dirty slots (new spawns + just-expired) to GPU. CPU is NOT
-        // the source of truth for integrated position/velocity/etc. after
-        // spawn — uploading the full live range every frame would wipe
-        // out GPU's integrated state.
-        if (this._gpuDirtySlots.size > 0) {
-            this._gpuState.uploadDirty(this, this._gpuDirtySlots);
-            this._gpuDirtySlots.clear();
-        }
-        this._gpuState.dispatch(this, dt);
-    }
-    _copySlot(from, to) {
-        this.posX[to] = this.posX[from];
-        this.posY[to] = this.posY[from];
-        this.velX[to] = this.velX[from];
-        this.velY[to] = this.velY[from];
-        this.scaleX[to] = this.scaleX[from];
-        this.scaleY[to] = this.scaleY[from];
-        this.rotations[to] = this.rotations[from];
-        this.rotationSpeeds[to] = this.rotationSpeeds[from];
-        this.color[to] = this.color[from];
-        this.elapsed[to] = this.elapsed[from];
-        this.lifetime[to] = this.lifetime[from];
-        this.textureIndex[to] = this.textureIndex[from];
-    }
-}
+* The process-wide default render mode, created on first use.
+*
+* Every system constructed without `ParticleSystemOptions.render` draws with
+* this one instance. The backends key their GPU resources on the mode's
+* material, so sharing it means N systems cost one compiled program / pipeline
+* set, one vertex array object and one vertex buffer between them - what a
+* single system costs.
+*
+* Sharing the mode also shares its scratch buffer, which is safe because that
+* buffer is only live between a `build()` and the upload that immediately
+* follows it: the WebGL2 renderer flushes the pending system at the top of
+* every `render()` before building the next one, and the WebGPU renderer
+* copies the built bytes out through `queue.writeBuffer` before it moves on to
+* the next drawcall. That is exactly how the renderers behaved when each of
+* them owned one shared pack buffer for all systems.
+*
+* Never destroyed. It outlives every individual system (see
+* {@link ParticleSystem.destroy}), so a scene that destroys one system leaves
+* the others drawing and a system constructed afterwards reuses the already
+* compiled program instead of paying for a fresh one. The GPU resources behind
+* it are released by the backend when the renderer disconnects.
+*/
+let defaultRenderMode = null;
+const getDefaultRenderMode = () => {
+	defaultRenderMode ??= new QuadParticles();
+	return defaultRenderMode;
+};
+/**
+* The central coordinator of the particle pipeline. `ParticleSystem` is a
+* {@link Drawable} that owns:
+*
+* - **Particle storage** - one channel per attribute (position, velocity,
+*   scale, rotation, color, timing, ...), sized to a fixed capacity at
+*   construction. Modules and render modes address it by name through a
+*   {@link ParticleBatch}; user code brings particles into existence with
+*   {@link emit}.
+* - **Spawn modules** - fill freshly emitted particles.
+* - **Update modules** - mutate the live range each frame (forces, color
+*   blends, scale curves, drag, ...). Built-in modules ship both CPU and
+*   WGSL implementations; custom modules can opt into GPU acceleration by
+*   implementing `wgsl()`.
+* - **Death modules** - fire once per dying particle, before its slot is
+*   recycled (sub-emitters, event hooks).
+*
+* **Auto-routing CPU vs GPU:** at first {@link update}, the system checks:
+* if a `WebGpuBackend` was supplied AND every registered update module has
+* `wgsl()` AND the render mode is GPU-eligible, the GPU path engages - a
+* composite compute pipeline runs
+* integration plus all module bodies in one dispatch and writes directly
+* into the renderer's instance buffer (no CPU readback). Otherwise the CPU
+* path runs the existing per-module `apply()` loops.
+*
+* **Per-frame order in {@link update} (CPU mode):**
+* 1. Run every spawn module.
+* 2. Integrate position from velocity, rotation from rotationSpeed, advance `elapsed`.
+* 3. Run every update module on the live range.
+* 4. Compact: scan `[0, liveCount)` forward, fire death modules on expired
+*    slots, copy survivors down. `liveCount` shrinks to the survivor count.
+*
+* **Per-frame order in {@link update} (GPU mode):**
+* 1. Run every spawn module (CPU writes initial values into the spawn slot).
+* 2. Detect expiries on CPU (via `elapsed >= lifetime`); fire death modules;
+*    set `lifetime[slot] = -1` sentinel + clear `alive[slot]` so the GPU
+*    shader skips them. **No compaction** - slots are recycled on next spawn.
+* 3. Dispatch the composite compute pipeline. Integration + update modules
+*    + pack-instances run in one pass; the instance buffer is written
+*    directly. CPU SoA stays as-is for spawn writes.
+*
+* **Coordinate space:** particle positions are LOCAL to the system. The
+* system's `getGlobalTransform()` is applied on top during rendering - both
+* the WebGL2 and WebGPU shaders multiply `projection * translation * rotated`.
+* Setting world-space positions on individual particles double-translates.
+* Position the system itself via `system.setPosition(...)` and emit relative
+* to `(0, 0)`.
+*
+* **Pixel snapping:** {@link Drawable.pixelSnapMode} is intentionally ignored
+* for particle systems. Particle instances bake their own per-particle
+* transforms in the emitter/compute path rather than reading the shared
+* pixel-snap transform row, so a snap mode set on the system has no effect on
+* rendered output - snapping thousands of independently-moving sub-pixel
+* particles to the device grid is neither meaningful nor desirable.
+*
+* @example
+* // Backend-agnostic - runs CPU on WebGL2, GPU on WebGPU automatically.
+* const system = new ParticleSystem(loader.get('spark.png'), {
+*     capacity: 8192,
+* });
+*
+* system.addSpawnModule(new RateSpawn({ rate: new Constant(60), ... }));
+* system.addUpdateModule(new ApplyForce(0, 980));     // gravity, GPU-eligible
+* system.addUpdateModule(new ColorOverLifetime(fireGradient));
+* scene.addChild(system);
+*/
+var ParticleSystem = class extends Drawable {
+	/** Maximum particle count this system will store. Fixed at construction. */
+	capacity;
+	/**
+	* The simulation's channel storage. Handed to update modules and render modes
+	* as a {@link ParticleBatch}; never exposed as a property of the system,
+	* because outside those two callbacks its integrated values are not
+	* backend-true.
+	* @internal
+	*/
+	_storage;
+	_writer;
+	_spawnModules = [];
+	_updateModules = [];
+	_deathModules = [];
+	_backend = null;
+	_device = null;
+	_gpuState = null;
+	_gpuMode = false;
+	_compiled = false;
+	_spawnHint = 0;
+	/**
+	* In GPU mode, slots whose CPU SoA values need re-uploading to the GPU
+	* (newly spawned, or just-expired with lifetime sentinel). Cleared
+	* after each compute dispatch. CPU never overwrites integrated GPU
+	* state - only dirty slots flow CPU → GPU.
+	*/
+	_gpuDirtySlots = /* @__PURE__ */ new Set();
+	/**
+	* Spawn lifetimes, in death order per slot, of the particles that expired
+	* since the last batch the device staged for readback. The device's own
+	* record cannot carry them: by the time the shader sees the particle, the CPU
+	* has already overwritten its lifetime with the expiry sentinel. A slot can
+	* appear more than once when it is recycled and dies again before the batch
+	* is staged, so the lifetimes queue up per slot.
+	*/
+	_pendingDeathLifetimes = /* @__PURE__ */ new Map();
+	/** Total entries across `_pendingDeathLifetimes`, which is what the dispatch reports. */
+	_pendingDeathCount = 0;
+	/** Whether this system has already reported that its death backlog overflowed. */
+	_deathOverflowReported = false;
+	/**
+	* Slots handed out by `spawn()` while a recording window is open, or `null`
+	* when nothing is recording. Lets callers identify freshly spawned particles
+	* without diffing `liveCount`, which cannot see a recycled GPU slot.
+	*/
+	_spawnRecord = null;
+	_renderMode;
+	/** Whether {@link destroy} may destroy {@link _renderMode} - false for the shared default. */
+	_ownsRenderMode;
+	_texture;
+	_frames = [];
+	_textureFrame = new Rectangle();
+	_vertices = /* @__PURE__ */ new Float32Array(4);
+	_texCoords = /* @__PURE__ */ new Uint32Array(4);
+	_updateTexCoords = true;
+	_updateVertices = true;
+	constructor(sourceOrOptions, framesOrOptions, finalOptions) {
+		super();
+		let texture = null;
+		let frames = null;
+		let options;
+		if (sourceOrOptions instanceof Texture) {
+			texture = sourceOrOptions;
+			if (Array.isArray(framesOrOptions)) {
+				frames = framesOrOptions;
+				options = finalOptions ?? {};
+			} else options = framesOrOptions ?? {};
+		} else if (sourceOrOptions instanceof Spritesheet) {
+			texture = sourceOrOptions.texture;
+			frames = [...sourceOrOptions.frames.values()];
+			options = framesOrOptions ?? {};
+		} else options = sourceOrOptions ?? {};
+		const capacity = options.capacity ?? defaultCapacity;
+		if (capacity <= 0 || !Number.isInteger(capacity)) throw new Error(`ParticleSystem capacity must be a positive integer (got ${capacity}).`);
+		this.capacity = capacity;
+		this._storage = new ParticleStorage(capacity);
+		this._writer = new ParticleSlotWriter(this._storage);
+		this._device = options.device ?? null;
+		this._ownsRenderMode = options.render !== void 0;
+		this._renderMode = options.render ?? getDefaultRenderMode();
+		this._texture = texture ?? getDefaultWhiteTexture();
+		if (frames !== null) for (const frame of frames) this._frames.push(frame.clone());
+		this.resetTextureFrame();
+	}
+	/**
+	* The render mode this system's particles are drawn with. Fixed at
+	* construction via `ParticleSystemOptions.render`; the backend renderers
+	* read it every draw to learn the vertex layout, shader and draw model.
+	*
+	* Without that option this is the shared default mode - the same instance
+	* every other defaulted system draws with, so do not destroy it or mutate
+	* its material.
+	*/
+	get renderMode() {
+		return this._renderMode;
+	}
+	get texture() {
+		return this._texture;
+	}
+	set texture(texture) {
+		this.setTexture(texture);
+	}
+	get textureFrame() {
+		return this._textureFrame;
+	}
+	set textureFrame(frame) {
+		this.setTextureFrame(frame);
+	}
+	/**
+	* Atlas frames declared on this system, or empty when the texture is
+	* used as a single frame. Each particle's {@link textureIndex} selects
+	* an entry from this list; anything out of range shows frame 0.
+	*/
+	get frames() {
+		return this._frames;
+	}
+	/** `true` when the system declares more than one atlas frame. */
+	get hasAtlas() {
+		return this._frames.length > 1;
+	}
+	get vertices() {
+		if (this._updateVertices) {
+			const { x, y, width, height } = this._textureFrame;
+			const offsetX = width / 2;
+			const offsetY = height / 2;
+			this._vertices[0] = x - offsetX;
+			this._vertices[1] = y - offsetY;
+			this._vertices[2] = width - offsetX;
+			this._vertices[3] = height - offsetY;
+			this._updateVertices = false;
+		}
+		return this._vertices;
+	}
+	get texCoords() {
+		if (this._updateTexCoords) {
+			const { width, height } = this._texture;
+			const { left, top, right, bottom } = this._textureFrame;
+			const minX = left / width * 65535 & 65535;
+			const minY = (top / height * 65535 & 65535) << 16;
+			const maxX = right / width * 65535 & 65535;
+			const maxY = (bottom / height * 65535 & 65535) << 16;
+			if (this._texture.flipY) {
+				this._texCoords[0] = maxY | minX;
+				this._texCoords[1] = maxY | maxX;
+				this._texCoords[2] = minY | maxX;
+				this._texCoords[3] = minY | minX;
+			} else {
+				this._texCoords[0] = minY | minX;
+				this._texCoords[1] = minY | maxX;
+				this._texCoords[2] = maxY | maxX;
+				this._texCoords[3] = maxY | minX;
+			}
+			this._updateTexCoords = false;
+		}
+		return this._texCoords;
+	}
+	/** `true` when the system is running on the GPU compute pipeline. */
+	get gpuMode() {
+		return this._gpuMode;
+	}
+	/** GPU-side state, or `null` in CPU mode. */
+	get gpuState() {
+		return this._gpuState;
+	}
+	/**
+	* Upper bound of the slot range that can hold live particles.
+	*
+	* Exact on the CPU path: after each `update()` slots `[0, liveCount)` are all
+	* alive. On the GPU path it is a high-water mark whose range can contain dead
+	* holes that future emissions fill; {@link aliveCount} counts the live ones.
+	*/
+	get liveCount() {
+		return this._storage.count;
+	}
+	/** Actual count of live particles. May be below {@link liveCount} on the GPU path. */
+	get aliveCount() {
+		const { alive, count } = this._storage;
+		let live = 0;
+		for (let i = 0; i < count; i++) if (alive[i] === 1) live++;
+		return live;
+	}
+	get spawnModules() {
+		return this._spawnModules;
+	}
+	get updateModules() {
+		return this._updateModules;
+	}
+	get deathModules() {
+		return this._deathModules;
+	}
+	setTexture(texture) {
+		if (this._texture !== texture) {
+			this._texture = texture;
+			this.resetTextureFrame();
+		}
+		return this;
+	}
+	setTextureFrame(frame) {
+		this._textureFrame.copy(frame);
+		this._updateTexCoords = true;
+		this._updateVertices = true;
+		this._setLocalBounds(0, 0, frame.width, frame.height);
+		return this;
+	}
+	resetTextureFrame() {
+		return this.setTextureFrame(Rectangle.temp.set(0, 0, this._texture.width, this._texture.height));
+	}
+	addSpawnModule(mod) {
+		this._spawnModules.push(mod);
+		return this;
+	}
+	/**
+	* Registers an update module. Modules run in registration order, each seeing
+	* what the previous ones did.
+	*
+	* Modules may be added and removed at any time, including mid-flight: the
+	* next update rebuilds whatever the change invalidated. On the GPU path that
+	* is the compute program alone - live particles keep the state the device has
+	* been integrating. Adding a module without a `wgsl()` implementation to a
+	* running GPU system is the one change that cannot preserve them: the
+	* simulation moves to the CPU, which has no copy of the integrated state, so
+	* the system clears its live particles rather than continuing from stale
+	* values (see {@link clearParticles}).
+	*/
+	addUpdateModule(mod) {
+		this._updateModules.push(mod);
+		this._invalidateProgram();
+		return this;
+	}
+	addDeathModule(mod) {
+		const hadNone = this._deathModules.length === 0;
+		this._deathModules.push(mod);
+		if (hadNone) this._invalidateProgram();
+		return this;
+	}
+	clearSpawnModules() {
+		for (const mod of this._spawnModules) mod.destroy();
+		this._spawnModules.length = 0;
+		return this;
+	}
+	clearUpdateModules() {
+		for (const mod of this._updateModules) mod.destroy();
+		this._updateModules.length = 0;
+		this._invalidateProgram();
+		return this;
+	}
+	clearDeathModules() {
+		for (const mod of this._deathModules) mod.destroy();
+		this._deathModules.length = 0;
+		this._invalidateProgram();
+		return this;
+	}
+	/**
+	* Brings one particle into existence and returns a writer for its initial
+	* values, or `null` when the system is at {@link capacity}.
+	*
+	* The particle starts at the spawn defaults - origin, no velocity, unit
+	* scale, no rotation, opaque white, frame 0, one second of life - so a caller
+	* writes only what it varies. The returned writer is a cursor that the next
+	* `emit()` rebinds, so it must not be stored.
+	*
+	* Emission is the only per-particle write that is true on every backend:
+	* spawn values originate on the CPU and are uploaded from there, while
+	* everything the simulation integrates afterwards lives wherever the
+	* simulation runs.
+	*
+	* @example
+	* ```ts
+	* const particle = system.emit();
+	*
+	* if (particle) {
+	*     particle.position.set(120, 40);
+	*     particle.velocity.set(0, -80);
+	*     particle.lifetime = 2;
+	* }
+	* ```
+	*/
+	emit() {
+		const slot = this._spawnSlot();
+		if (slot < 0) return null;
+		return this._writer.bind(slot);
+	}
+	/**
+	* Allocates one slot at the spawn defaults and returns its index, or `-1` at
+	* capacity. Backs {@link emit}; the simulation's own machinery addresses
+	* particles by slot, the public surface does not.
+	* @internal
+	*/
+	_spawnSlot() {
+		const slot = this._gpuMode ? this._spawnGpu() : this._spawnCpu();
+		if (slot >= 0) this._storage.reset(slot);
+		return slot;
+	}
+	/**
+	* Begin recording the slots handed out by {@link spawn}.
+	*
+	* Callers that post-process freshly spawned particles cannot infer which
+	* slots those are from {@link liveCount}: in GPU mode a spawn may recycle a
+	* dead slot below the high-water mark, leaving the count unchanged, and the
+	* reused slots are scattered rather than contiguous. Pass the returned token
+	* back to {@link _endSpawnRecording}.
+	*
+	* @internal
+	*/
+	_beginSpawnRecording() {
+		const previous = this._spawnRecord;
+		this._spawnRecord = [];
+		return previous;
+	}
+	/**
+	* End the recording started by {@link _beginSpawnRecording} and return the
+	* slots allocated during it. Slots are also handed to an enclosing recording
+	* so a nested spawn stays visible to the outer window.
+	*
+	* @internal
+	*/
+	_endSpawnRecording(previous) {
+		const recorded = this._spawnRecord ?? [];
+		this._spawnRecord = previous;
+		if (previous !== null) for (const slot of recorded) previous.push(slot);
+		return recorded;
+	}
+	/**
+	* Shifts the particles a sub-emitter just produced by `(x, y)`, so a child
+	* spawner's distributions read as offsets from the death position.
+	* @internal
+	*/
+	_offsetSpawned(slots, x, y) {
+		const { posX, posY } = this._storage;
+		for (const slot of slots) {
+			posX[slot] = posX[slot] + x;
+			posY[slot] = posY[slot] + y;
+		}
+	}
+	/** Resets the system to zero live particles without destroying it. */
+	clearParticles() {
+		const storage = this._storage;
+		storage.count = 0;
+		this._spawnHint = 0;
+		storage.alive.fill(0);
+		storage.lifetime.fill(0);
+		storage.elapsed.fill(0);
+		return this;
+	}
+	/**
+	* @internal
+	*
+	* Collect-hook: captures the active backend before this node is emitted so
+	* the next `update()` can compile a GPU pipeline if the backend turned out
+	* to be `WebGpuBackend`. Re-captures and rebuilds when the backend
+	* reference changes (e.g. after device-loss recovery).
+	*/
+	/** @internal */
+	_collect(builder, seq) {
+		const backend = builder.backend;
+		if (this._backend !== backend) {
+			this._backend = backend;
+			if (this._gpuState !== null) {
+				this._gpuState.destroy();
+				this._gpuState = null;
+			}
+			this._gpuMode = false;
+			this._compiled = false;
+		}
+		super._collect(builder, seq);
+	}
+	/** Per-frame entry point. Routes to CPU or GPU pipeline based on auto-detection at first call. */
+	update(delta) {
+		if (!this._compiled) this._compile();
+		const dt = delta;
+		for (let i = 0; i < this._spawnModules.length; i++) this._spawnModules[i].apply(this, dt);
+		if (this._gpuMode) this._updateGpu(dt);
+		else this._updateCpu(dt);
+		return this;
+	}
+	destroy() {
+		super.destroy();
+		this.clearSpawnModules();
+		this.clearUpdateModules();
+		this.clearDeathModules();
+		if (this._ownsRenderMode) this._renderMode.destroy();
+		if (this._gpuState !== null) {
+			this._gpuState.destroy();
+			this._gpuState = null;
+		}
+		for (const frame of this._frames) frame.destroy();
+		this._frames.length = 0;
+		this._gpuMode = false;
+		this._compiled = false;
+		this._storage.count = 0;
+		this._storage.alive.fill(0);
+		this._textureFrame.destroy();
+	}
+	/**
+	* Marks the compiled program stale. The next update decides what that costs:
+	* a GPU system that stays GPU-eligible rebuilds only its program, everything
+	* else follows the transition rules in {@link _compile}.
+	*/
+	_invalidateProgram() {
+		this._compiled = false;
+	}
+	_compile() {
+		this._compiled = true;
+		const eligible = this._updateModules.every((m) => typeof m.wgsl === "function") && this._renderMode.gpuEligible;
+		if (this._gpuState !== null) {
+			if (eligible) {
+				this._gpuState.setProgram(this._updateModules, this._deathModules.length > 0);
+				return;
+			}
+			this._gpuState.destroy();
+			this._gpuState = null;
+			this._gpuMode = false;
+			this._gpuDirtySlots.clear();
+			this.clearParticles();
+			return;
+		}
+		const backendDevice = this._backend?.device ?? null;
+		const device = this._device ?? backendDevice;
+		if (device === null) return;
+		if (!eligible) return;
+		this._gpuState = new ParticleGpuState(device, this.capacity, this._updateModules, this._frames, this._texture, this._deathModules.length > 0);
+		this._gpuMode = true;
+		const { alive, count } = this._storage;
+		for (let i = 0; i < count; i++) if (alive[i] === 1) this._gpuDirtySlots.add(i);
+	}
+	_spawnCpu() {
+		const storage = this._storage;
+		if (storage.count >= this.capacity) return -1;
+		const slot = storage.count++;
+		storage.alive[slot] = 1;
+		this._spawnRecord?.push(slot);
+		return slot;
+	}
+	_spawnGpu() {
+		const capacity = this.capacity;
+		const alive = this._storage.alive;
+		const start = this._spawnHint;
+		for (let i = start; i < capacity; i++) if (alive[i] === 0) return this._claimGpuSlot(i, i + 1 === capacity ? 0 : i + 1);
+		for (let i = 0; i < start; i++) if (alive[i] === 0) return this._claimGpuSlot(i, i + 1);
+		return -1;
+	}
+	_claimGpuSlot(slot, nextHint) {
+		const storage = this._storage;
+		storage.alive[slot] = 1;
+		this._spawnHint = nextHint;
+		if (slot >= storage.count) storage.count = slot + 1;
+		this._gpuDirtySlots.add(slot);
+		this._spawnRecord?.push(slot);
+		return slot;
+	}
+	_updateCpu(dt) {
+		const storage = this._storage;
+		const { posX, posY, velX, velY, rotations, rotationSpeeds, elapsed, lifetime, alive } = storage;
+		const liveCount = storage.count;
+		for (let i = 0; i < liveCount; i++) {
+			posX[i] = posX[i] + velX[i] * dt;
+			posY[i] = posY[i] + velY[i] * dt;
+			rotations[i] = rotations[i] + rotationSpeeds[i] * dt;
+			elapsed[i] = elapsed[i] + dt;
+		}
+		for (let i = 0; i < this._updateModules.length; i++) this._updateModules[i].apply(storage, dt);
+		const deathModules = this._deathModules;
+		let writeIndex = 0;
+		for (let readIndex = 0; readIndex < storage.count; readIndex++) {
+			if (elapsed[readIndex] >= lifetime[readIndex]) {
+				if (deathModules.length > 0) this._reportDeath(storage.snapshot(readIndex));
+				alive[readIndex] = 0;
+				continue;
+			}
+			if (writeIndex !== readIndex) {
+				storage.copySlot(readIndex, writeIndex);
+				alive[writeIndex] = 1;
+			}
+			writeIndex++;
+		}
+		for (let i = writeIndex; i < storage.count; i++) alive[i] = 0;
+		storage.count = writeIndex;
+	}
+	/** Hands one death snapshot to every registered death module, in registration order. */
+	_reportDeath(death) {
+		const deathModules = this._deathModules;
+		for (let m = 0; m < deathModules.length; m++) deathModules[m].onDeath(this, death);
+	}
+	_updateGpu(dt) {
+		const storage = this._storage;
+		const { elapsed, lifetime, alive } = storage;
+		const liveCount = storage.count;
+		const reportsDeaths = this._deathModules.length > 0;
+		for (let i = 0; i < liveCount; i++) {
+			if (alive[i] === 0) continue;
+			elapsed[i] = elapsed[i] + dt;
+			if (elapsed[i] >= lifetime[i]) {
+				if (reportsDeaths) {
+					const queued = this._pendingDeathLifetimes.get(i);
+					if (queued === void 0) this._pendingDeathLifetimes.set(i, [lifetime[i]]);
+					else queued.push(lifetime[i]);
+					this._pendingDeathCount++;
+				}
+				alive[i] = 0;
+				lifetime[i] = -1;
+				this._gpuDirtySlots.delete(i);
+				this._gpuState.uploadExpiry(i);
+			}
+		}
+		if (this._gpuDirtySlots.size > 0) {
+			this._gpuState.uploadDirty(this, this._gpuDirtySlots);
+			this._gpuDirtySlots.clear();
+		}
+		const staged = this._gpuState.dispatch(dt, liveCount, this._pendingDeathCount);
+		let newLiveCount = storage.count;
+		while (newLiveCount > 0 && alive[newLiveCount - 1] === 0) newLiveCount--;
+		storage.count = newLiveCount;
+		if (staged) {
+			const pending = this._pendingDeathLifetimes;
+			this._pendingDeathLifetimes = /* @__PURE__ */ new Map();
+			this._pendingDeathCount = 0;
+			this._drainDeaths(pending);
+		}
+	}
+	/**
+	* Delivers a staged batch of deaths once its readback has landed. Each record
+	* carries what the device integrated; the lifetime comes from the CPU, which
+	* is where it was written at spawn.
+	*/
+	async _drainDeaths(pending) {
+		await this._gpuState?.readDeaths((records) => {
+			for (const record of records) this._reportDeath({
+				x: record.x,
+				y: record.y,
+				velocityX: record.velocityX,
+				velocityY: record.velocityY,
+				rotation: record.rotation,
+				scaleX: record.scaleX,
+				scaleY: record.scaleY,
+				color: record.color,
+				elapsed: record.elapsed,
+				lifetime: pending.get(record.slot)?.shift() ?? 0
+			});
+		});
+	}
+};
 
+//#endregion
 export { ParticleSystem };
-//# sourceMappingURL=ParticleSystem.js.map
+//# sourceMappingURL=ParticleSystem.js.map