@newkrok/three-particles 2.10.4 → 2.11.1

package/README.md

@@ -19,6 +19,7 @@ Particle system for ThreeJS.
 *   Force fields and attractors for dynamic particle behavior (point attraction/repulsion, directional wind).
 *   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.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples
@@ -66,6 +67,78 @@ scene.add(instance);
 updateParticleSystems({now, delta, elapsed});
 ```
 
+# Usage with React Three Fiber
+
+The library works seamlessly with [React Three Fiber](https://github.com/pmndrs/react-three-fiber). No additional wrapper package is needed — use `createParticleSystem` directly with React hooks:
+
+```tsx
+import { useRef, useEffect } from "react";
+import { useFrame } from "@react-three/fiber";
+import {
+  createParticleSystem,
+  Shape,
+  type ParticleSystem,
+} from "@newkrok/three-particles";
+import * as THREE from "three";
+
+function FireEffect({ config }: { config?: Record<string, unknown> }) {
+  const groupRef = useRef<THREE.Group>(null);
+  const systemRef = useRef<ParticleSystem | null>(null);
+
+  useEffect(() => {
+    const system = createParticleSystem({
+      duration: 5,
+      looping: true,
+      maxParticles: 200,
+      startLifetime: { min: 0.5, max: 1.5 },
+      startSpeed: { min: 1, max: 3 },
+      startSize: { min: 0.3, max: 0.8 },
+      startColor: {
+        min: { r: 1, g: 0.2, b: 0 },
+        max: { r: 1, g: 0.8, b: 0 },
+      },
+      gravity: -1,
+      emission: { rateOverTime: 50 },
+      shape: { shape: Shape.CONE, cone: { angle: 0.2, radius: 0.3 } },
+      renderer: {
+        blending: THREE.AdditiveBlending,
+        transparent: true,
+        depthWrite: false,
+      },
+      ...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} />;
+}
+
+// In your R3F Canvas:
+// <Canvas>
+//   <FireEffect />
+// </Canvas>
+```
+
+**Key points:**
+- Use `useEffect` to create and dispose the particle system
+- Use `useFrame` to drive updates each frame (call `system.update()` instead of `updateParticleSystems()` for per-system control)
+- Add the `system.instance` to a `<group>` ref so R3F manages the scene graph
+- Return a cleanup function from `useEffect` that calls `system.dispose()`
+
 # Documentation
 
 Automatically generated TypeDoc: [https://newkrok.github.io/three-particles/api/](https://newkrok.github.io/three-particles/api/)

package/dist/index.d.ts

@@ -151,6 +151,26 @@ declare const enum ForceFieldType {
      */
     DIRECTIONAL = "DIRECTIONAL"
 }
+/**
+ * Defines the rendering technique used for particles.
+ *
+ * @enum {string}
+ */
+declare const enum RendererType {
+    /**
+     * Render particles as point sprites using `THREE.Points`.
+     * This is the default renderer, efficient for small to medium particle counts.
+     * Note: point size is limited by `gl_PointSize` hardware caps (typically 64–256 px).
+     */
+    POINTS = "POINTS",
+    /**
+     * Render particles as camera-facing quads using `THREE.InstancedBufferGeometry`.
+     * Removes the `gl_PointSize` hardware limit, supports stretched billboards,
+     * and enables batching multiple emitters into fewer draw calls.
+     * Recommended for 10 000+ particles or when large on-screen particle sizes are needed.
+     */
+    INSTANCED = "INSTANCED"
+}
 /**
  * Defines how force diminishes with distance from a POINT force field center.
  * Only applicable to {@link ForceFieldType.POINT} force fields.
@@ -643,6 +663,16 @@ type Renderer = {
     transparent: boolean;
     depthTest: boolean;
     depthWrite: boolean;
+    /**
+     * Selects the rendering technique for particles.
+     *
+     * - `RendererType.POINTS` (default) — classic point-sprite renderer using `THREE.Points`.
+     * - `RendererType.INSTANCED` — camera-facing quads via `InstancedBufferGeometry`,
+     *   removing the `gl_PointSize` hardware limit and enabling stretched billboards.
+     *
+     * @default RendererType.POINTS
+     */
+    rendererType?: RendererType;
 };
 /**
  * Configuration for noise effects applied to particles in a particle system.
@@ -1392,7 +1422,7 @@ type ParticleSystemConfig = {
      * Called on every update frame with particle system data.
      */
     onUpdate?: (data: {
-        particleSystem: THREE.Points;
+        particleSystem: THREE.Points | THREE.Mesh;
         delta: number;
         elapsed: number;
         lifetime: number;
@@ -1453,15 +1483,36 @@ type GeneralData = {
     /** Tracks the state of each burst emission event */
     burstStates?: Array<BurstState>;
 };
+/** Union of all buffer attribute types Three.js uses in geometry. */
+type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
+/**
+ * A view that maps standard attribute names (e.g. 'position', 'size') to
+ * their actual geometry attribute objects, which may have different names
+ * in the instanced renderer (e.g. 'instanceOffset', 'instanceSize').
+ */
+type MappedAttributes = {
+    position: AnyBufferAttribute;
+    isActive: AnyBufferAttribute;
+    lifetime: AnyBufferAttribute;
+    startLifetime: AnyBufferAttribute;
+    startFrame: AnyBufferAttribute;
+    size: AnyBufferAttribute;
+    rotation: AnyBufferAttribute;
+    colorR: AnyBufferAttribute;
+    colorG: AnyBufferAttribute;
+    colorB: AnyBufferAttribute;
+    colorA: AnyBufferAttribute;
+};
 type ParticleSystemInstance = {
-    particleSystem: THREE.Points;
+    particleSystem: THREE.Points | THREE.Mesh;
     wrapper?: Gyroscope;
+    mappedAttributes: MappedAttributes;
     elapsedUniform: {
         value: number;
     };
     generalData: GeneralData;
     onUpdate: (data: {
-        particleSystem: THREE.Points;
+        particleSystem: THREE.Points | THREE.Mesh;
         delta: number;
         elapsed: number;
         lifetime: number;
@@ -1469,7 +1520,7 @@ type ParticleSystemInstance = {
         iterationCount: number;
     }) => void;
     onComplete: (data: {
-        particleSystem: THREE.Points;
+        particleSystem: THREE.Points | THREE.Mesh;
     }) => void;
     creationTime: number;
     lastEmissionTime: number;
@@ -1515,7 +1566,7 @@ type ParticleSystemInstance = {
  * particleSystem.dispose(); // Cleanup the particle system
  */
 type ParticleSystem = {
-    instance: THREE.Points | Gyroscope;
+    instance: THREE.Points | THREE.Mesh | Gyroscope;
     resumeEmitter: () => void;
     pauseEmitter: () => void;
     dispose: () => void;
@@ -1719,7 +1770,7 @@ declare const applyModifiers: ({ delta, generalData, normalizedConfig, attribute
     delta: number;
     generalData: GeneralData;
     normalizedConfig: NormalizedParticleSystemConfig;
-    attributes: THREE.NormalBufferAttributes;
+    attributes: MappedAttributes;
     particleLifetimePercentage: number;
     particleIndex: number;
 }) => void;
@@ -1985,4 +2036,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 MinMaxColor, type Noise, type NoiseConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, type Rgb, Shape, type ShapeConfig, SimulationSpace, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };
+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 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 Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };