@newkrok/three-particles 2.10.4 → 2.11.1

package/llms-full.txt

@@ -1,6 +1,6 @@
 # @newkrok/three-particles — Full API Reference
 
-> Three.js-based high-performance particle system library (v2.5.0)
+> Three.js-based high-performance particle system library (v2.11.0)
 > License: MIT | Author: Istvan Krisztian Somoracz
 > Repository: https://github.com/NewKrok/three-particles
 
@@ -12,7 +12,7 @@
 npm install @newkrok/three-particles three
 ```
 
-Peer dependency: `three` ^0.180.0
+Peer dependency: `three` ^0.182.0
 
 ---
 
@@ -62,7 +62,7 @@ function animate() {
 
 | Property/Method | Type | Description |
 |-----------------|------|-------------|
-| `instance` | `THREE.Points \| Gyroscope` | The renderable object — add to scene |
+| `instance` | `THREE.Points \| THREE.Mesh \| Gyroscope` | The renderable object — add to scene (Mesh when using RendererType.INSTANCED) |
 | `pauseEmitter()` | `() => void` | Stop emitting new particles |
 | `resumeEmitter()` | `() => void` | Resume emitting particles |
 | `dispose()` | `() => void` | Destroy system, free resources |
@@ -337,7 +337,15 @@ type Renderer = {
   transparent: boolean;                 // Default: true
   depthTest: boolean;                   // Default: true
   depthWrite: boolean;                  // Default: false
+  rendererType?: RendererType;          // Default: RendererType.POINTS
 };
+
+enum RendererType {
+  POINTS = 'POINTS',       // Classic point sprites (THREE.Points). Default.
+  INSTANCED = 'INSTANCED', // Camera-facing quads via InstancedBufferGeometry.
+                            // Removes gl_PointSize hardware limit, supports large particles.
+                            // Recommended for 10 000+ particles or large on-screen sizes.
+}
 ```
 
 Common blending modes: `THREE.NormalBlending`, `THREE.AdditiveBlending`, `THREE.SubtractiveBlending`
@@ -417,6 +425,9 @@ const system = createParticleSystem({
 ### LifeTimeCurve
 `BEZIER` | `EASING`
 
+### RendererType
+`POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit)
+
 ---
 
 ## Callbacks
@@ -425,7 +436,7 @@ const system = createParticleSystem({
 createParticleSystem({
   // Called every frame
   onUpdate: ({ particleSystem, delta, elapsed, lifetime, iterationCount }) => {
-    // particleSystem: THREE.Points instance
+    // particleSystem: THREE.Points or THREE.Mesh instance
     // delta: seconds since last frame
     // elapsed: total seconds
     // lifetime: system duration
@@ -514,6 +525,171 @@ scene.add(fire.instance);
 
 ---
 
+## Sub-Emitters
+
+Trigger child particle systems when particles are born or die.
+
+```typescript
+type SubEmitter = {
+  trigger: SubEmitterTrigger;  // BIRTH or DEATH
+  config: ParticleSystemConfig; // The child particle system config
+};
+
+// Usage
+createParticleSystem({
+  // ... main system config
+  subEmitters: [
+    { trigger: SubEmitterTrigger.BIRTH, config: sparkConfig },
+    { trigger: SubEmitterTrigger.DEATH, config: explosionConfig },
+  ],
+});
+```
+
+### SubEmitterTrigger
+- `BIRTH` — Spawns child system at the position of each newly created particle
+- `DEATH` — Spawns child system at the position of each dying particle
+
+---
+
+## Force Fields
+
+Apply forces to particles dynamically. Supports point attraction/repulsion and directional wind.
+
+```typescript
+type ForceField = {
+  type: ForceFieldType;         // POINT or DIRECTIONAL
+  position?: Point3D;           // For POINT type — center of force
+  direction?: Point3D;          // For DIRECTIONAL type — force direction
+  strength: number;             // Force strength (negative = repulsion for POINT)
+  radius?: number;              // For POINT type — area of effect
+  falloff?: ForceFieldFalloff;  // NONE, LINEAR, or QUADRATIC
+};
+```
+
+### ForceFieldType
+- `POINT` — Attracts (positive strength) or repels (negative strength) particles toward/from a point
+- `DIRECTIONAL` — Applies a constant force in a direction (e.g., wind)
+
+### ForceFieldFalloff
+- `NONE` — Constant force regardless of distance
+- `LINEAR` — Force decreases linearly with distance
+- `QUADRATIC` — Force decreases with the square of distance (realistic gravity-like falloff)
+
+**Example — Vortex with wind:**
+```typescript
+createParticleSystem({
+  // ... particle config
+  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,
+    },
+  ],
+});
+```
+
+---
+
+## Serialization
+
+Save and load particle system configurations as JSON.
+
+```typescript
+import {
+  serializeParticleSystemConfig,
+  deserializeParticleSystemConfig,
+} from "@newkrok/three-particles";
+
+// Serialize (config → JSON-safe object)
+const json = serializeParticleSystemConfig(config);
+const jsonString = JSON.stringify(json);
+
+// Deserialize (JSON-safe object → config)
+const restored = deserializeParticleSystemConfig(JSON.parse(jsonString));
+const system = createParticleSystem(restored);
+```
+
+---
+
+## Usage with React Three Fiber
+
+The library works with [React Three Fiber](https://github.com/pmndrs/react-three-fiber) without any additional wrapper package. 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} />;
+}
+```
+
+### Key Integration Points
+
+- **`useEffect`** — Create the particle system on mount, dispose on unmount
+- **`useFrame`** — Drive per-frame updates using R3F's render loop (use `system.update()` for individual system control instead of the global `updateParticleSystems()`)
+- **`<group ref>`** — Attach `system.instance` to a group so R3F manages the scene graph
+- **Config changes** — Pass `config` as a dependency to `useEffect` to recreate on changes
+- **No wrapper package needed** — The imperative API integrates naturally with React hooks
+
+---
+
 ## Links
 
 - Repository: https://github.com/NewKrok/three-particles

package/llms.txt

@@ -69,6 +69,12 @@ function animate() {
 | 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
 
 ## Emitter Shapes
 
@@ -112,6 +118,68 @@ Values support: constant `number`, random `{ min, max }`, or curves:
 { 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,
+  },
+]
+```
+
+## 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 "@newkrok/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/NewKrok/three-particles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newkrok/three-particles",
-  "version": "2.10.4",
+  "version": "2.11.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",