@codexo/exojs 0.7.12 → 0.8.0

package/dist/esm/particles/ParticleSystem.d.ts

@@ -1,112 +1,209 @@
-import { Particle } from './Particle';
 import { Rectangle } from '@/math/Rectangle';
 import type { Time } from '@/core/Time';
 import { Drawable } from '@/rendering/Drawable';
-import type { Texture } from '@/rendering/texture/Texture';
-import type { ParticleEmitter } from '@/particles/emitters/ParticleEmitter';
-import type { ParticleAffector } from '@/particles/affectors/ParticleAffector';
+import { Texture } from '@/rendering/texture/Texture';
+import type { RenderBackend } from '@/rendering/RenderBackend';
+import { Spritesheet } from '@/rendering/sprite/Spritesheet';
+import type { SpawnModule } from './modules/SpawnModule';
+import type { UpdateModule } from './modules/UpdateModule';
+import type { DeathModule } from './modules/DeathModule';
+import { ParticleGpuState } from './gpu/ParticleGpuState';
 /**
- * The central coordinator of the particle triad. `ParticleSystem` is a
- * {@link Drawable} that owns a list of {@link ParticleEmitter} spawners, a
- * list of {@link ParticleAffector} mutators, and the live/graveyard particle
- * pools. Each call to {@link ParticleSystem.update} runs all emitters to
- * spawn new particles, advances every live particle's position and lifetime,
- * retires expired ones to the graveyard for pooling, and runs all affectors
- * on the survivors.
+ * Options for {@link ParticleSystem}'s constructor — orthogonal config
+ * that's independent of the texture source. Texture / frames / spritesheet
+ * live in positional arguments to enforce mutual exclusivity at the type
+ * level (you can't pass both a texture and a spritesheet by accident).
+ */
+export interface ParticleSystemOptions {
+    /** Maximum particle count. Fixed at construction. Default 4096. */
+    capacity?: number;
+    /**
+     * Direct GPU device. Lets advanced consumers wire a `GPUDevice` owned
+     * outside an `Application` (or a mock device in tests). When omitted,
+     * the backend reference is captured automatically on the first
+     * {@link ParticleSystem.render} call — `WebGpuBackend` ⇒ GPU mode,
+     * anything else (incl. WebGL2) ⇒ CPU mode.
+     */
+    device?: GPUDevice;
+}
+/**
+ * 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.
  *
- * Rendering reads {@link ParticleSystem.vertices} and
- * {@link ParticleSystem.texCoords} (lazily recomputed on texture-frame
- * changes) plus the live {@link ParticleSystem.particles} array to draw each
- * sprite.
+ * **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,
+ *     backend: app.backend,
+ * });
+ *
+ * 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);
  */
 export declare class ParticleSystem extends Drawable {
-    private _emitters;
-    private _affectors;
-    private _particles;
-    private _graveyard;
+    /** Maximum particle count this system will store. Fixed at construction. */
+    readonly capacity: number;
+    readonly posX: Float32Array;
+    readonly posY: Float32Array;
+    readonly velX: Float32Array;
+    readonly velY: Float32Array;
+    readonly scaleX: Float32Array;
+    readonly scaleY: Float32Array;
+    readonly rotations: Float32Array;
+    readonly rotationSpeeds: Float32Array;
+    readonly color: Uint32Array;
+    readonly elapsed: Float32Array;
+    readonly lifetime: Float32Array;
+    readonly textureIndex: Uint16Array;
+    /**
+     * 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: number;
+    /**
+     * 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.
+     */
+    readonly alive: Uint8Array;
+    private readonly _spawnModules;
+    private readonly _updateModules;
+    private readonly _deathModules;
+    private _backend;
+    private readonly _device;
+    private _gpuState;
+    private _gpuMode;
+    private _compiled;
+    private _spawnHint;
+    /**
+     * 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.
+     */
+    private readonly _gpuDirtySlots;
     private _texture;
-    private _textureFrame;
-    private _vertices;
-    private _texCoords;
+    private readonly _frames;
+    private readonly _textureFrame;
+    private readonly _vertices;
+    private readonly _texCoords;
     private _updateTexCoords;
     private _updateVertices;
-    constructor(texture: Texture);
+    /** No texture — particles render as solid-color quads on a 1×1 white default. */
+    constructor(options?: ParticleSystemOptions);
+    /** Single texture, no atlas — every particle uses the full texture as one frame. */
+    constructor(texture: Texture, options?: ParticleSystemOptions);
+    /** Multi-frame atlas — each particle's `textureIndex` selects a frame. */
+    constructor(texture: Texture, frames: ReadonlyArray<Rectangle>, options?: ParticleSystemOptions);
+    /** Spritesheet shorthand — texture + frames pulled from the sheet. */
+    constructor(spritesheet: Spritesheet, options?: ParticleSystemOptions);
     get texture(): Texture;
     set texture(texture: Texture);
     get textureFrame(): Rectangle;
     set textureFrame(frame: Rectangle);
     /**
-     * Quad corner offsets for the current {@link textureFrame}, in local
-     * space as `[minX, minY, maxX, maxY]`. Recomputed lazily whenever
-     * `textureFrame` changes. Used by the renderer to position each particle
-     * sprite relative to its world position.
+     * 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(): ReadonlyArray<Rectangle>;
+    /** `true` when the system declares more than one atlas frame. */
+    get hasAtlas(): boolean;
     get vertices(): Float32Array;
-    /**
-     * Packed UV coordinates for the current {@link textureFrame} as four
-     * `Uint32` values, each encoding a `(u, v)` pair in the upper/lower 16
-     * bits (normalised to 0–65535). Vertex order respects
-     * {@link Texture.flipY}. Recomputed lazily on texture or frame changes.
-     */
     get texCoords(): Uint32Array;
-    get emitters(): Array<ParticleEmitter>;
-    get affectors(): Array<ParticleAffector>;
-    get particles(): Array<Particle>;
-    /**
-     * Pool of expired {@link Particle} instances waiting to be recycled.
-     * {@link requestParticle} pops from this array before allocating a new
-     * instance, keeping GC pressure low during sustained emission.
-     */
-    get graveyard(): Array<Particle>;
-    /**
-     * Replaces the particle sprite texture and resets the texture frame to
-     * cover the full new texture. No-ops if `texture` is the same instance.
-     */
+    /** `true` when the system is running on the GPU compute pipeline. */
+    get gpuMode(): boolean;
+    /** GPU-side state, or `null` in CPU mode. */
+    get gpuState(): ParticleGpuState | null;
+    /** Actual count of live particles (slots with `alive[i] === 1`). May differ from `liveCount` in GPU mode. */
+    get aliveCount(): number;
+    get spawnModules(): ReadonlyArray<SpawnModule>;
+    get updateModules(): ReadonlyArray<UpdateModule>;
+    get deathModules(): ReadonlyArray<DeathModule>;
     setTexture(texture: Texture): this;
-    /**
-     * Sets the sub-rectangle of the texture used as the particle sprite,
-     * invalidating cached vertices and UV coordinates and updating the system's
-     * local bounds to match the frame dimensions.
-     */
     setTextureFrame(frame: Rectangle): this;
-    /** Resets the texture frame to the full dimensions of the current texture. */
     resetTextureFrame(): this;
-    /** Registers `emitter` to be called each tick during {@link update}. */
-    addEmitter(emitter: ParticleEmitter): this;
-    /** Destroys and removes all registered emitters. */
-    clearEmitters(): this;
-    /** Registers `affector` to run on every live particle each tick during {@link update}. */
-    addAffector(affector: ParticleAffector): this;
-    /** Destroys and removes all registered affectors. */
-    clearAffectors(): this;
-    /**
-     * Returns a recycled particle from the {@link graveyard}, or allocates a
-     * new one if the pool is empty. Call {@link Particle.applyOptions}
-     * immediately after to reset its state before passing it to
-     * {@link emitParticle}.
-     */
-    requestParticle(): Particle;
-    /** Adds a fully-configured `particle` to the live pool. Typically called by emitters. */
-    emitParticle(particle: Particle): this;
-    /**
-     * Advances a single particle by one `delta` step: increments
-     * `elapsedLifetime`, integrates velocity into position, and applies
-     * `rotationSpeed` to rotation. Called for every live particle by
-     * {@link update} before the affector pass.
-     */
-    updateParticle(particle: Particle, delta: Time): this;
+    addSpawnModule(mod: SpawnModule): this;
+    addUpdateModule(mod: UpdateModule): this;
+    addDeathModule(mod: DeathModule): this;
+    clearSpawnModules(): this;
+    clearUpdateModules(): this;
+    clearDeathModules(): this;
     /**
-     * Destroys and removes all particles from both the live pool and the
-     * graveyard. Use when resetting or recycling the entire system.
+     * 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(): number;
+    /** Resets the system to zero live particles without destroying it. */
     clearParticles(): this;
     /**
-     * Advances the full simulation by one `delta` step: runs all emitters,
-     * then for each live particle calls {@link updateParticle}, moves expired
-     * ones to the {@link graveyard}, and runs all affectors on survivors.
-     * The particle array is iterated in reverse to allow in-place splice
-     * without re-indexing.
+     * Engine-side render hook. Captures the active backend on each call 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).
      */
+    render(backend: RenderBackend): this;
+    /** Per-frame entry point. Routes to CPU or GPU pipeline based on auto-detection at first call. */
     update(delta: Time): this;
     destroy(): void;
+    private _compile;
+    private _spawnCpu;
+    private _spawnGpu;
+    private _updateCpu;
+    private _updateGpu;
+    private _copySlot;
 }