@newkrok/three-particles 2.15.2 → 2.16.0

package/README.md

@@ -19,12 +19,14 @@ Particle system for ThreeJS.
 *   Highly customizable particle properties (position, velocity, size, color, alpha, rotation, etc.).
 *   Support for various emitter shapes and parameters.
 *   Force fields and attractors for dynamic particle behavior (point attraction/repulsion, directional wind).
+*   Collision planes — kill, clamp, or bounce particles off infinite planes (e.g., water surfaces, floors, walls). Works on both CPU and GPU compute paths.
 *   Sub-emitters triggered on particle birth or death events.
 *   Serialization support for saving and loading particle system configs.
 *   GPU instancing renderer (`RendererType.INSTANCED`) — removes `gl_PointSize` hardware limit, ideal for large particles or high particle counts.
 *   Trail / Ribbon renderer (`RendererType.TRAIL`) — continuous ribbon trails behind particles with configurable width, opacity, and color tapering.
 *   Mesh particle renderer (`RendererType.MESH`) — render each particle as a 3D mesh (debris, gems, coins) using GPU instancing with full 3D rotation and simple directional lighting.
 *   Soft particles — depth-based alpha fade near opaque geometry, eliminating hard intersection lines.
+*   **WebGPU compute support** — GPU compute shaders for particle simulation (gravity, velocity, modifiers, force fields, noise) via Three.js TSL. Enables 50K-350K+ particles at full framerate. Automatic fallback to CPU when WebGPU is unavailable.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples
@@ -75,6 +77,10 @@ updateParticleSystems({now, delta, elapsed});
 system.updateConfig({
   gravity: -9.8,
   forceFields: [{ type: 'DIRECTIONAL', direction: { x: 1, y: 0, z: 0 }, strength: 5 }],
+  // Collision planes — kill, clamp, or bounce particles off surfaces
+  collisionPlanes: [
+    { position: { x: 0, y: 5, z: 0 }, normal: { x: 0, y: -1, z: 0 }, mode: 'KILL' },
+  ],
 });
 ```
 
@@ -150,6 +156,80 @@ function FireEffect({ config }: { config?: Record<string, unknown> }) {
 - Add the `system.instance` to a `<group>` ref so R3F manages the scene graph
 - Return a cleanup function from `useEffect` that calls `system.dispose()`
 
+# 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 the WebGPU build (`three/webgpu`)
+- A browser with [WebGPU support](https://caniuse.com/webgpu) (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 your 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, you can also use `registerTSLMaterialFactory()` to selectively register individual WebGPU functions — see the full API reference.
+
+## SimulationBackend
+
+| Value | Behavior |
+|-------|----------|
+| `AUTO` (default) | GPU compute if WebGPU renderer detected, else CPU |
+| `CPU` | Always JavaScript update loop (works with any renderer) |
+| `GPU` | Request GPU compute; falls back to CPU if renderer lacks compute support |
+
+## What Runs on GPU
+
+- **Core physics:** gravity, velocity integration, position update, lifetime tracking
+- **All 7 modifiers:** size/opacity/color over lifetime, rotation, linear velocity, orbital velocity, noise (3D simplex FBM)
+- **Force fields:** point attractors/repulsors and directional forces with falloff (up to 16 per system)
+- **Curves:** baked into 256-sample lookup arrays for fast GPU evaluation (<0.4% error)
+
+## What Stays on CPU
+
+- **Emission** — particle activation, burst scheduling, rate-over-distance
+- **Sub-emitters** — birth/death trigger spawning
+- **Configuration changes** — `updateConfig()` applies on the next frame
+- **Trail renderer** — TRAIL type always uses CPU simulation (other renderer types work with GPU)
+
+## Fallback Behavior
+
+WebGPU is fully opt-in and non-breaking:
+- If `enableWebGPU()` not called (or no TSL factory registered), the library uses GLSL shaders (WebGL path)
+- If `simulationBackend: 'GPU'` but WebGPU is unavailable, it silently falls back to CPU
+- The same particle config works identically on both backends
+
 # Documentation
 
 Automatically generated TypeDoc: [https://newkrok.github.io/three-particles/api/](https://newkrok.github.io/three-particles/api/)

package/dist/index.d.ts

@@ -215,10 +215,58 @@ declare const enum ForceFieldFalloff {
     LINEAR = "LINEAR",
     /**
      * Force decreases with the square of distance: `1 - (d/range)²`.
-     * More physically realistic than linear falloff.
+     * More physically realistic than linear fallback.
      */
     QUADRATIC = "QUADRATIC"
 }
+/**
+ * Defines the behavior when a particle crosses a collision plane.
+ *
+ * @enum {string}
+ */
+declare const enum CollisionPlaneMode {
+    /**
+     * Kill the particle immediately when it crosses the plane.
+     * The particle is deactivated and returned to the free list.
+     * Ideal for boundaries like water surfaces where bubbles pop.
+     */
+    KILL = "KILL",
+    /**
+     * Clamp the particle's position to the plane surface.
+     * The velocity component along the plane normal is zeroed.
+     * The particle stays alive and slides along the plane.
+     */
+    CLAMP = "CLAMP",
+    /**
+     * Bounce the particle off the plane.
+     * The velocity is reflected across the plane normal and dampened.
+     * Use `dampen` to control energy loss on bounce.
+     */
+    BOUNCE = "BOUNCE"
+}
+/**
+ * Defines the simulation backend used for particle updates.
+ *
+ * @enum {string}
+ */
+declare const enum SimulationBackend {
+    /**
+     * Automatically select the best backend based on the renderer type.
+     * Uses GPU compute when a WebGPU-capable renderer is detected, otherwise falls back to CPU.
+     */
+    AUTO = "AUTO",
+    /**
+     * Force CPU-based simulation (JavaScript update loop).
+     * Always available regardless of renderer type.
+     */
+    CPU = "CPU",
+    /**
+     * Force GPU compute shader simulation.
+     * Requires a WebGPU-capable renderer (e.g. `THREE.WebGPURenderer`).
+     * Falls back to CPU if the renderer does not support compute.
+     */
+    GPU = "GPU"
+}
 
 /**
  * A fixed numerical value.
@@ -931,9 +979,12 @@ type Noise = {
     isActive: boolean;
     strength: number;
     noisePower: number;
+    frequency: number;
     positionAmount: number;
     rotationAmount: number;
     sizeAmount: number;
+    /** Pre-computed FBM normalisation divisor: `2 - 2^(-octaves)`. */
+    fbmMax: number;
     sampler?: FBM;
     offsets?: Array<number>;
 };
@@ -1111,6 +1162,76 @@ type NormalizedForceFieldConfig = {
     range: number;
     falloff: ForceFieldFalloff;
 };
+/**
+ * Configuration for a collision plane that constrains particle positions.
+ * Collision planes define infinite planes in 3D space. When a particle crosses
+ * from the front side (positive normal direction) to the back side, the
+ * configured response mode is triggered.
+ *
+ * @example
+ * ```typescript
+ * // Water surface — kill bubbles when they reach y=5
+ * const waterSurface: CollisionPlaneConfig = {
+ *   position: { x: 0, y: 5, z: 0 },
+ *   normal: { x: 0, y: -1, z: 0 },
+ *   mode: CollisionPlaneMode.KILL,
+ * };
+ *
+ * // Bouncy floor
+ * const floor: CollisionPlaneConfig = {
+ *   position: { x: 0, y: 0, z: 0 },
+ *   normal: { x: 0, y: 1, z: 0 },
+ *   mode: CollisionPlaneMode.BOUNCE,
+ *   dampen: 0.6,
+ * };
+ *
+ * // Invisible wall clamp
+ * const wall: CollisionPlaneConfig = {
+ *   position: { x: 5, y: 0, z: 0 },
+ *   normal: { x: -1, y: 0, z: 0 },
+ *   mode: CollisionPlaneMode.CLAMP,
+ * };
+ * ```
+ */
+type CollisionPlaneConfig = {
+    /** Whether this collision plane is active. @default true */
+    isActive?: boolean;
+    /** A point on the plane surface. @default (0,0,0) */
+    position?: Point3D;
+    /**
+     * The plane normal vector (will be normalized internally).
+     * Defines the "front" side of the plane. Particles crossing from front
+     * to back trigger the collision response.
+     * @default (0,1,0)
+     */
+    normal?: Point3D;
+    /** The collision response mode. @default CollisionPlaneMode.KILL */
+    mode?: CollisionPlaneMode;
+    /**
+     * Energy retention factor for BOUNCE mode (0–1).
+     * 0 = no bounce (all energy absorbed), 1 = perfect bounce (no energy loss).
+     * @default 0.5
+     */
+    dampen?: number;
+    /**
+     * Fraction of the particle's start lifetime to subtract on collision (0–1).
+     * Applied on each collision for BOUNCE mode; ignored for KILL and CLAMP.
+     * @default 0
+     */
+    lifetimeLoss?: number;
+};
+/**
+ * Internal normalized collision plane configuration where all properties are required.
+ * Created during particle system initialization from user-provided {@link CollisionPlaneConfig}.
+ */
+type NormalizedCollisionPlaneConfig = {
+    isActive: boolean;
+    position: THREE.Vector3;
+    normal: THREE.Vector3;
+    mode: CollisionPlaneMode;
+    dampen: number;
+    lifetimeLoss: number;
+};
 /**
  * Configuration object for the particle system.
  * Defines all aspects of the particle system, including its appearance, behavior, and runtime events.
@@ -1344,6 +1465,18 @@ type ParticleSystemConfig = {
      * simulationSpace: SimulationSpace.WORLD;
      */
     simulationSpace?: SimulationSpace;
+    /**
+     * Selects the simulation backend for particle updates.
+     *
+     * - `AUTO` (default): Uses GPU compute when a WebGPU-capable renderer is
+     *   detected, otherwise falls back to CPU.
+     * - `CPU`: Always uses the JavaScript update loop (works with any renderer).
+     * - `GPU`: Requests GPU compute simulation. Falls back to CPU if the renderer
+     *   does not support compute shaders.
+     *
+     * @default SimulationBackend.AUTO
+     */
+    simulationBackend?: SimulationBackend;
     /**
      * Defines the maximum number of particles allowed in the system.
      * This value limits the total number of active particles at any given time.
@@ -1635,6 +1768,31 @@ type ParticleSystemConfig = {
      * ```
      */
     forceFields?: Array<ForceFieldConfig>;
+    /**
+     * Collision planes that constrain particle positions.
+     *
+     * Each plane defines an infinite surface in 3D space. When a particle crosses
+     * from the front side (positive normal direction) to the back side, the
+     * configured response mode is triggered: KILL (remove), CLAMP (stop at surface),
+     * or BOUNCE (reflect with energy loss).
+     *
+     * Plane positions and normals are in world space. Multiple planes are checked
+     * in order; for KILL mode, the first collision deactivates the particle.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * collisionPlanes: [
+     *   {
+     *     position: { x: 0, y: 5, z: 0 },
+     *     normal: { x: 0, y: -1, z: 0 },
+     *     mode: CollisionPlaneMode.KILL,
+     *   },
+     * ]
+     * ```
+     */
+    collisionPlanes?: Array<CollisionPlaneConfig>;
     /**
      * Called on every update frame with particle system data.
      */
@@ -1745,10 +1903,8 @@ type MappedAttributes = {
     startFrame: AnyBufferAttribute;
     size: AnyBufferAttribute;
     rotation: AnyBufferAttribute;
-    colorR: AnyBufferAttribute;
-    colorG: AnyBufferAttribute;
-    colorB: AnyBufferAttribute;
-    colorA: AnyBufferAttribute;
+    /** Packed RGBA color (vec4). */
+    color: AnyBufferAttribute;
     /** Packed quaternion vec4 for 3D mesh rotation (only present for RendererType.MESH). */
     quat?: AnyBufferAttribute;
 };
@@ -1756,6 +1912,10 @@ type ParticleSystemInstance = {
     particleSystem: THREE.Points | THREE.Mesh;
     wrapper?: Gyroscope;
     mappedAttributes: MappedAttributes;
+    /** Shared interleaved Float32Array backing all scalar per-particle attributes. */
+    scalarArray: Float32Array;
+    /** The InterleavedBuffer (or InstancedInterleavedBuffer) for scalar attributes. */
+    scalarInterleavedBuffer: THREE.InterleavedBuffer;
     elapsedUniform: {
         value: number;
     };
@@ -1778,6 +1938,7 @@ type ParticleSystemInstance = {
     simulationSpace: SimulationSpace;
     gravity: number;
     normalizedForceFields: Array<NormalizedForceFieldConfig>;
+    normalizedCollisionPlanes: Array<NormalizedCollisionPlaneConfig>;
     emission: Emission;
     normalizedConfig: NormalizedParticleSystemConfig;
     iterationCount: number;
@@ -1828,6 +1989,20 @@ type ParticleSystemInstance = {
         twistPrevention: boolean;
         ribbonId?: number;
     };
+    /** GPU compute pipeline for WebGPU simulation. Opaque type to avoid pulling TSL types into DTS. */
+    computePipeline?: {
+        computeNode: unknown;
+        uniforms: Record<string, unknown>;
+        buffers: Record<string, unknown>;
+        forceFieldInfo: {
+            offset: number;
+            countUniform: unknown;
+        } | null;
+    };
+    /** Whether this system uses GPU compute for simulation. */
+    useGPUCompute?: boolean;
+    /** Flag set by update loop, consumed by onBeforeRender to dispatch compute. */
+    computeDispatchReady?: boolean;
 };
 /**
  * Represents a particle system instance, providing methods to control and manage its lifecycle.
@@ -1855,6 +2030,8 @@ type ParticleSystem = {
     pauseEmitter: () => void;
     dispose: () => void;
     update: (cycleData: CycleData) => void;
+    /** GPU compute node for WebGPU dispatch. Call `renderer.compute(computeNode)` before `renderer.render()`. Null when CPU simulation. */
+    computeNode: unknown | null;
     /**
      * Updates the particle system configuration at runtime without recreating the system.
      *
@@ -2083,15 +2260,93 @@ declare const getCurveFunction: (curveFunctionId: CurveFunctionId | CurveFunctio
  * @see {@link VelocityOverLifetime} - Configuration for velocity modifiers
  * @see {@link NoiseConfig} - Configuration for noise-based effects
  */
-declare const applyModifiers: ({ delta, generalData, normalizedConfig, attributes, particleLifetimePercentage, particleIndex, }: {
+declare const applyModifiers: ({ delta, generalData, normalizedConfig, attributes, scalarArray, particleLifetimePercentage, particleIndex, }: {
     delta: number;
     generalData: GeneralData;
     normalizedConfig: NormalizedParticleSystemConfig;
     attributes: MappedAttributes;
+    scalarArray: Float32Array;
     particleLifetimePercentage: number;
     particleIndex: number;
 }) => void;
 
+/**
+ * Checks whether the given renderer supports GPU compute dispatches.
+ *
+ * Uses duck-typing: a renderer is considered WebGPU-capable when it exposes
+ * a `.compute()` method and a `.hasFeature()` method (both present on
+ * `THREE.WebGPURenderer` but absent from `THREE.WebGLRenderer`).
+ *
+ * @param renderer - Any Three.js renderer instance.
+ * @returns `true` when the renderer supports compute shaders.
+ */
+declare function isComputeCapableRenderer(renderer: unknown): boolean;
+/**
+ * Resolves the effective simulation backend based on the user's preference
+ * and the capabilities of the provided renderer.
+ *
+ * | Preference | WebGPURenderer | WebGLRenderer |
+ * |------------|---------------|---------------|
+ * | `AUTO`     | `GPU`         | `CPU`         |
+ * | `CPU`      | `CPU`         | `CPU`         |
+ * | `GPU`      | `GPU`         | `CPU` (fallback) |
+ *
+ * @param renderer - The Three.js renderer instance used for rendering.
+ * @param preference - The user-specified simulation backend preference.
+ * @returns The resolved {@link SimulationBackend} (`CPU` or `GPU`).
+ */
+declare function resolveSimulationBackend(renderer: unknown, preference?: SimulationBackend): SimulationBackend.CPU | SimulationBackend.GPU;
+
+/**
+ * Serializes a `ParticleSystemConfig` to a JSON string.
+ *
+ * - `THREE.Vector3` / `THREE.Vector2` are converted to plain `{x, y, z}` / `{x, y}` objects.
+ * - `renderer.blending` is converted to its string identifier (e.g. `"THREE.AdditiveBlending"`).
+ * - `EasingCurve.curveFunction` is replaced by a `curveFunctionId` string.
+ *   Only predefined `CurveFunctionId` functions can be serialized; custom functions throw.
+ * - `THREE.Texture` (`map`), callback fields (`onUpdate`, `onComplete`) are omitted.
+ * - An `_editorData` field and other unknown fields are preserved as-is.
+ * - A `_version` field is added for forward-compatibility.
+ *
+ * @param config - The particle system configuration to serialize.
+ * @returns A JSON string representation of the config.
+ * @throws If the config contains a custom (non-predefined) `curveFunction`.
+ *
+ * @example
+ * ```typescript
+ * import { serializeParticleSystem } from '@newkrok/three-particles';
+ *
+ * const json = serializeParticleSystem(config);
+ * localStorage.setItem('myEffect', json);
+ * ```
+ */
+declare function serializeParticleSystem(config: ParticleSystemConfig): string;
+/**
+ * Deserializes a JSON string produced by `serializeParticleSystem` (or by the
+ * three-particles-editor) into a `ParticleSystemConfig` object.
+ *
+ * - Blending strings (e.g. `"THREE.AdditiveBlending"`) are converted back to
+ *   `THREE.Blending` constants.
+ * - `{x, y, z}` objects under `transform` are reconstructed as `THREE.Vector3`.
+ * - `{x, y}` objects under `textureSheetAnimation.tiles` are reconstructed as `THREE.Vector2`.
+ * - Legacy Bézier curves without a `type` field (editor format) are normalized.
+ * - Easing curves stored as `{ type: "EASING", curveFunctionId }` have their
+ *   `curveFunction` resolved from the predefined map.
+ * - `_editorData` and other unknown fields are preserved.
+ *
+ * @param json - A JSON string produced by `serializeParticleSystem` or the editor.
+ * @returns A fully reconstructed `ParticleSystemConfig`.
+ *
+ * @example
+ * ```typescript
+ * import { deserializeParticleSystem } from '@newkrok/three-particles';
+ *
+ * const config = deserializeParticleSystem(localStorage.getItem('myEffect')!);
+ * createParticleSystem(config);
+ * ```
+ */
+declare function deserializeParticleSystem(json: string): ParticleSystemConfig;
+
 /**
  * Calculates random position and velocity for particles emitted from a sphere.
  *
@@ -2255,6 +2510,106 @@ declare const isLifeTimeCurve: (value: Constant | RandomBetweenTwoConstants | Li
 declare const getCurveFunctionFromConfig: (particleSystemId: number, lifetimeCurve: LifetimeCurve) => CurveFunction;
 declare const calculateValue: (particleSystemId: number, value: Constant | RandomBetweenTwoConstants | LifetimeCurve, time?: number) => number;
 
+/**
+ * Interleaved scalar buffer layout constants.
+ *
+ * All per-particle float attributes (except position and quat) are packed
+ * into a single InterleavedBuffer to stay within the WebGPU vertex buffer
+ * limit of 8.
+ *
+ * Buffer layout per particle (stride = 10 floats):
+ * ```
+ * [isActive, lifetime, startLifetime, startFrame, size, rotation, colorR, colorG, colorB, colorA]
+ * ```
+ */
+/** Number of float32 elements per particle in the interleaved scalar buffer. */
+declare const SCALAR_STRIDE = 10;
+/** Offset for the isActive flag (0 = inactive, 1 = active). */
+declare const S_IS_ACTIVE = 0;
+/** Offset for the current lifetime of the particle in milliseconds. */
+declare const S_LIFETIME = 1;
+/** Offset for the total lifetime of the particle in milliseconds. */
+declare const S_START_LIFETIME = 2;
+/** Offset for the texture sheet animation start frame index. */
+declare const S_START_FRAME = 3;
+/** Offset for the particle size. */
+declare const S_SIZE = 4;
+/** Offset for the particle rotation (radians). */
+declare const S_ROTATION = 5;
+/** Offset for the red color channel (0..1). */
+declare const S_COLOR_R = 6;
+/** Offset for the green color channel (0..1). */
+declare const S_COLOR_G = 7;
+/** Offset for the blue color channel (0..1). */
+declare const S_COLOR_B = 8;
+/** Offset for the alpha (opacity) channel (0..1). */
+declare const S_COLOR_A = 9;
+
+type TSLMaterialFactory = {
+    createTSLParticleMaterial: (rendererType: RendererType, sharedUniforms: Record<string, {
+        value: unknown;
+    }>, rendererConfig: {
+        transparent: boolean;
+        blending: THREE.Blending;
+        depthTest: boolean;
+        depthWrite: boolean;
+    }, gpuCompute?: boolean) => THREE.Material;
+    createTSLTrailMaterial: (trailUniforms: Record<string, {
+        value: unknown;
+    }>, rendererConfig: {
+        transparent: boolean;
+        blending: THREE.Blending;
+        depthTest: boolean;
+        depthWrite: boolean;
+    }) => THREE.Material;
+    createComputePipeline?: (...args: any[]) => any;
+    writeParticleToModifierBuffers?: (...args: any[]) => void;
+    deactivateParticleInModifierBuffers?: (...args: any[]) => void;
+    flushEmitQueue?: (...args: any[]) => number;
+    registerCurveDataLength?: (...args: any[]) => void;
+    encodeForceFieldsForGPU?: (...args: any[]) => Float32Array;
+    encodeCollisionPlanesForGPU?: (...args: any[]) => Float32Array;
+};
+/**
+ * Registers the TSL (Three Shading Language) material factory for WebGPU support.
+ *
+ * Call this **once** before creating any particle systems that use WebGPU rendering.
+ * The factory functions are imported from the `@newkrok/three-particles/webgpu` sub-module.
+ *
+ * When registered, all particle systems will use TSL-based `NodeMaterial` (compiles to WGSL)
+ * instead of GLSL `ShaderMaterial`. If the factory also includes the GPU compute functions
+ * (`createComputePipeline`, `writeParticleToModifierBuffers`, etc.), particle systems with
+ * `simulationBackend: 'AUTO'` or `'GPU'` will run physics and modifiers on the GPU.
+ *
+ * @param factory - Object containing TSL material creators and optional GPU compute helpers.
+ *
+ * @example
+ * ```typescript
+ * import { registerTSLMaterialFactory } from '@newkrok/three-particles';
+ * import {
+ *   createTSLParticleMaterial,
+ *   createTSLTrailMaterial,
+ *   createComputePipeline,
+ *   writeParticleToModifierBuffers,
+ *   deactivateParticleInModifierBuffers,
+ *   flushEmitQueue,
+ *   registerCurveDataLength,
+ *   encodeForceFieldsForGPU,
+ * } from '@newkrok/three-particles/webgpu';
+ *
+ * registerTSLMaterialFactory({
+ *   createTSLParticleMaterial,
+ *   createTSLTrailMaterial,
+ *   createComputePipeline,
+ *   writeParticleToModifierBuffers,
+ *   deactivateParticleInModifierBuffers,
+ *   flushEmitQueue,
+ *   registerCurveDataLength,
+ *   encodeForceFieldsForGPU,
+ * });
+ * ```
+ */
+declare const registerTSLMaterialFactory: (factory: TSLMaterialFactory) => void;
 /**
  * Mapping of blending mode string identifiers to Three.js blending constants.
  *
@@ -2360,4 +2715,4 @@ declare const getDefaultParticleSystemConfig: () => any;
 declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
 declare const updateParticleSystems: (cycleData: CycleData) => void;
 
-export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MeshConfig, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, Shape, type ShapeConfig, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type CollisionPlaneConfig, CollisionPlaneMode, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type ForceFieldConfig, ForceFieldFalloff, ForceFieldType, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MappedAttributes, type MeshConfig, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedCollisionPlaneConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, SCALAR_STRIDE, S_COLOR_A, S_COLOR_B, S_COLOR_G, S_COLOR_R, S_IS_ACTIVE, S_LIFETIME, S_ROTATION, S_SIZE, S_START_FRAME, S_START_LIFETIME, Shape, type ShapeConfig, SimulationBackend, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, deserializeParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isComputeCapableRenderer, isLifeTimeCurve, registerTSLMaterialFactory, removeBezierCurveFunction, resolveSimulationBackend, serializeParticleSystem, updateParticleSystems };