@codexo/exojs-particles 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codexo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @codexo/exojs-particles
+
+Official ExoJS extension for GPU-accelerated particle systems.
+
+## Installation
+
+```sh
+npm install @codexo/exojs @codexo/exojs-particles
+```
+
+This package requires `@codexo/exojs` as a peer dependency. Both must be the same version.
+
+## Core compatibility
+
+| `@codexo/exojs-particles` | `@codexo/exojs` |
+|---|---|
+| 0.12.x | 0.12.x |
+
+## Usage — side-effect-free root entry
+
+Import `ParticleSystem` and supply it explicitly to your Application via `extensions`:
+
+```ts
+import { Application } from '@codexo/exojs';
+import { ParticleSystem, particlesExtension } from '@codexo/exojs-particles';
+
+const app = new Application({
+    extensions: [particlesExtension],
+});
+```
+
+Importing from the root entry (`@codexo/exojs-particles`) does **not** register the extension globally. You control exactly which Applications receive the Particles extension.
+
+## Extension descriptor
+
+`particlesExtension` is the default descriptor. Use it when you want the default renderer batch size:
+
+```ts
+import { particlesExtension } from '@codexo/exojs-particles';
+
+const app = new Application({ extensions: [particlesExtension] });
+```
+
+## Custom batch size via `createParticlesExtension`
+
+```ts
+import { createParticlesExtension } from '@codexo/exojs-particles';
+
+const app = new Application({
+    extensions: [createParticlesExtension({ batchSize: 8192 })],
+});
+```
+
+## `ApplicationOptions.extensions`
+
+Pass any combination of descriptors:
+
+```ts
+const app = new Application({
+    extensions: [particlesExtension],
+});
+```
+
+## `/register` convenience entry
+
+Importing `/register` registers the default `particlesExtension` descriptor in the global `ExtensionRegistry`. Subsequently created Applications that use global defaults will automatically receive the Particles extension. This is the only side-effectful entry in this package.
+
+```ts
+// Side effect: registers particlesExtension in the global ExtensionRegistry.
+import '@codexo/exojs-particles/register';
+
+// All named exports are re-exported from /register:
+import { ParticleSystem, particlesExtension } from '@codexo/exojs-particles/register';
+```
+
+**Note:** `/register` does not use automatic discovery. It explicitly calls `ExtensionRegistry.register(particlesExtension)` at module evaluation time.
+
+## Minimal working example
+
+```ts
+import { Application, Scene, Texture } from '@codexo/exojs';
+import {
+    ParticleSystem,
+    particlesExtension,
+    RateSpawn,
+    Constant,
+} from '@codexo/exojs-particles';
+
+const app = new Application({ extensions: [particlesExtension] });
+document.body.append(app.canvas);
+
+class DemoScene extends Scene {
+    system!: ParticleSystem;
+
+    override async load(loader) {
+        await loader.load(Texture, { particle: '/particle.png' });
+    }
+
+    override create(loader) {
+        this.system = new ParticleSystem(loader.get(Texture, 'particle'), {
+            capacity: 1024,
+        });
+        this.system.addSpawnModule(
+            new RateSpawn({ rate: new Constant(120), lifetime: new Constant(2) }),
+        );
+        this.addChild(this.system);
+    }
+}
+
+app.scenes.start(DemoScene);
+```
+
+## WebGL2 and WebGPU support
+
+- **WebGL2**: full instanced-draw renderer
+- **WebGPU**: compute-shader GPU simulation when a WebGPU device is available; falls back to CPU simulation otherwise
+
+## Destruction and ownership
+
+`ParticleSystem` owns its GPU resources. Call `system.destroy()` when you are done with it. The `Application` or parent scene does not automatically destroy nested systems.
+
+## Links
+
+- [Official ExoJS Particles guide](https://exojs.dev/guides/extensions/particles)
+- [API reference](https://exojs.dev/api/exojs-particles)
+
+## License
+
+MIT

package/dist/esm/ParticleSystem.d.ts

@@ -0,0 +1,212 @@
+import type { Time } from '@codexo/exojs';
+import { Rectangle } from '@codexo/exojs';
+import { Drawable } from '@codexo/exojs';
+import type { RenderPlanBuilder } from '@codexo/exojs/rendering';
+import { Spritesheet } from '@codexo/exojs';
+import { Texture } from '@codexo/exojs';
+import { ParticleGpuState } from '#gpu/ParticleGpuState';
+import type { DeathModule } from '#modules/DeathModule';
+import type { SpawnModule } from '#modules/SpawnModule';
+import type { UpdateModule } from '#modules/UpdateModule';
+/**
+ * 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.
+ *
+ * **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 {
+    /** 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 readonly _frames;
+    private readonly _textureFrame;
+    private readonly _vertices;
+    private readonly _texCoords;
+    private _updateTexCoords;
+    private _updateVertices;
+    /** 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: readonly 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);
+    /**
+     * 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(): readonly Rectangle[];
+    /** `true` when the system declares more than one atlas frame. */
+    get hasAtlas(): boolean;
+    get vertices(): Float32Array;
+    get texCoords(): Uint32Array;
+    /** `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(): readonly SpawnModule[];
+    get updateModules(): readonly UpdateModule[];
+    get deathModules(): readonly DeathModule[];
+    setTexture(texture: Texture): this;
+    setTextureFrame(frame: Rectangle): this;
+    resetTextureFrame(): this;
+    addSpawnModule(mod: SpawnModule): this;
+    addUpdateModule(mod: UpdateModule): this;
+    addDeathModule(mod: DeathModule): this;
+    clearSpawnModules(): this;
+    clearUpdateModules(): this;
+    clearDeathModules(): 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(): number;
+    /** Resets the system to zero live particles without destroying it. */
+    clearParticles(): 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: RenderPlanBuilder, seq?: number): void;
+    /** 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;
+}