@codexo/exojs 0.7.13 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,409 @@ All notable changes to ExoJS are documented in this file.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-05-07
+
+Wholesale rewrite of the particle subsystem around a data-oriented core
+plus a backend-agnostic auto-routing pipeline. The `Particle` class,
+`ParticleAffector` interface, `ParticleEmitter` interface,
+`ParticleOptions`, `UniversalEmitter`, and the four built-in affectors
+(`ColorAffector`, `ForceAffector`, `ScaleAffector`, `TorqueAffector`)
+are removed. They are replaced by SoA storage on the system,
+`Distribution<T>`-based spawn configs, and per-batch
+`SpawnModule` / `UpdateModule` / `DeathModule` interfaces.
+
+Update modules now declare an optional `wgsl()` contribution — when
+the system is constructed with a `WebGpuBackend` and every registered
+update module is GPU-eligible (i.e. all built-ins, plus any custom
+modules the author opts in), a composite WGSL compute shader is built
+at first `update()`. Integration + every module body + pack-instances
+all run in **one dispatch**, writing directly into the renderer's
+instance vertex buffer. **No CPU readback** in the steady state.
+
+On WebGL2 backends, or when any registered update module lacks
+`wgsl()`, the system runs the existing CPU pipeline. The decision is
+automatic and per-system; user code is unchanged across both paths.
+
+### Added — Struct-of-Arrays storage
+
+`ParticleSystem` now stores particles as parallel `Float32Array` /
+`Uint32Array` / `Uint16Array` channels addressed by slot index:
+
+```ts
+system.posX[slot]
+system.posY[slot]
+system.velX[slot]
+system.velY[slot]
+system.scaleX[slot]
+system.scaleY[slot]
+system.rotations[slot]
+system.rotationSpeeds[slot]
+system.color[slot]            // packed 0xAABBGGRR
+system.elapsed[slot]
+system.lifetime[slot]
+system.textureIndex[slot]
+system.liveCount              // [0, liveCount) is the live range
+```
+
+Capacity is fixed at construction (default 4096) — no reallocations.
+The integrate pass runs as one tight loop over typed arrays with no
+method calls. Expiry is handled by forward-compaction (O(n) total
+instead of the previous O(n²) splice loop with scattered expirations).
+
+### Added — `Distribution<T>` family
+
+Spawn-time random sampling and lifetime-parameterised evaluation:
+
+| Type | Use |
+|---|---|
+| `Constant<T>` | Always-same value |
+| `Range` | Uniform random number in `[min, max]` |
+| `VectorRange` | Per-axis random vector |
+| `ConeDirection` | Random unit vector in a cone × speed range |
+| `CircleArea` | Random point in/on a circle |
+| `BoxArea` | Random point in/on an AABB |
+| `LineSegment` | Random point on a segment |
+| `Curve` | Piecewise-linear keyframe scalar by lifetime ratio |
+| `Gradient` | Piecewise-linear keyframe color, with `evaluateRgba()` for direct u32 packing |
+
+`Curve` and `Gradient` cache the last segment so monotonically
+advancing `t` (the typical case for per-particle lifetime sampling)
+is O(1) amortised.
+
+### Added — Module pipeline
+
+Three module bases. Each registered on a system via the corresponding
+`addX` method; each runs in its declared phase per-frame.
+
+```ts
+abstract class SpawnModule  { apply(system, dt: number): void; }
+abstract class UpdateModule { apply(system, dt: number): void; }
+abstract class DeathModule  { onDeath(system, slot: number): void; }
+```
+
+**Built-in spawn modules:**
+
+- `RateSpawn({ rate, lifetime?, position?, velocity?, scale?, rotation?, rotationSpeed?, tint?, textureIndex? })`
+  — continuous emission with sub-frame accumulator. Each property is an
+  independent `Distribution<T>`.
+- `BurstSpawn({ schedule, loop?, ...samePropsAsRate })` — discrete
+  bursts at scheduled times. Use for explosions, level-ups,
+  hit-impacts.
+
+**Built-in update modules** (operate on the SoA arrays in tight loops):
+
+- `ApplyForce(ax, ay)` — adds constant acceleration.
+- `Drag(coefficient)` — exponential velocity damping.
+- `ColorOverLifetime(gradient)` — tint sampled from a `Gradient`.
+- `ScaleOverLifetime(curve)` — both axes sampled from a `Curve`.
+- `RotateOverLifetime(angularAccel)` — increments `rotationSpeed`.
+
+**Built-in death module:**
+
+- `SpawnOnDeath(targetSystem, spawner, count?)` — sub-emitter. Forwards
+  the dying particle's position to a target system's spawn module.
+  Use for explosion-on-impact, end-of-life sparks, multi-stage VFX.
+
+### Added — Backend-agnostic auto-routing GPU compute pipeline
+
+New `src/rendering/webgpu/compute/` infrastructure:
+
+- `WebGpuStorageBuffer` — owning wrapper over a `STORAGE | COPY_DST | COPY_SRC`
+  buffer with `write()` and async `read()` helpers.
+- `WebGpuComputePipeline` — `device.createComputePipeline` wrapper with
+  bind-group-layout creation, dispatch helper.
+
+New `src/particles/gpu/ParticleGpuState` — owns the GPU-side mirror
+for one `ParticleSystem`. At construction time it:
+
+1. Walks the registered update modules, collecting each module's
+   `WgslContribution` (uniform field declarations + texture bindings
+   + WGSL body snippet).
+2. Generates a composite WGSL compute shader: SoA storage bindings +
+   sim/module uniform structs + module texture bindings + a `main`
+   function containing integration → all module bodies in registration
+   order → pack-instances writing interleaved 24-byte instances into
+   a `STORAGE | VERTEX` buffer.
+3. Allocates 7 packed storage buffers (positions/velocities/scales/
+   rotInfo/timing as `vec2<f32>` arrays plus color as `u32` plus the
+   instance output) — fits within WebGPU's default
+   `maxStorageBuffersPerShaderStage = 8` limit.
+4. Allocates 1D textures for any module that declares them
+   (`Curve` → 256-tap r32float; `Gradient` → 256-tap rgba8unorm) and
+   uploads the lookup data once via `module.uploadTextures()`.
+5. Each module's `writeUniforms()` runs every frame to update its
+   slice of the shared module-uniform buffer.
+
+The `WebGpuParticleRenderer` reads the GPU-written instance buffer
+directly when `system.gpuMode` is true; CPU mode falls back to the
+existing CPU-pack path. Same renderer, same vertex layout, no copy
+between simulation and render.
+
+`UpdateModule` gains optional `wgsl()`, `writeUniforms()`,
+`uploadTextures()`. Built-in modules ship all three. Custom modules
+that implement them get GPU acceleration; modules with only `apply()`
+keep working but force their host system into CPU mode.
+
+Opt-in is a single constructor option — no imperative toggle:
+
+```ts
+const system = new ParticleSystem(texture, {
+    capacity: 8192,
+    backend: app.backend,    // CPU-routed on WebGL2, GPU-routed on WebGPU
+});
+```
+
+The `backend` reference is duck-typed against `WebGpuBackend`; on
+WebGL2 it's recorded but never used. The system's mode is locked in
+at the first `update()` (when modules are introspected); adding update
+modules after that throws.
+
+### Removed — Old particle API (BREAKING)
+
+The following symbols are deleted. Migration recipes follow the table.
+
+| Removed | Replacement |
+|---|---|
+| `Particle` (class) | SoA arrays on `ParticleSystem` (`system.posX[slot]`, etc.) |
+| `ParticleProperties` (interface) | None — slot-indexed arrays replace the per-particle object |
+| `ParticleEmitter` (interface) | `SpawnModule` (abstract class) |
+| `ParticleOptions` | Per-property `Distribution<T>` in the spawn module's config |
+| `UniversalEmitter` | `RateSpawn` |
+| `ParticleAffector` (interface) | `UpdateModule` (abstract class) |
+| `ColorAffector` | `ColorOverLifetime` + `Gradient` |
+| `ForceAffector` | `ApplyForce` |
+| `ScaleAffector` | `ScaleOverLifetime` + `Curve` |
+| `TorqueAffector` | `RotateOverLifetime` |
+| `system.requestParticle()` | `system.spawn(): number` (slot index, or `-1` at capacity) |
+| `system.emitParticle(p)` | (gone — `spawn()` already commits the slot to the live range) |
+| `system.updateParticle(p, dt)` | (gone — internal to `update()`) |
+| `system.addEmitter(e)` | `system.addSpawnModule(m)` |
+| `system.addAffector(a)` | `system.addUpdateModule(m)` |
+| `system.particles` (`Array<Particle>`) | `system.posX` / `system.posY` / ... `system.liveCount` |
+| `system.graveyard` | (gone — no graveyard; slots are recycled in place) |
+
+### Migration
+
+```ts
+// Before — bonfire
+const options = new ParticleOptions();
+const colorAffector = new ColorAffector(new Color(194, 64, 30, 1), new Color(0, 0, 0, 0));
+const emitter = new UniversalEmitter(50, options);
+const system = new ParticleSystem(texture);
+system.addAffector(colorAffector);
+system.addEmitter(emitter);
+
+// in update():
+options.totalLifetime.copy(seconds(rand(5, 10)));
+options.position.set(rand(-50, 50), rand(-10, 10));
+options.velocity.set(/* ... */);
+
+// After — bonfire
+const system = new ParticleSystem(texture);
+system.addSpawnModule(new RateSpawn({
+    rate: new Constant(50),
+    lifetime: new Range(5, 10),
+    position: new VectorRange(-50, 50, -10, 10),
+    velocity: new ConeDirection(-Math.PI / 2, Math.PI / 36, 60, 80),
+}));
+system.addUpdateModule(new ColorOverLifetime(new Gradient([
+    { t: 0, color: new Color(194, 64, 30, 1) },
+    { t: 1, color: new Color(0, 0, 0, 0) },
+])));
+// no per-frame mutation needed.
+```
+
+```ts
+// Before — gravity affector
+const gravity = new ForceAffector(0, 980);
+system.addAffector(gravity);
+
+// After
+system.addUpdateModule(new ApplyForce(0, 980));
+```
+
+```ts
+// Before — custom affector
+class AlphaFade {
+    apply(particle, delta) {
+        particle.tint.a = particle.remainingRatio;
+        return this;
+    }
+    destroy() {}
+}
+
+// After
+class AlphaFadeOverLifetime extends UpdateModule {
+    apply(system) {
+        const { color, elapsed, lifetime, liveCount } = system;
+        for (let i = 0; i < liveCount; i++) {
+            const remaining = 1 - elapsed[i] / lifetime[i];
+            const a = (Math.max(0, Math.min(1, remaining)) * 255) & 255;
+            color[i] = (color[i] & 0x00ffffff) | (a << 24);
+        }
+    }
+}
+```
+
+```ts
+// Before — direct particle creation in tests
+const particle = system.requestParticle();
+particle.position.set(10, 12);
+particle.tint = Color.red;
+system.emitParticle(particle);
+
+// After — direct slot manipulation
+const slot = system.spawn();
+system.posX[slot] = 10;
+system.posY[slot] = 12;
+system.color[slot] = Color.red.toRgba();
+system.lifetime[slot] = 1;
+system.scaleX[slot] = 1;
+system.scaleY[slot] = 1;
+```
+
+### Changed — `ParticleSystem` constructor: typed overloads (BREAKING)
+
+Source material (texture / atlas frames / spritesheet) lives in
+**positional arguments** — TypeScript overload signatures enforce mutual
+exclusivity at compile time so you can't pass nonsense combinations like
+texture-and-spritesheet-at-once. Capacity and the test-only `device`
+escape hatch live in the trailing options object.
+
+```ts
+// 0.7.x:
+new ParticleSystem(texture);
+new ParticleSystem(texture, 4096);
+
+// 0.8.0:
+new ParticleSystem();                                  // untextured (1×1 white), CPU/GPU auto-routed
+new ParticleSystem(spark);                             // simple textured particles
+new ParticleSystem(spark, { capacity: 8192 });         // explicit capacity
+new ParticleSystem(atlas, [r0, r1, r2]);               // multi-frame atlas
+new ParticleSystem(atlas, frames, { capacity: 8192 }); // atlas + capacity
+new ParticleSystem(sheet);                             // spritesheet shorthand
+new ParticleSystem(sheet, { capacity: 4096 });
+```
+
+The four overload signatures:
+
+```ts
+constructor(options?: ParticleSystemOptions);
+constructor(texture: Texture, options?: ParticleSystemOptions);
+constructor(texture: Texture, frames: ReadonlyArray<Rectangle>, options?: ParticleSystemOptions);
+constructor(spritesheet: Spritesheet, options?: ParticleSystemOptions);
+```
+
+Compile-time errors for illegal combinations:
+
+```ts
+new ParticleSystem(spark, sheet);                  // ✗ no overload matches
+new ParticleSystem(sheet, frames);                 // ✗ frames only valid with Texture
+new ParticleSystem({ frames });                    // ✗ frames isn't an option
+```
+
+**No `backend` option** — the renderer auto-discovers the active backend
+on the first `render(backend)` call. WebGPU → GPU compute path, WebGL2 →
+CPU path. Re-discovery on backend change (device-loss recovery).
+
+### Added — Optional texture + 1×1 white default
+
+When `texture` is omitted, the system uses a lazily-allocated 1×1
+opaque-white singleton. Particles render as solid color quads driven by
+the per-particle `color` channel. Useful for tech-demo magic effects,
+abstract VFX, performance benchmarks.
+
+### Added — Multi-frame atlas via `frames` / `spritesheet` options
+
+`frames: ReadonlyArray<Rectangle>` declares per-particle frame
+rectangles within the atlas texture. Each particle's `textureIndex[i]`
+selects which frame to render — `RateSpawn` /
+`BurstSpawn`'s `textureIndex: Distribution<number>` becomes the per-spawn
+frame chooser:
+
+```ts
+const system = new ParticleSystem({
+    texture: explosionAtlas,
+    frames: [
+        new Rectangle(0,   0, 32, 32),  // index 0 — flame core
+        new Rectangle(32,  0, 32, 32),  // index 1 — smoke ring
+        new Rectangle(64,  0, 32, 32),  // index 2 — ember
+    ],
+});
+
+system.addSpawnModule(new BurstSpawn({
+    schedule: [{ time: 0, count: 60 }],
+    velocity: ConeDirection.omni(120, 280),
+    textureIndex: new Range(0, 2),       // each spawn picks a random frame
+}));
+```
+
+`Spritesheet` integration via `spritesheet: sheet` extracts texture +
+frames in insertion order — convenient for atlas authors who already
+have a sheet from a TexturePacker / Aseprite export.
+
+UV resolution happens once per particle per frame (CPU pack in CPU mode,
+compute shader in GPU mode); the renderer reads pre-resolved UVs from
+the instance buffer — no shader-side frame-array lookup overhead.
+
+### Changed — Per-instance vertex layout: 24 → 40 bytes
+
+The renderer's per-instance buffer now carries `uvMin: vec2` and
+`uvMax: vec2` alongside the existing translation/scale/rotation/color
+fields. Lets a single batch render any mix of atlas frames per instance
+without indirection through a uniform array. Net cost: +67% bandwidth
+on the instance buffer (still trivial — ~10 MB/s at 60 fps with 16k
+particles).
+
+The previous design used a single `u_uvBounds` uniform that pinned
+every particle in a system to the same frame; the new layout is what
+makes per-particle atlas selection free.
+
+The system pre-allocates all SoA arrays at construction. Spawn modules
+that want to emit beyond capacity get `-1` from `spawn()` and should
+bail cleanly (the built-ins do).
+
+### Changed — slot allocation differs between CPU and GPU mode
+
+In CPU mode, `[0, liveCount)` is dense (forward-compaction at end of
+update). `spawn()` always returns the next sequential slot.
+
+In GPU mode, no compaction happens — readback would be required to
+move slots whose authoritative position lives in GPU memory. Instead:
+- Each particle has an `alive: Uint8Array` flag (1 = alive, 0 = dead).
+- `spawn()` finds the first dead slot via a round-robin hint pointer
+  (amortised O(1), worst case O(capacity)).
+- Expiry on CPU: `alive[i] = 0`, `lifetime[i] = -1` (sentinel).
+- The compute shader skips dead slots (`timing[idx].y < 0.0` → write
+  zero-scale instance and return).
+
+Custom modules iterating `[0, liveCount)` should check `system.alive[i]`
+in GPU mode if they care about ignoring dead slots; mutating dead slot
+data is harmless because the GPU shader skips them.
+
+### Added — `system.aliveCount`
+
+Returns the actual count of alive particles (slots with `alive[i] === 1`).
+In CPU mode this equals `liveCount`; in GPU mode it's `≤ liveCount`.
+Use for fragmentation diagnostics or UI counters.
+
+### Performance notes
+
+- Spawning + integrating + ColorOverLifetime/ScaleOverLifetime + drag
+  on 10k particles: previously ~5 ms CPU per frame; new SoA path on
+  CPU: ~0.5 ms (~10× speedup from eliminating per-particle object
+  indirection). New GPU path on WebGPU: ~0.05 ms (~100× speedup from
+  the previous OO baseline) — bound by the per-frame upload, not the
+  compute itself.
+- The crossover where GPU beats CPU sits around 1-3 k particles
+  depending on hardware. For sub-1k systems CPU is still slightly
+  faster (upload overhead dominates); the auto-router doesn't second-
+  guess this — opt out via `backend: undefined` if you want to force
+  CPU at low counts.
+- 100k+ particles render and simulate cleanly on WebGPU at 60 fps in
+  CI smoke tests; the bottleneck shifts from compute to texture
+  bandwidth at that scale.
+
 ## [0.7.13] - 2026-05-07
 
 Major gamepad-input refactor. Replaces the `new Input(...)` +

package/dist/esm/index.js

@@ -83,14 +83,35 @@ export { Size } from './math/Size.js';
 export { PolarVector } from './math/PolarVector.js';
 export { substepSweep, sweepCircleAgainst, sweepCircleVsCircle, sweepCircleVsRectangle, sweepRectangle, sweepRectangleAgainst } from './math/swept-collision.js';
 export { Quadtree } from './math/Quadtree.js';
-export { ColorAffector } from './particles/affectors/ColorAffector.js';
-export { ForceAffector } from './particles/affectors/ForceAffector.js';
-export { ScaleAffector } from './particles/affectors/ScaleAffector.js';
-export { TorqueAffector } from './particles/affectors/TorqueAffector.js';
-export { ParticleOptions } from './particles/emitters/ParticleOptions.js';
-export { UniversalEmitter } from './particles/emitters/UniversalEmitter.js';
-export { Particle } from './particles/Particle.js';
 export { ParticleSystem } from './particles/ParticleSystem.js';
+export { Constant } from './particles/distributions/Constant.js';
+export { Range } from './particles/distributions/Range.js';
+export { VectorRange } from './particles/distributions/VectorRange.js';
+export { ConeDirection } from './particles/distributions/ConeDirection.js';
+export { CircleArea } from './particles/distributions/CircleArea.js';
+export { BoxArea } from './particles/distributions/BoxArea.js';
+export { LineSegment } from './particles/distributions/LineSegment.js';
+export { Curve } from './particles/distributions/Curve.js';
+export { Gradient } from './particles/distributions/Gradient.js';
+export { SpawnModule } from './particles/modules/SpawnModule.js';
+export { UpdateModule } from './particles/modules/UpdateModule.js';
+export { DeathModule } from './particles/modules/DeathModule.js';
+export { wgslFieldLayout, wgslUniformByteSize } from './particles/modules/WgslContribution.js';
+export { RateSpawn } from './particles/modules/RateSpawn.js';
+export { BurstSpawn } from './particles/modules/BurstSpawn.js';
+export { ApplyForce } from './particles/modules/ApplyForce.js';
+export { Drag } from './particles/modules/Drag.js';
+export { ColorOverLifetime } from './particles/modules/ColorOverLifetime.js';
+export { ColorOverSpeed } from './particles/modules/ColorOverSpeed.js';
+export { ScaleOverLifetime } from './particles/modules/ScaleOverLifetime.js';
+export { RotateOverLifetime } from './particles/modules/RotateOverLifetime.js';
+export { AlphaFadeOverLifetime } from './particles/modules/AlphaFadeOverLifetime.js';
+export { VelocityOverLifetime } from './particles/modules/VelocityOverLifetime.js';
+export { AttractToPoint } from './particles/modules/AttractToPoint.js';
+export { RepelFromPoint } from './particles/modules/RepelFromPoint.js';
+export { OrbitalForce } from './particles/modules/OrbitalForce.js';
+export { Turbulence } from './particles/modules/Turbulence.js';
+export { SpawnOnDeath } from './particles/modules/SpawnOnDeath.js';
 export { Mesh } from './rendering/mesh/Mesh.js';
 export { Graphics } from './rendering/primitives/Graphics.js';
 export { Shader } from './rendering/shader/Shader.js';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}