@newkrok/three-particles 2.11.1 → 2.12.0

package/llms-full.txt

@@ -345,11 +345,69 @@ enum RendererType {
   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.
+  TRAIL = 'TRAIL',         // Ribbon trails behind particles. Each particle records a position
+                            // history and the renderer builds a camera-facing triangle-strip
+                            // ribbon through those samples.
 }
 ```
 
 Common blending modes: `THREE.NormalBlending`, `THREE.AdditiveBlending`, `THREE.SubtractiveBlending`
 
+### Trail / Ribbon Configuration
+
+When using `RendererType.TRAIL`, configure trail-specific properties via `renderer.trail`:
+
+```typescript
+type TrailConfig = {
+  length?: number;              // Position history samples per particle. Default: 20
+  width?: number;               // Base ribbon width in world units. Default: 1.0
+  widthOverTrail?: LifetimeCurve;   // Width taper from head (0) to tail (1)
+  opacityOverTrail?: LifetimeCurve; // Opacity taper from head (0) to tail (1)
+  colorOverTrail?: {            // Optional per-channel color multiplier curves
+    isActive: boolean;
+    r: LifetimeCurve;           // Red channel multiplier (0=head, 1=tail)
+    g: LifetimeCurve;           // Green channel multiplier
+    b: LifetimeCurve;           // Blue channel multiplier
+  };
+};
+```
+
+Trail features:
+- GPU billboard rendering (vertex shader computes perpendicular offset from camera direction)
+- Soft-edge fade on ribbon borders (no hard edges)
+- Optional texture mapping (texture modulates brightness via luminance)
+- `colorOverTrail` multiplies the particle's current color at each trail position — use white `startColor` for full color transitions
+- Works with all particle features: colorOverLifetime, noise, gravity, force fields
+
+Example — comet trail with color shift:
+
+```typescript
+renderer: {
+  rendererType: RendererType.TRAIL,
+  blending: THREE.AdditiveBlending,
+  transparent: true,
+  depthWrite: false,
+  trail: {
+    length: 60,
+    width: 0.5,
+    widthOverTrail: {
+      type: LifeTimeCurve.BEZIER,
+      bezierPoints: [
+        { x: 0, y: 1, percentage: 0 },
+        { x: 0.5, y: 0.4 },
+        { x: 1, y: 0, percentage: 1 },
+      ],
+    },
+    colorOverTrail: {
+      isActive: true,
+      r: { type: LifeTimeCurve.BEZIER, bezierPoints: [{ x: 0, y: 0.2, percentage: 0 }, { x: 0.5, y: 0.5 }, { x: 1, y: 0.8, percentage: 1 }] },
+      g: { type: LifeTimeCurve.BEZIER, bezierPoints: [{ x: 0, y: 1.0, percentage: 0 }, { x: 0.5, y: 0.5 }, { x: 1, y: 0.1, percentage: 1 }] },
+      b: { type: LifeTimeCurve.BEZIER, bezierPoints: [{ x: 0, y: 0.4, percentage: 0 }, { x: 0.5, y: 0.9 }, { x: 1, y: 1.0, percentage: 1 }] },
+    },
+  },
+}
+```
+
 ---
 
 ## Texture Sheet Animation

package/llms.txt

@@ -75,6 +75,33 @@ function animate() {
 
 - `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
+
+## 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
 

package/package.json

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