@newkrok/three-particles 2.11.1 → 2.12.0

package/README.md

@@ -20,6 +20,7 @@ Particle system for ThreeJS.
 *   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.
+*   Trail / Ribbon renderer (`RendererType.TRAIL`) — continuous ribbon trails behind particles with configurable width, opacity, and color tapering.
 *   TypeDoc API documentation available.
 
 # Live Demo & Examples

package/dist/index.d.ts

@@ -169,7 +169,18 @@ declare const enum RendererType {
      * 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"
+    INSTANCED = "INSTANCED",
+    /**
+     * Render each particle as a ribbon trail connecting its current and previous positions.
+     * Each particle stores a configurable number of position history samples, and the
+     * renderer builds a camera-facing triangle-strip ribbon through those samples.
+     *
+     * Trail width and opacity can taper along the ribbon length for effects like
+     * sword slashes, magic missiles, comet tails, and speed lines.
+     *
+     * Configure trail-specific properties via {@link TrailConfig} on the renderer.
+     */
+    TRAIL = "TRAIL"
 }
 /**
  * Defines how force diminishes with distance from a POINT force field center.
@@ -620,6 +631,57 @@ type TextureSheetAnimation = {
     fps?: number;
     startFrame?: Constant | RandomBetweenTwoConstants;
 };
+/**
+ * Configuration for the trail/ribbon renderer.
+ * Controls how particle trails are drawn when using `RendererType.TRAIL`.
+ *
+ * @property length - Number of position history samples per particle (trail segments).
+ *   Higher values produce longer, smoother trails but cost more memory.
+ *   @default 20
+ * @property widthOverTrail - Lifetime curve that controls the ribbon width along its length.
+ *   At 0 the trail head (current position), at 1 the trail tail (oldest position).
+ *   @default constant 1.0
+ * @property opacityOverTrail - Lifetime curve that controls opacity along the trail length.
+ *   @default linear fade from 1 (head) to 0 (tail)
+ *
+ * @example
+ * ```typescript
+ * // Long comet-style trail tapering to nothing
+ * trail: {
+ *   length: 40,
+ *   widthOverTrail: {
+ *     type: LifeTimeCurve.BEZIER,
+ *     scale: 1,
+ *     bezierPoints: [
+ *       { x: 0, y: 1, percentage: 0 },
+ *       { x: 0.5, y: 0.4 },
+ *       { x: 1, y: 0, percentage: 1 },
+ *     ],
+ *   },
+ * }
+ * ```
+ */
+type TrailConfig = {
+    /** Number of position history samples per particle. @default 20 */
+    length?: number;
+    /** Base ribbon width in world units. @default 1.0 */
+    width?: number;
+    /** Curve controlling ribbon width from head (0) to tail (1). */
+    widthOverTrail?: LifetimeCurve;
+    /** Curve controlling opacity from head (0) to tail (1). */
+    opacityOverTrail?: LifetimeCurve;
+    /**
+     * Per-channel color multiplier curves along the trail (head=0, tail=1).
+     * Works as multipliers on the particle's current color, same as colorOverLifetime.
+     * To achieve full color transitions, use white startColor.
+     */
+    colorOverTrail?: {
+        isActive: boolean;
+        r: LifetimeCurve;
+        g: LifetimeCurve;
+        b: LifetimeCurve;
+    };
+};
 /**
  * Configuration for the particle system renderer, controlling blending, transparency, depth, and background color behavior.
  *
@@ -673,6 +735,13 @@ type Renderer = {
      * @default RendererType.POINTS
      */
     rendererType?: RendererType;
+    /**
+     * Trail/ribbon renderer configuration.
+     * Only used when `rendererType` is `RendererType.TRAIL`.
+     *
+     * @see TrailConfig
+     */
+    trail?: TrailConfig;
 };
 /**
  * Configuration for noise effects applied to particles in a particle system.
@@ -1482,6 +1551,20 @@ type GeneralData = {
     isEnabled: boolean;
     /** Tracks the state of each burst emission event */
     burstStates?: Array<BurstState>;
+    /**
+     * Circular buffer storing position history for trail renderer.
+     * Each particle has `trailLength` slots of (x, y, z) positions.
+     * Only allocated when `RendererType.TRAIL` is used.
+     */
+    positionHistory?: Float32Array;
+    /** Write index per particle into the circular position history buffer. */
+    positionHistoryIndex?: Uint16Array;
+    /** Number of valid history samples per particle (fills up from 0 to trailLength). */
+    positionHistoryCount?: Uint16Array;
+    /** Trail length (number of history samples per particle). */
+    trailLength?: number;
+    /** Cached camera world position, updated each frame via onBeforeRender for billboard trails. */
+    trailCameraPosition?: THREE.Vector3;
 };
 /** Union of all buffer attribute types Three.js uses in geometry. */
 type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
@@ -1544,6 +1627,29 @@ type ParticleSystemInstance = {
     onParticleDeath?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
     /** Called when a particle is born to trigger birth sub-emitters */
     onParticleBirth?: (particleIndex: number, positionArr: THREE.TypedArray, velocity: THREE.Vector3, now: number) => void;
+    /** Trail mesh for RendererType.TRAIL */
+    trailMesh?: THREE.Mesh;
+    /** Trail geometry position attribute */
+    trailPositionAttr?: THREE.BufferAttribute;
+    /** Trail geometry alpha attribute */
+    trailAlphaAttr?: THREE.BufferAttribute;
+    /** Trail geometry color attribute */
+    trailColorAttr?: THREE.BufferAttribute;
+    /** Trail width curve function */
+    trailWidthCurveFn?: CurveFunction;
+    /** Trail opacity curve function */
+    trailOpacityCurveFn?: CurveFunction;
+    /** Trail color-over-trail curve functions (r, g, b multipliers) */
+    trailColorOverTrailFns?: {
+        r: CurveFunction;
+        g: CurveFunction;
+        b: CurveFunction;
+    };
+    /** Trail config (length, width) */
+    trailConfig?: {
+        length: number;
+        width: number;
+    };
 };
 /**
  * Represents a particle system instance, providing methods to control and manage its lifecycle.
@@ -2036,4 +2142,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 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 };
+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 TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };