@newkrok/three-particles 2.15.1 → 2.16.0

package/llms-full.txt

@@ -68,6 +68,7 @@ function animate() {
 | `dispose()` | `() => void` | Destroy system, free resources |
 | `update(cycleData)` | `(CycleData) => void` | Update this system individually |
 | `updateConfig(config)` | `(Partial<ParticleSystemConfig>) => void` | Update configuration at runtime without recreating the system. System-level properties (gravity, force fields, noise, emission, color/size/opacity over lifetime) take effect immediately. Per-particle spawn properties (startColor, startSize, etc.) affect only newly emitted particles. |
+| `computeNode` | `unknown \| null` | GPU compute node for WebGPU dispatch. Non-null when GPU compute is active. Must be dispatched via `renderer.compute(system.computeNode)` every frame before `renderer.render()`. Null when CPU simulation is used. |
 
 ---
 
@@ -96,6 +97,7 @@ type CycleData = {
 | `maxParticles` | `number` | 100 | Maximum concurrent particles |
 | `gravity` | `number` | 0.0 | Downward acceleration |
 | `simulationSpace` | `SimulationSpace` | LOCAL | LOCAL or WORLD coordinate space |
+| `simulationBackend` | `SimulationBackend` | AUTO | Simulation backend: AUTO (GPU if WebGPU available, else CPU), CPU, or GPU |
 
 ### Start Properties
 
@@ -523,6 +525,12 @@ const system = createParticleSystem({
 ### RendererType
 `POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit) | `TRAIL` (ribbon trails behind particles) | `MESH` (3D mesh particles via GPU instancing)
 
+### CollisionPlaneMode
+`KILL` (deactivate particle immediately) | `CLAMP` (stop particle at the plane surface) | `BOUNCE` (reflect velocity with optional dampen)
+
+### SimulationBackend
+`AUTO` (default — GPU compute if WebGPU renderer detected, else CPU) | `CPU` (always JavaScript update loop) | `GPU` (request GPU compute, falls back to CPU if unavailable)
+
 ---
 
 ## Callbacks
@@ -693,6 +701,48 @@ createParticleSystem({
 
 ---
 
+## Collision Planes
+
+Infinite planes that constrain particle positions. When a particle crosses from the front side (positive normal direction) to the back side, the configured response mode is triggered.
+
+```typescript
+type CollisionPlaneConfig = {
+  isActive?: boolean;         // Whether this plane is active (default: true)
+  position?: Point3D;         // A point on the plane surface (default: {x:0, y:0, z:0})
+  normal?: Point3D;           // Plane normal vector, defines the "front" side (default: {x:0, y:1, z:0})
+  mode?: CollisionPlaneMode;  // Response mode (default: KILL)
+  dampen?: number;            // Velocity dampen factor for BOUNCE mode, 0-1 (default: 0)
+  lifetimeLoss?: number;      // Fraction of start lifetime to subtract on collision, 0-1 (default: 0)
+};
+```
+
+### CollisionPlaneMode
+- `KILL` — Deactivate the particle immediately when it crosses the plane
+- `CLAMP` — Stop the particle at the plane surface (zero velocity toward plane)
+- `BOUNCE` — Reflect the velocity vector off the plane normal with optional dampen
+
+**Example — Bouncy floor and kill ceiling:**
+```typescript
+createParticleSystem({
+  // ... particle config
+  collisionPlanes: [
+    {
+      position: { x: 0, y: 0, z: 0 },
+      normal: { x: 0, y: 1, z: 0 },
+      mode: CollisionPlaneMode.BOUNCE,
+      dampen: 0.6,
+    },
+    {
+      position: { x: 0, y: 10, z: 0 },
+      normal: { x: 0, y: -1, z: 0 },
+      mode: CollisionPlaneMode.KILL,
+    },
+  ],
+});
+```
+
+---
+
 ## Serialization
 
 Save and load particle system configurations as JSON.
@@ -785,6 +835,145 @@ function FireEffect({ config }: { config?: Record<string, unknown> }) {
 
 ---
 
+## WebGPU Compute Support
+
+Optional GPU-accelerated particle simulation via Three.js WebGPU renderer and TSL (Three Shading Language). Offloads all per-particle physics and modifiers to GPU compute shaders, enabling **50K-350K+ particles** at interactive frame rates.
+
+**Requirements:** Three.js r182+ with WebGPU build (`three/webgpu`), browser with WebGPU support (Chrome 113+, Edge 113+, Firefox Nightly). No breaking changes — all existing WebGL code works unchanged.
+
+### Setup
+
+```typescript
+// 1. Enable WebGPU support (once, before creating any particle system)
+import { enableWebGPU } from "@newkrok/three-particles/webgpu";
+enableWebGPU();
+
+// 2. Create a WebGPU renderer
+import * as THREE from "three/webgpu";
+const renderer = new THREE.WebGPURenderer({ antialias: true });
+await renderer.init();
+
+// 3. Create a GPU-accelerated particle system
+import { createParticleSystem, SimulationBackend } from "@newkrok/three-particles";
+const system = createParticleSystem({
+  simulationBackend: SimulationBackend.AUTO, // GPU if WebGPU available, else CPU
+  maxParticles: 100000,
+  // ... rest of config (same API as CPU)
+});
+
+scene.add(system.instance);
+
+// 4. In your render loop — dispatch compute before rendering
+function animate() {
+  system.update({ now: performance.now(), delta, elapsed });
+
+  if (system.computeNode) {
+    renderer.compute(system.computeNode);
+  }
+  renderer.render(scene, camera);
+}
+```
+
+For fine-grained control (e.g., selective registration of individual WebGPU functions), you can also use `registerTSLMaterialFactory()` directly — see the API reference below.
+
+### SimulationBackend
+
+```typescript
+enum SimulationBackend {
+  AUTO = 'AUTO',  // GPU compute if WebGPU renderer detected, else CPU (default)
+  CPU = 'CPU',    // Always JavaScript update loop (works with any renderer)
+  GPU = 'GPU',    // Request GPU compute; falls back to CPU if renderer lacks compute support
+}
+```
+
+| Value | WebGPU Renderer | WebGL Renderer |
+|-------|----------------|----------------|
+| `AUTO` | GPU compute | CPU (JavaScript) |
+| `CPU` | CPU (JavaScript) | CPU (JavaScript) |
+| `GPU` | GPU compute | CPU (fallback) |
+
+### What Runs on GPU
+
+- **Core physics:** gravity, velocity integration, position update, lifetime tracking, death detection
+- **All 7 modifiers:** size over lifetime, opacity over lifetime, color over lifetime (per-channel RGB curves), rotation over lifetime, linear velocity over lifetime (per-axis X/Y/Z curves), orbital velocity, noise (3D simplex FBM)
+- **Force fields:** point attractors/repulsors and directional forces with all falloff modes (NONE, LINEAR, QUADRATIC), up to 16 per system
+- **Collision planes:** kill/clamp/bounce modes with dampen and lifetime loss, encoded as packed uniform buffer
+- **Curves:** baked into 256-sample Float32Array lookup tables at system creation for fast GPU evaluation (<0.4% interpolation error)
+
+### What Stays on CPU
+
+- **Emission:** particle activation, burst scheduling, rate-over-time, rate-over-distance
+- **Sub-emitters:** birth/death trigger spawning (sub-emitters are always forced to `SimulationBackend.CPU`)
+- **Configuration changes:** `updateConfig()` applies on the next frame
+- **Trail renderer:** `RendererType.TRAIL` always uses CPU simulation (POINTS, INSTANCED, and MESH work with GPU compute)
+
+### ParticleSystem.computeNode
+
+When GPU compute is active, the returned `ParticleSystem` object exposes a `computeNode` property. This must be dispatched every frame **before** `renderer.render()`:
+
+```typescript
+const system = createParticleSystem({ simulationBackend: SimulationBackend.GPU, ... });
+
+// In render loop:
+if (system.computeNode) {
+  renderer.compute(system.computeNode); // Dispatch GPU compute
+}
+renderer.render(scene, camera);
+```
+
+When CPU simulation is active (no WebGPU, or `simulationBackend: 'CPU'`), `computeNode` is `null`.
+
+### Fallback Behavior
+
+WebGPU is fully opt-in and non-breaking:
+- If `enableWebGPU()` not called (or no TSL factory registered via `registerTSLMaterialFactory()`), the library uses GLSL shaders (existing WebGL path)
+- If `simulationBackend: 'GPU'` but the renderer lacks compute support, it silently falls back to CPU
+- The same `ParticleSystemConfig` works identically on both backends — no config changes needed
+- Renderer detection is duck-typed (checks for `.compute()` and `.hasFeature()` methods), not class-based
+
+### WebGPU with React Three Fiber
+
+```tsx
+import { useRef, useEffect } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import { createParticleSystem, SimulationBackend } from "@newkrok/three-particles";
+import { enableWebGPU } from "@newkrok/three-particles/webgpu";
+
+// Enable once at module level
+enableWebGPU();
+
+function GPUParticleEffect({ config }) {
+  const groupRef = useRef(null);
+  const systemRef = useRef(null);
+  const { gl: renderer } = useThree();
+
+  useEffect(() => {
+    const system = createParticleSystem({
+      simulationBackend: SimulationBackend.AUTO,
+      ...config,
+    });
+    systemRef.current = system;
+    groupRef.current?.add(system.instance);
+    return () => system.dispose();
+  }, [config]);
+
+  useFrame((_, delta) => {
+    const system = systemRef.current;
+    if (!system) return;
+    system.update({ now: performance.now(), delta, elapsed: 0 });
+    if (system.computeNode) {
+      renderer.compute(system.computeNode);
+    }
+  });
+
+  return <group ref={groupRef} />;
+}
+```
+
+**Important:** R3F must be configured to use `WebGPURenderer` (via the `gl` prop on `<Canvas>`) for GPU compute to activate.
+
+---
+
 ## Links
 
 - Repository: https://github.com/NewKrok/three-particles

package/llms.txt

@@ -67,6 +67,7 @@ function animate() {
 | startColor | MinMaxColor | white | Color range |
 | gravity | number | 0.0 | Gravity strength |
 | simulationSpace | LOCAL / WORLD | LOCAL | Coordinate space |
+| simulationBackend | AUTO / CPU / GPU | AUTO | Simulation backend (AUTO: GPU if WebGPU, else CPU) |
 | emission | Emission | rateOverTime: 10 | Emission config |
 | shape | ShapeConfig | — | Emitter shape |
 | map | THREE.Texture | undefined | Particle texture |
@@ -198,6 +199,94 @@ forceFields: [
 ]
 ```
 
+## Collision Planes
+
+Infinite planes that constrain particles with three response modes: kill, clamp, or bounce.
+
+```typescript
+collisionPlanes: [
+  { position: { x: 0, y: 0, z: 0 }, normal: { x: 0, y: 1, z: 0 }, mode: CollisionPlaneMode.BOUNCE, dampen: 0.6 },
+  { position: { x: 0, y: 5, z: 0 }, normal: { x: 0, y: -1, z: 0 }, mode: CollisionPlaneMode.KILL },
+]
+```
+
+## WebGPU Compute Support
+
+Optional GPU-accelerated particle simulation via Three.js WebGPU renderer and TSL (Three Shading Language). Enables **50K-350K+ particles** with full physics on the GPU.
+
+**Requirements:** Three.js r182+ with WebGPU build (`three/webgpu`), browser with WebGPU support (Chrome 113+, Edge 113+). No breaking changes — all existing WebGL code works unchanged.
+
+### Setup
+
+```typescript
+// 1. Enable WebGPU support (once, before creating any particle system)
+import { enableWebGPU } from "@newkrok/three-particles/webgpu";
+enableWebGPU();
+
+// 2. Create a WebGPU renderer
+import * as THREE from "three/webgpu";
+const renderer = new THREE.WebGPURenderer({ antialias: true });
+await renderer.init();
+
+// 3. Create a GPU-accelerated particle system
+import { createParticleSystem, SimulationBackend } from "@newkrok/three-particles";
+const system = createParticleSystem({
+  simulationBackend: SimulationBackend.AUTO, // GPU if WebGPU available, else CPU
+  maxParticles: 100000,
+  // ... rest of config (same API as CPU)
+});
+
+scene.add(system.instance);
+
+// 4. In your render loop — dispatch compute before rendering
+system.update({ now: performance.now(), delta, elapsed });
+if (system.computeNode) {
+  renderer.compute(system.computeNode);
+}
+renderer.render(scene, camera);
+```
+
+For fine-grained control, you can also use `registerTSLMaterialFactory()` to selectively register individual WebGPU functions — see the full API reference.
+
+### SimulationBackend
+
+| Value | WebGPU Renderer | WebGL Renderer |
+|-------|----------------|----------------|
+| `AUTO` (default) | GPU compute | CPU (JavaScript) |
+| `CPU` | CPU (JavaScript) | CPU (JavaScript) |
+| `GPU` | GPU compute | CPU (fallback) |
+
+### What runs on GPU
+
+- Core physics: gravity, velocity integration, position update, lifetime tracking
+- All 7 modifiers: size/opacity/color over lifetime, rotation, linear/orbital velocity, noise (3D simplex FBM)
+- Force fields: point/directional with falloff (up to 16 per system)
+- Collision planes: kill/clamp/bounce with dampen and lifetime loss
+- Curves: baked into 256-sample Float32Array lookup tables (<0.4% error)
+
+### What stays on CPU
+
+- Emission (particle activation, burst scheduling, rate-over-distance)
+- Sub-emitter spawning (birth/death triggers; sub-emitters are forced to CPU backend)
+- Configuration changes (`updateConfig`)
+- Trail renderer (`RendererType.TRAIL` always uses CPU simulation)
+
+### Compute dispatch
+
+The returned `ParticleSystem` exposes `computeNode` (non-null when GPU compute is active). This must be dispatched every frame **before** `renderer.render()`:
+
+```typescript
+if (system.computeNode) {
+  renderer.compute(system.computeNode);
+}
+```
+
+### Fallback behavior
+
+- If `enableWebGPU()` not called (or no TSL factory registered): uses GLSL shaders (WebGL path)
+- If `GPU` requested but renderer lacks compute: silently falls back to CPU
+- Same `ParticleSystemConfig` works on both backends — no config changes needed
+
 ## Usage with React Three Fiber
 
 No wrapper package needed — use hooks directly:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newkrok/three-particles",
-  "version": "2.15.1",
+  "version": "2.16.0",
   "type": "module",
   "description": "Three.js-based high-performance particle system library designed for creating visually stunning particle effects with ease. Perfect for game developers and 3D applications.",
   "main": "./dist/index.js",
@@ -8,6 +8,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/",
+    "webgpu.d.ts",
     "README.md",
     "LICENSE",
     "llms.txt",
@@ -19,6 +20,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./webgpu": {
+      "import": "./dist/webgpu.js",
+      "types": "./webgpu.d.ts"
     }
   },
   "repository": {
@@ -73,15 +78,15 @@
     "three": "^0.182.0"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.29.0",
+    "@babel/preset-env": "^7.29.2",
     "@babel/preset-typescript": "^7.28.5",
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@types/three": "^0.183.1",
-    "@typescript-eslint/eslint-plugin": "^8.57.1",
-    "@typescript-eslint/parser": "^8.57.1",
+    "@typescript-eslint/eslint-plugin": "^8.58.2",
+    "@typescript-eslint/parser": "^8.58.2",
     "babel-jest": "^30.3.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
@@ -90,14 +95,14 @@
     "husky": "^9.1.7",
     "jest": "^30.3.0",
     "madge": "^8.0.0",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.9",
     "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
-    "typedoc": "^0.28.17",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "webpack": "^5.105.4",
-    "webpack-cli": "^7.0.1"
+    "webpack": "^5.106.2",
+    "webpack-cli": "^7.0.2"
   }
 }

package/webgpu.d.ts

@@ -0,0 +1,88 @@
+/**
+ * WebGPU entry point type declarations for @newkrok/three-particles/webgpu.
+ *
+ * Hand-written because automatic DTS generation fails on TSL node types
+ * (Three.js TSL Fn return types resolve to `unknown` in the type system).
+ */
+import type { Material, Blending } from 'three';
+import type { RendererType } from '@newkrok/three-particles';
+
+/** Renderer configuration for material creation. */
+export interface RendererConfig {
+  transparent: boolean;
+  blending: Blending;
+  depthTest: boolean;
+  depthWrite: boolean;
+}
+
+/** Creates a TSL NodeMaterial for the main particle system (non-trail). */
+export declare function createTSLParticleMaterial(
+  rendererType: RendererType,
+  sharedUniforms: Record<string, { value: unknown }>,
+  rendererConfig: RendererConfig,
+  gpuCompute?: boolean
+): Material;
+
+/** Creates a TSL NodeMaterial for the trail ribbon renderer. */
+export declare function createTSLTrailMaterial(
+  trailUniforms: Record<string, { value: unknown }>,
+  rendererConfig: RendererConfig
+): Material;
+
+/** Creates the GPU compute pipeline for particle simulation. */
+export declare function createComputePipeline(
+  maxParticles: number,
+  instanced: boolean,
+  normalizedConfig: unknown,
+  particleSystemId: number,
+  forceFieldCount: number,
+  collisionPlaneCount?: number
+): unknown;
+
+/** Writes init data for a newly emitted particle into modifier storage buffers. */
+export declare function writeParticleToModifierBuffers(
+  buffers: unknown,
+  index: number,
+  data: Record<string, unknown>
+): void;
+
+/** Deactivates a particle in the modifier storage buffers. */
+export declare function deactivateParticleInModifierBuffers(
+  buffers: unknown,
+  index: number
+): void;
+
+/** Flushes pending init data to the GPU. Call once per frame before compute dispatch. */
+export declare function flushEmitQueue(buffers: unknown): number;
+
+/** Registers the curve data length for a buffer. Called once during pipeline creation. */
+export declare function registerCurveDataLength(
+  buffers: unknown,
+  curveDataLength: number
+): void;
+
+/** Packs force field configs into a flat Float32Array for GPU upload. */
+export declare function encodeForceFieldsForGPU(
+  forceFields: ReadonlyArray<unknown>,
+  particleSystemId: number,
+  systemLifetimePercentage: number
+): Float32Array;
+
+/** Packs collision plane configs into a flat Float32Array for GPU upload. */
+export declare function encodeCollisionPlanesForGPU(
+  planes: ReadonlyArray<unknown>
+): Float32Array;
+
+/**
+ * Convenience function that registers all WebGPU TSL material factories
+ * and GPU compute helpers in a single call.
+ *
+ * Call this **once** before creating any particle systems that use WebGPU rendering.
+ *
+ * @example
+ * ```typescript
+ * import { enableWebGPU } from '@newkrok/three-particles/webgpu';
+ * enableWebGPU();
+ * ```
+ */
+export declare function enableWebGPU(): void;