@cyberluke/three-particles 4.0.1

package/llms.txt

@@ -0,0 +1,339 @@
+# @cyberluke/three-particles
+
+> Three.js-based high-performance particle system library for creating visually stunning particle effects. Perfect for game developers and 3D applications.
+
+## Quick Start
+
+```bash
+npm install @cyberluke/three-particles three
+```
+
+```typescript
+import * as THREE from "three";
+import { createParticleSystem, updateParticleSystems } from "@cyberluke/three-particles";
+
+const scene = new THREE.Scene();
+
+const { instance } = createParticleSystem({
+  duration: 5,
+  looping: true,
+  maxParticles: 100,
+  startLifetime: 2,
+  startSpeed: 3,
+  startSize: 0.5,
+  startColor: { min: { r: 1, g: 0.5, b: 0 }, max: { r: 1, g: 1, b: 0 } },
+  emission: { rateOverTime: 20 },
+  shape: { shape: Shape.CONE, cone: { angle: 0.4, radius: 0.5 } },
+});
+
+scene.add(instance);
+
+// In your animation loop:
+function animate() {
+  updateParticleSystems({
+    now: performance.now(),
+    delta: clock.getDelta(),
+    elapsed: clock.getElapsedTime(),
+  });
+}
+```
+
+## Main API
+
+- `createParticleSystem(config: ParticleSystemConfig): ParticleSystem` ??? Create a particle system
+- `updateParticleSystems(cycleData: CycleData)` ??? Update all active particle systems
+
+### ParticleSystem Methods
+
+- `instance` ??? The Three.js Points or Mesh object (add to scene)
+- `pauseEmitter()` ??? Pause particle emission
+- `resumeEmitter()` ??? Resume particle emission
+- `dispose()` ??? Clean up and free resources
+- `update(cycleData)` ??? Update this specific system only
+- `updateConfig(config)` ??? Update configuration at runtime without recreating the system
+- `getActiveParticleCount()` ??? Number of currently alive particles (O(1))
+
+## Key Configuration Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| duration | number | 5.0 | Duration in seconds |
+| looping | boolean | true | Whether to loop |
+| maxParticles | number | 100 | Maximum active particles |
+| startLifetime | number / {min,max} / Curve | 5.0 | Particle lifetime |
+| startSpeed | number / {min,max} / Curve | 1.0 | Initial speed |
+| startSize | number / {min,max} / Curve | 1.0 | Initial size |
+| startOpacity | number / {min,max} / Curve | 1.0 | Initial opacity |
+| startRotation | number / {min,max} / Curve | 0.0 | Initial rotation (degrees) |
+| 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 |
+| renderer | Renderer | ??? | Renderer settings (blending, rendererType, etc.) |
+
+## Renderer Types
+
+- `RendererType.POINTS` (default) ??? Classic point sprites via `THREE.Points`
+- `RendererType.INSTANCED` ??? Camera-facing quads via `InstancedBufferGeometry`, removes `gl_PointSize` hardware limit
+- `RendererType.TRAIL` ??? Ribbon trails behind particles with configurable width, opacity, and color tapering
+- `RendererType.MESH` ??? Render each particle as a 3D mesh (cubes, spheres, custom geometry) via GPU instancing with quaternion-based 3D rotation and directional lighting. Uses solid white default texture (not circle) to preserve mesh shape. Sub-emitters do not inherit MESH or TRAIL rendererType from parent
+
+## Mesh Particle Renderer
+
+Configure via `renderer.mesh`:
+
+```typescript
+renderer: {
+  rendererType: RendererType.MESH,
+  blending: THREE.NormalBlending,
+  transparent: true,
+  depthTest: true,
+  depthWrite: true,
+  mesh: {
+    geometry: new THREE.BoxGeometry(1, 1, 1), // Any THREE.BufferGeometry
+  },
+}
+```
+
+Mesh particles use GPU instancing (`InstancedBufferGeometry`). Each particle is a full 3D mesh with quaternion rotation, normals, and UVs preserved. All modifiers (sizeOverLifetime, colorOverLifetime, noise, force fields, sub-emitters) work with mesh particles.
+
+## Trail / Ribbon Renderer
+
+Configure via `renderer.trail`:
+
+```typescript
+renderer: {
+  rendererType: RendererType.TRAIL,
+  blending: THREE.AdditiveBlending,
+  transparent: true,
+  trail: {
+    length: 40,           // History samples per particle (default: 20)
+    width: 0.5,           // Ribbon width in world units (default: 1.0)
+    widthOverTrail: { ... },    // LifetimeCurve: width taper (0=head, 1=tail)
+    opacityOverTrail: { ... },  // LifetimeCurve: opacity taper
+    colorOverTrail: {           // Optional per-channel color multipliers
+      isActive: true,
+      r: { type: LifeTimeCurve.BEZIER, bezierPoints: [...] },
+      g: { type: LifeTimeCurve.BEZIER, bezierPoints: [...] },
+      b: { type: LifeTimeCurve.BEZIER, bezierPoints: [...] },
+    },
+  },
+}
+```
+
+Trails use GPU billboard rendering (vertex shader). Supports optional textures and soft-edge fade.
+
+## Emitter Shapes
+
+- `Shape.SPHERE` ??? Spherical emission (radius, arc, radiusThickness)
+- `Shape.CONE` ??? Conical emission (angle, radius, arc)
+- `Shape.CIRCLE` ??? Circular flat emission (radius, arc)
+- `Shape.RECTANGLE` ??? Rectangular flat emission (scale, rotation)
+- `Shape.BOX` ??? Box volume emission (scale, emitFrom: VOLUME/SHELL/EDGE)
+
+## Lifetime Modifiers
+
+- `velocityOverLifetime` ??? Linear & orbital velocity changes
+- `sizeOverLifetime` ??? Size curve over lifetime
+- `opacityOverLifetime` ??? Opacity curve over lifetime
+- `colorOverLifetime` ??? RGB curves (multipliers on startColor)
+- `rotationOverLifetime` ??? Rotation speed range
+- `noise` ??? FBM noise affecting position, rotation, size
+
+## Burst Emission
+
+```typescript
+emission: {
+  rateOverTime: 0,
+  bursts: [
+    { time: 0, count: 50 },
+    { time: 1, count: { min: 10, max: 30 }, probability: 0.8 },
+    { time: 0.5, count: 10, cycles: 3, interval: 0.2 },
+  ],
+}
+```
+
+## Curves
+
+Values support: constant `number`, random `{ min, max }`, or curves:
+
+```typescript
+// Bezier curve
+{ type: LifeTimeCurve.BEZIER, bezierPoints: [...], scale: 1 }
+
+// Easing function
+{ type: LifeTimeCurve.EASING, curveFunction: (t) => t * t, scale: 1 }
+```
+
+## Sub-Emitters
+
+Trigger child particle systems on particle birth or death:
+
+```typescript
+subEmitters: [
+  { trigger: SubEmitterTrigger.BIRTH, config: sparkConfig },
+  { trigger: SubEmitterTrigger.DEATH, config: explosionConfig },
+]
+```
+
+## Force Fields
+
+Point attractors/repulsors and directional wind forces:
+
+```typescript
+forceFields: [
+  {
+    type: ForceFieldType.POINT,
+    position: { x: 0, y: 2, z: 0 },
+    strength: 5,
+    radius: 3,
+    falloff: ForceFieldFalloff.LINEAR,
+  },
+  {
+    type: ForceFieldType.DIRECTIONAL,
+    direction: { x: 1, y: 0, z: 0 },
+    strength: 2,
+  },
+]
+```
+
+## 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 "@cyberluke/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();
+// No outputColorSpace override needed ??? the library uses the standard
+// three.js linear workflow and works with the default (SRGBColorSpace).
+
+// 3. Create a GPU-accelerated particle system
+import { createParticleSystem, SimulationBackend } from "@cyberluke/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 path registered (`enableWebGPU()`) | Not registered |
+|-------|------------------------------------------|----------------|
+| `AUTO` (default) | GPU compute | CPU (JavaScript) |
+| `CPU` | CPU (JavaScript) | CPU (JavaScript) |
+| `GPU` | GPU compute | CPU (JavaScript) |
+
+Note: the library never inspects the renderer on its own ??? the decision is
+based on whether `enableWebGPU()` registered the WebGPU path. Call
+`enableWebGPU(renderer)` (returns boolean) to skip registration automatically
+when the renderer cannot dispatch compute shaders (e.g. `WebGLRenderer`).
+
+### 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`) ??? note: on the GPU backend, modifier
+  flags and lifetime curves (sizeOverLifetime, opacityOverLifetime,
+  colorOverLifetime, rotationOverLifetime, velocityOverLifetime,
+  noise.isActive) are baked into the compute kernel at creation and cannot be
+  changed live (a console warning is logged); recreate the system instead.
+  On the CPU backend all of these update live.
+- 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) and CPU simulation
+- If `enableWebGPU(renderer)` is called with a renderer that lacks compute support: registration is skipped with a console warning; everything stays on the CPU/GLSL path
+- Same `ParticleSystemConfig` works on both backends ??? but see the `updateConfig` GPU limitation above
+
+## Usage with React Three Fiber
+
+No wrapper package needed ??? use hooks directly:
+
+```tsx
+import { useRef, useEffect } from "react";
+import { useFrame } from "@react-three/fiber";
+import { createParticleSystem, type ParticleSystem } from "@cyberluke/three-particles";
+
+function ParticleEffect({ config }) {
+  const groupRef = useRef(null);
+  const systemRef = useRef(null);
+
+  useEffect(() => {
+    const system = createParticleSystem(config);
+    systemRef.current = system;
+    groupRef.current?.add(system.instance);
+    return () => system.dispose();
+  }, [config]);
+
+  useFrame((_, delta) => {
+    systemRef.current?.update({ now: performance.now(), delta, elapsed: 0 });
+  });
+
+  return <group ref={groupRef} />;
+}
+```
+
+Key: `useEffect` for create/dispose, `useFrame` for per-frame updates, `system.update()` for individual system control.
+
+## Links
+
+- Repository: https://github.com/cyberluke/three-particles
+- API docs: shipped TypeScript definitions (`dist/index.d.ts`, `webgpu.d.ts`)
+- Visual Editor: https://github.com/cyberluke/three-particles-editor
+- Editor: `@cyberluke/three-particles-editor`
+- Full LLM reference: `llms-full.txt` included in the npm package.

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@cyberluke/three-particles",
+  "version": "4.0.1",
+  "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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "webgpu.d.ts",
+    "README.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "llms": "https://newkrok.github.io/three-particles/llms.txt",
+  "llmsFull": "https://newkrok.github.io/three-particles/llms-full.txt",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./webgpu": {
+      "import": "./dist/webgpu.js",
+      "types": "./webgpu.d.ts"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyberluke/three-particles.git"
+  },
+  "keywords": [
+    "three",
+    "three.js",
+    "particles",
+    "particle system",
+    "webgl",
+    "3d",
+    "visual effects",
+    "game development",
+    "3d applications",
+    "high performance",
+    "javascript",
+    "typescript",
+    "three-particles",
+    "threejs effects"
+  ],
+  "author": "CyberLuke",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bugs": {
+    "url": "https://github.com/cyberluke/three-particles/issues"
+  },
+  "homepage": "https://github.com/cyberluke/three-particles#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src",
+    "benchmark": "npm run build && node --experimental-vm-modules benchmarks/run.js",
+    "benchmark:json": "npm run build && node --experimental-vm-modules benchmarks/run.js --json",
+    "benchmark:compare": "node --experimental-vm-modules benchmarks/run.js --compare",
+    "benchmark:save-baseline": "npm run benchmark:json > benchmarks/baseline.json",
+    "build:examples": "tsup && webpack --config webpack.docs.config.js",
+    "examples:dev": "npm run build:examples && npx http-server examples -p 8081 -o",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@newkrok/three-utils": "^2.0.2",
+    "easing-functions": "1.3.0",
+    "three-noise": "1.1.2"
+  },
+  "peerDependencies": {
+    "three": "^0.186.0"
+  },
+  "devDependencies": {
+    "@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.6.0",
+    "@types/three": "^0.183.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",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "jest": "^30.3.0",
+    "madge": "^8.0.0",
+    "prettier": "^3.8.3",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.9",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.19",
+    "typescript": "^5.9.3",
+    "webpack": "^5.106.2",
+    "webpack-cli": "^7.0.2"
+  }
+}

package/webgpu.d.ts

@@ -0,0 +1,98 @@
+/**
+ * WebGPU entry point type declarations for @cyberluke/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 '@cyberluke/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.
+ *
+ * Pass your renderer to get automatic capability detection: when the
+ * renderer cannot dispatch compute shaders (e.g. `THREE.WebGLRenderer`),
+ * registration is skipped with a console warning and all particle systems
+ * keep using the CPU/GLSL path.
+ *
+ * @param renderer - Optional Three.js renderer used for capability detection.
+ * @returns `true` when the WebGPU path was registered, `false` when the
+ *   provided renderer is not compute-capable and registration was skipped.
+ *
+ * @example
+ * ```typescript
+ * import { enableWebGPU } from '@cyberluke/three-particles/webgpu';
+ * const renderer = new THREE.WebGPURenderer();
+ * const gpuEnabled = enableWebGPU(renderer);
+ * ```
+ */
+export declare function enableWebGPU(renderer?: unknown): boolean;