@newkrok/three-particles 2.13.0 → 2.14.1

package/README.md

@@ -3,10 +3,12 @@
 </p>
 
 # THREE Particles
-[![Run Tests](https://github.com/NewKrok/three-particles/actions/workflows/test.yml/badge.svg)](https://github.com/NewKrok/three-particles/actions/workflows/test.yml)
-[![NPM Version](https://img.shields.io/npm/v/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
-[![NPM Downloads](https://img.shields.io/npm/dw/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
-[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@newkrok/three-particles)](https://bundlephobia.com/package/@newkrok/three-particles)
+[![npm](https://img.shields.io/npm/v/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
+[![downloads](https://img.shields.io/npm/dm/@newkrok/three-particles.svg)](https://www.npmjs.com/package/@newkrok/three-particles)
+[![CI](https://github.com/NewKrok/three-particles/actions/workflows/ci.yml/badge.svg)](https://github.com/NewKrok/three-particles/actions/workflows/ci.yml)
+[![gzip](https://img.shields.io/bundlephobia/minzip/@newkrok/three-particles)](https://bundlephobia.com/package/@newkrok/three-particles)
+[![license](https://img.shields.io/npm/l/@newkrok/three-particles.svg)](https://github.com/NewKrok/three-particles/blob/master/LICENSE)
+[![docs](https://img.shields.io/badge/docs-online-blue)](https://newkrok.github.io/three-particles/api/)
 
 Particle system for ThreeJS.
 
@@ -22,6 +24,7 @@ Particle system for ThreeJS.
 *   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.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples

package/dist/index.d.ts

@@ -697,6 +697,59 @@ type TrailConfig = {
         g: LifetimeCurve;
         b: LifetimeCurve;
     };
+    /**
+     * Minimum distance (in world units) a particle must travel before a new
+     * trail sample is recorded. When set, the trail becomes frame-rate
+     * independent — at high FPS the samples are spread further apart in time,
+     * at low FPS they cluster around sharp turns.
+     *
+     * When `0` or `undefined`, a sample is recorded every frame (legacy behavior).
+     * @default 0
+     */
+    minVertexDistance?: number;
+    /**
+     * Maximum trail duration in seconds. Trail segments older than this value
+     * are faded out and expired, regardless of the ring-buffer `length`.
+     * This enables time-based trail length (e.g. "2-second trails") in addition
+     * to the segment-count cap.
+     *
+     * When `0` or `undefined`, trail length is governed only by `length`.
+     * @default 0
+     */
+    maxTime?: number;
+    /**
+     * Enable Catmull-Rom spline interpolation between history samples.
+     * Inserts additional subdivided points between raw samples, eliminating
+     * sharp kinks at trail bends. The `smoothingSubdivisions` property controls
+     * how many extra points are inserted per segment.
+     *
+     * @default false
+     */
+    smoothing?: boolean;
+    /**
+     * Number of Catmull-Rom subdivisions inserted between each pair of raw
+     * history samples when `smoothing` is enabled. Higher values produce
+     * smoother curves at the cost of more vertices.
+     *
+     * @default 3
+     */
+    smoothingSubdivisions?: number;
+    /**
+     * Enable twist prevention for the ribbon. Uses frame tracking to maintain
+     * consistent ribbon orientation during rapid direction changes, preventing
+     * self-intersecting or flipped ribbon quads.
+     *
+     * @default false
+     */
+    twistPrevention?: boolean;
+    /**
+     * Connect multiple particles into a single continuous ribbon.
+     * All particles that share the same `ribbonId` are sorted by age and
+     * their positions are chained into one continuous strip.
+     *
+     * When `undefined`, each particle has its own independent trail (default behavior).
+     */
+    ribbonId?: number;
 };
 /**
  * Configuration for the mesh particle renderer.
@@ -790,6 +843,53 @@ type Renderer = {
      * @see MeshConfig
      */
     mesh?: MeshConfig;
+    /**
+     * Soft particles configuration.
+     * When enabled, particles fade smoothly near opaque geometry instead of
+     * producing a hard intersection line. Requires a depth texture from a
+     * `WebGLRenderTarget`.
+     *
+     * @see SoftParticlesConfig
+     */
+    softParticles?: SoftParticlesConfig;
+};
+/**
+ * Configuration for soft (depth-faded) particles.
+ * When enabled, particles fade out smoothly near opaque geometry instead
+ * of producing a hard intersection line.
+ *
+ * Requires a depth texture from a `WebGLRenderTarget` with `DepthTexture`.
+ * If `depthTexture` is not provided, soft particles are automatically disabled
+ * regardless of the `enabled` flag.
+ *
+ * @property enabled - Whether soft particle fading is active. @default false
+ * @property intensity - Controls the fade distance in world units. Higher values
+ *   produce a wider fade zone. Typical range: 0.1 to 5.0. @default 1.0
+ * @property depthTexture - A `THREE.DepthTexture` attached to the render target
+ *   that contains the scene's depth pass. Must be updated every frame before
+ *   the particle system renders.
+ *
+ * @example
+ * // Create a render target with a depth texture
+ * const rt = new THREE.WebGLRenderTarget(width, height, {
+ *   depthTexture: new THREE.DepthTexture(width, height),
+ * });
+ *
+ * // Pass it to the particle system config
+ * const config = {
+ *   renderer: {
+ *     softParticles: {
+ *       enabled: true,
+ *       intensity: 1.5,
+ *       depthTexture: rt.depthTexture,
+ *     },
+ *   },
+ * };
+ */
+type SoftParticlesConfig = {
+    enabled?: boolean;
+    intensity?: number;
+    depthTexture?: THREE.DepthTexture;
 };
 /**
  * Configuration for noise effects applied to particles in a particle system.
@@ -1613,6 +1713,22 @@ type GeneralData = {
     trailLength?: number;
     /** Cached camera world position, updated each frame via onBeforeRender for billboard trails. */
     trailCameraPosition?: THREE.Vector3;
+    /**
+     * Timestamp (in ms) when each trail history sample was recorded.
+     * Used by `maxTime` to expire old segments.
+     * Layout: `maxParticles * trailLength` entries.
+     */
+    trailSampleTimes?: Float64Array;
+    /**
+     * Last recorded position per particle for adaptive sampling (`minVertexDistance`).
+     * Layout: `maxParticles * 3` (x, y, z).
+     */
+    trailLastSampledPosition?: Float32Array;
+    /**
+     * Per-particle previous ribbon normal vector for twist prevention.
+     * Layout: `maxParticles * 3` (nx, ny, nz).
+     */
+    trailPrevNormal?: Float32Array;
 };
 /** Union of all buffer attribute types Three.js uses in geometry. */
 type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
@@ -1695,10 +1811,16 @@ type ParticleSystemInstance = {
         g: CurveFunction;
         b: CurveFunction;
     };
-    /** Trail config (length, width) */
+    /** Trail config (length, width, and advanced features) */
     trailConfig?: {
         length: number;
         width: number;
+        minVertexDistance: number;
+        maxTime: number;
+        smoothing: boolean;
+        smoothingSubdivisions: number;
+        twistPrevention: boolean;
+        ribbonId?: number;
     };
 };
 /**
@@ -2199,4 +2321,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 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 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 };