@newkrok/three-particles 2.11.2 → 2.13.0

package/llms-full.txt

@@ -338,6 +338,8 @@ type Renderer = {
   depthTest: boolean;                   // Default: true
   depthWrite: boolean;                  // Default: false
   rendererType?: RendererType;          // Default: RendererType.POINTS
+  trail?: TrailConfig;                  // Only for RendererType.TRAIL
+  mesh?: MeshConfig;                    // Only for RendererType.MESH
 };
 
 enum RendererType {
@@ -345,11 +347,103 @@ 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.
+  MESH = 'MESH',           // 3D mesh particles via GPU instancing. Each particle is rendered
+                            // as a full 3D mesh with quaternion-based rotation, normals, and
+                            // directional lighting. Any THREE.BufferGeometry can be used.
 }
+
+type MeshConfig = {
+  geometry: THREE.BufferGeometry;  // The geometry to render for each particle
+};
 ```
 
 Common blending modes: `THREE.NormalBlending`, `THREE.AdditiveBlending`, `THREE.SubtractiveBlending`
 
+### Mesh Particle Configuration
+
+When using `RendererType.MESH`, configure mesh-specific properties 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),
+  },
+}
+```
+
+Mesh particle features:
+- GPU instancing (`InstancedBufferGeometry`) — one draw call for all particles
+- Quaternion-based 3D rotation (particles rotate in all 3 axes)
+- Normals preserved from the source geometry, simple directional lighting from camera
+- Any `THREE.BufferGeometry` works: `BoxGeometry`, `SphereGeometry`, `IcosahedronGeometry`, custom meshes, etc.
+- All modifiers work: sizeOverLifetime, colorOverLifetime, opacityOverLifetime, rotationOverLifetime, noise, force fields, sub-emitters
+- Default texture: solid white 1×1 (preserves mesh shape); point/billboard renderers default to a circle texture
+- Sub-emitter note: sub-emitters do not inherit `RendererType.MESH` or `RendererType.TRAIL` from the parent because mesh geometry and trail config cannot be passed through; sub-emitters fall back to their own `rendererType` or `POINTS` by default
+- Note: `mesh.geometry` is a runtime object (not serializable to JSON); provide it programmatically
+
+### 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
@@ -426,7 +520,7 @@ const system = createParticleSystem({
 `BEZIER` | `EASING`
 
 ### RendererType
-`POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit)
+`POINTS` (default — classic point sprites) | `INSTANCED` (GPU instanced quads, no gl_PointSize limit) | `TRAIL` (ribbon trails behind particles) | `MESH` (3D mesh particles via GPU instancing)
 
 ---
 

package/llms.txt

@@ -75,6 +75,53 @@ 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
+- `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
 

package/package.json

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