@cyberluke/three-particles 4.0.1

package/dist/index.d.ts

@@ -0,0 +1,2970 @@
+import * as THREE from 'three';
+import { FBM } from 'three-noise/build/three-noise.module.js';
+
+declare const REVISION: string;
+
+/**
+ * Standard IEC 61966-2-1 sRGB → linear transfer function.
+ * Matches `THREE.ColorManagement.SRGBToLinear` and the GLSL
+ * `ShaderChunk.colorspace_fragment` implementation, so that user-provided
+ * colors go through the exact same conversion the rest of the Three.js
+ * pipeline uses for sRGB-tagged inputs.
+ *
+ * Input: a channel value in [0, 1] interpreted as sRGB.
+ * Output: the corresponding linear value in [0, 1].
+ */
+declare const sRGBToLinear: (c: number) => number;
+/**
+ * Standard IEC 61966-2-1 linear → sRGB transfer function.
+ * Inverse of {@link sRGBToLinear}. Useful for one-shot migration of
+ * legacy color values that were authored under the old raw-byte pipeline.
+ */
+declare const linearToSRGB: (c: number) => number;
+/**
+ * Converts an sRGB {r, g, b} triplet to linear space.
+ * Used when uploading user-authored colors (e.g. `backgroundColor`) as
+ * shader uniforms that must match the linear-space texture samples and
+ * vertex colors used elsewhere in the pipeline. Missing channels default
+ * to 0 to mirror the permissive shape of the `Rgb` config type.
+ */
+declare const rgbSRGBToLinear: (c: {
+    r?: number;
+    g?: number;
+    b?: number;
+}) => {
+    r: number;
+    g: number;
+    b: number;
+};
+
+/**
+ * Defines the coordinate space in which particles are simulated.
+ *
+ * @enum {string}
+ */
+declare const enum SimulationSpace {
+    /**
+     * Particles move relative to the emitter's local coordinate system.
+     * When the emitter moves or rotates, particles move with it.
+     * Ideal for effects attached to moving objects (e.g., engine trails, character auras).
+     */
+    LOCAL = "LOCAL",
+    /**
+     * Particles move in world space and are independent of the emitter's transform.
+     * Once emitted, particles remain stationary or move according to their velocity in world coordinates.
+     * Ideal for environmental effects (e.g., smoke, explosions, ambient particles).
+     */
+    WORLD = "WORLD"
+}
+/**
+ * Defines the geometric shape from which particles are emitted.
+ *
+ * @enum {string}
+ */
+declare const enum Shape {
+    /**
+     * Emit particles from a spherical volume or shell.
+     * Configure with {@link Sphere} properties (radius, arc, radiusThickness).
+     */
+    SPHERE = "SPHERE",
+    /**
+     * Emit particles from a conical volume or shell.
+     * Configure with {@link Cone} properties (angle, radius, arc, radiusThickness).
+     * Useful for directional effects like fire, smoke plumes, or spray effects.
+     */
+    CONE = "CONE",
+    /**
+     * Emit particles from a box volume, shell, or edges.
+     * Configure with {@link Box} properties (scale, emitFrom).
+     * Useful for area-based effects like dust clouds or rain.
+     */
+    BOX = "BOX",
+    /**
+     * Emit particles from a circular area or edge.
+     * Configure with {@link Circle} properties (radius, arc, radiusThickness).
+     * Useful for ground impacts, rings, or radial effects.
+     */
+    CIRCLE = "CIRCLE",
+    /**
+     * Emit particles from a rectangular area.
+     * Configure with {@link Rectangle} properties (scale, rotation).
+     * Useful for planar effects like rain on a surface or screen effects.
+     */
+    RECTANGLE = "RECTANGLE"
+}
+/**
+ * Defines where on a shape particles are emitted from.
+ * Not all shapes support all emit modes.
+ *
+ * @enum {string}
+ */
+declare const enum EmitFrom {
+    /**
+     * Emit particles from random positions within the entire volume of the shape.
+     * Supported by: SPHERE, CONE, BOX.
+     */
+    VOLUME = "VOLUME",
+    /**
+     * Emit particles from the surface/shell of the shape.
+     * Supported by: SPHERE, CONE, BOX.
+     */
+    SHELL = "SHELL",
+    /**
+     * Emit particles from the edges of the shape.
+     * Supported by: BOX.
+     */
+    EDGE = "EDGE"
+}
+/**
+ * Defines how texture sheet animation is timed.
+ *
+ * @enum {string}
+ */
+declare const enum TimeMode {
+    /**
+     * Animation frames are based on the particle's lifetime percentage.
+     * The animation completes once over the particle's lifetime.
+     */
+    LIFETIME = "LIFETIME",
+    /**
+     * Animation frames are based on frames per second (FPS).
+     * The animation runs at a fixed speed regardless of particle lifetime.
+     */
+    FPS = "FPS"
+}
+/**
+ * Defines the type of curve function used for animating values over a particle's lifetime.
+ *
+ * @enum {string}
+ */
+declare const enum LifeTimeCurve {
+    /**
+     * Use custom Bezier curves with control points.
+     * Provides maximum control over the animation curve shape.
+     * See {@link BezierCurve} for configuration.
+     */
+    BEZIER = "BEZIER",
+    /**
+     * Use predefined easing functions (e.g., easeInQuad, easeOutCubic).
+     * Convenient for common animation patterns.
+     * See {@link EasingCurve} and {@link CurveFunctionId} for available functions.
+     */
+    EASING = "EASING"
+}
+/**
+ * Defines when a sub-emitter is triggered relative to a particle's lifecycle.
+ *
+ * @enum {string}
+ */
+declare const enum SubEmitterTrigger {
+    /**
+     * Trigger the sub-emitter when a particle is born (activated).
+     * Useful for trail effects that start immediately with each particle.
+     */
+    BIRTH = "BIRTH",
+    /**
+     * Trigger the sub-emitter when a particle dies (reaches end of lifetime).
+     * Useful for cascading effects like explosions spawning smoke.
+     */
+    DEATH = "DEATH"
+}
+/**
+ * Defines the type of force field that affects particles.
+ *
+ * @enum {string}
+ */
+declare const enum ForceFieldType {
+    /**
+     * Attract or repel particles toward/from a point in space.
+     * Positive strength attracts, negative strength repels.
+     * Configure with position, strength, range, and falloff.
+     */
+    POINT = "POINT",
+    /**
+     * Apply a constant directional force to all particles (like wind).
+     * Configure with direction and strength.
+     */
+    DIRECTIONAL = "DIRECTIONAL"
+}
+/**
+ * Defines the rendering technique used for particles.
+ *
+ * @enum {string}
+ */
+declare const enum RendererType {
+    /**
+     * Render particles as point sprites using `THREE.Points`.
+     * This is the default renderer, efficient for small to medium particle counts.
+     * Note: point size is limited by `gl_PointSize` hardware caps (typically 64–256 px).
+     */
+    POINTS = "POINTS",
+    /**
+     * Render particles as camera-facing quads using `THREE.InstancedBufferGeometry`.
+     * Removes the `gl_PointSize` hardware limit, supports stretched billboards,
+     * 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",
+    /**
+     * 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",
+    /**
+     * Render each particle as a 3D mesh using GPU instancing (`InstancedBufferGeometry`).
+     * Instead of flat billboard sprites, particles are rendered as real 3D geometry
+     * (e.g., cubes, spheres, tori, or any custom `THREE.BufferGeometry`).
+     *
+     * Key differences from billboard renderers:
+     * - **3D rotation**: Particles rotate in all three axes (quaternion-based).
+     * - **Normals**: Mesh geometry retains normals, enabling basic lighting.
+     * - **Arbitrary geometry**: Any `THREE.BufferGeometry` can be used per particle.
+     *
+     * All existing modifiers (sizeOverLifetime, colorOverLifetime, noise, force fields,
+     * sub-emitters) work with mesh particles.
+     *
+     * Configure mesh-specific properties via {@link MeshConfig} on the renderer.
+     */
+    MESH = "MESH"
+}
+/**
+ * Defines how force diminishes with distance from a POINT force field center.
+ * Only applicable to {@link ForceFieldType.POINT} force fields.
+ *
+ * @enum {string}
+ */
+declare const enum ForceFieldFalloff {
+    /**
+     * No falloff — force is constant within range.
+     */
+    NONE = "NONE",
+    /**
+     * Force decreases linearly with distance: `1 - d/range`.
+     */
+    LINEAR = "LINEAR",
+    /**
+     * Force decreases with the square of distance: `1 - (d/range)²`.
+     * More physically realistic than linear fallback.
+     */
+    QUADRATIC = "QUADRATIC"
+}
+/**
+ * Defines the behavior when a particle crosses a collision plane.
+ *
+ * @enum {string}
+ */
+declare const enum CollisionPlaneMode {
+    /**
+     * Kill the particle immediately when it crosses the plane.
+     * The particle is deactivated and returned to the free list.
+     * Ideal for boundaries like water surfaces where bubbles pop.
+     */
+    KILL = "KILL",
+    /**
+     * Clamp the particle's position to the plane surface.
+     * The velocity component along the plane normal is zeroed.
+     * The particle stays alive and slides along the plane.
+     */
+    CLAMP = "CLAMP",
+    /**
+     * Bounce the particle off the plane.
+     * The velocity is reflected across the plane normal and dampened.
+     * Use `dampen` to control energy loss on bounce.
+     */
+    BOUNCE = "BOUNCE"
+}
+/**
+ * Defines the simulation backend used for particle updates.
+ *
+ * @enum {string}
+ */
+declare const enum SimulationBackend {
+    /**
+     * Use GPU compute when the WebGPU path has been registered via
+     * `enableWebGPU()` / `registerTSLMaterialFactory()`, otherwise CPU.
+     *
+     * Note: the library does not inspect the renderer itself — pass your
+     * renderer to `enableWebGPU(renderer)` so registration (and therefore the
+     * GPU backend) is automatically skipped when the renderer cannot dispatch
+     * compute shaders.
+     */
+    AUTO = "AUTO",
+    /**
+     * Force CPU-based simulation (JavaScript update loop).
+     * Always available regardless of renderer type.
+     */
+    CPU = "CPU",
+    /**
+     * Use GPU compute shader simulation. Behaves like {@link SimulationBackend.AUTO}:
+     * the GPU backend requires the WebGPU path to be registered via
+     * `enableWebGPU()`; without it the system runs on the CPU.
+     */
+    GPU = "GPU"
+}
+
+/**
+ * A fixed numerical value.
+ * Used for properties that require a constant value.
+ *
+ * @example
+ * const delay: Constant = 2; // Fixed delay of 2 seconds.
+ */
+type Constant = number;
+/**
+ * An object that defines a range for random number generation.
+ * Contains `min` and `max` properties.
+ *
+ * @property min - The minimum value for the random range.
+ * @property max - The maximum value for the random range.
+ *
+ * @example
+ * const randomDelay: RandomBetweenTwoConstants = { min: 0.5, max: 2 }; // Random delay between 0.5 and 2 seconds.
+ */
+type RandomBetweenTwoConstants = {
+    min?: number;
+    max?: number;
+};
+/**
+ * Base type for curves, containing common properties.
+ * @property scale - A scaling factor for the curve.
+ */
+type CurveBase = {
+    scale?: number;
+};
+/**
+ * A function that defines how the value changes over time.
+ * @param time - A normalized value between 0 and 1 representing the progress of the curve.
+ * @returns The corresponding value based on the curve function.
+ */
+type CurveFunction = (time: number) => number;
+/**
+ * A B??zier curve point representing a control point.
+ * @property x - The time (normalized between 0 and 1).
+ * @property y - The value at that point.
+ * @property percentage - (Optional) Normalized position within the curve (for additional flexibility).
+ */
+type BezierPoint = {
+    x: number;
+    y: number;
+    percentage?: number;
+};
+/**
+ * A B??zier curve representation for controlling particle properties.
+ * @property type - Specifies that this curve is of type `bezier`.
+ * @property bezierPoints - An array of control points defining the B??zier curve.
+ * @example
+ * {
+ *   type: LifeTimeCurve.BEZIER,
+ *   bezierPoints: [
+ *     { x: 0, y: 0.275, percentage: 0 },
+ *     { x: 0.1666, y: 0.4416 },
+ *     { x: 0.5066, y: 0.495, percentage: 0.5066 },
+ *     { x: 1, y: 1, percentage: 1 }
+ *   ]
+ * }
+ */
+type BezierCurve = CurveBase & {
+    type: LifeTimeCurve.BEZIER;
+    bezierPoints: Array<BezierPoint>;
+};
+/**
+ * An easing curve representation using a custom function.
+ * @property type - Specifies that this curve is of type `easing`.
+ * @property curveFunction - A function defining how the value changes over time.
+ * @example
+ * {
+ *   type: LifeTimeCurve.EASING,
+ *   curveFunction: (time) => Math.sin(time * Math.PI) // Simple easing function
+ * }
+ */
+type EasingCurve = CurveBase & {
+    type: LifeTimeCurve.EASING;
+    curveFunction: CurveFunction;
+};
+/**
+ * A flexible curve representation that supports B??zier curves and easing functions.
+ */
+type LifetimeCurve = BezierCurve | EasingCurve;
+/**
+ * Represents a point in 3D space with optional x, y, and z coordinates.
+ * Each coordinate is a number and is optional, allowing for partial definitions.
+ *
+ * @example
+ * // A point with all coordinates defined
+ * const point: Point3D = { x: 10, y: 20, z: 30 };
+ *
+ * @example
+ * // A point with only one coordinate defined
+ * const point: Point3D = { x: 10 };
+ *
+ * @default
+ * // Default values are undefined for all coordinates.
+ * const point: Point3D = {};
+ */
+type Point3D = {
+    x?: number;
+    y?: number;
+    z?: number;
+};
+/**
+ * Represents a transform in 3D space, including position, rotation, and scale.
+ * Each property is optional and represented as a THREE.Vector3 instance.
+ *
+ * - `position`: Defines the translation of an object in 3D space.
+ * - `rotation`: Defines the rotation of an object in radians for each axis (x, y, z).
+ * - `scale`: Defines the scale of an object along each axis.
+ *
+ * @example
+ * // A transform with all properties defined
+ * const transform: Transform = {
+ *   position: new THREE.Vector3(10, 20, 30),
+ *   rotation: new THREE.Vector3(Math.PI / 2, 0, 0),
+ *   scale: new THREE.Vector3(1, 1, 1),
+ * };
+ *
+ * @example
+ * // A transform with only position defined
+ * const transform: Transform = {
+ *   position: new THREE.Vector3(5, 5, 5),
+ * };
+ *
+ * @default
+ * // Default values are undefined for all properties.
+ * const transform: Transform = {};
+ */
+type Transform = {
+    position?: THREE.Vector3;
+    rotation?: THREE.Vector3;
+    scale?: THREE.Vector3;
+};
+/**
+ * Represents an RGB color with normalized values (0.0 to 1.0).
+ *
+ * @example
+ * ```typescript
+ * // Pure red
+ * const red: Rgb = { r: 1.0, g: 0.0, b: 0.0 };
+ *
+ * // Pure white
+ * const white: Rgb = { r: 1.0, g: 1.0, b: 1.0 };
+ *
+ * // Orange
+ * const orange: Rgb = { r: 1.0, g: 0.5, b: 0.0 };
+ * ```
+ */
+type Rgb = {
+    /** Red channel (0.0 to 1.0) */
+    r?: number;
+    /** Green channel (0.0 to 1.0) */
+    g?: number;
+    /** Blue channel (0.0 to 1.0) */
+    b?: number;
+};
+/**
+ * Defines a color range for random particle colors.
+ * Each particle will receive a random color between min and max on emission.
+ *
+ * @example
+ * ```typescript
+ * // Random colors between red and yellow
+ * const fireColors: MinMaxColor = {
+ *   min: { r: 1.0, g: 0.0, b: 0.0 }, // Red
+ *   max: { r: 1.0, g: 1.0, b: 0.0 }  // Yellow
+ * };
+ *
+ * // Fixed white color (no randomness)
+ * const white: MinMaxColor = {
+ *   min: { r: 1.0, g: 1.0, b: 1.0 },
+ *   max: { r: 1.0, g: 1.0, b: 1.0 }
+ * };
+ * ```
+ */
+type MinMaxColor = {
+    /** Minimum color values (lower bound for random selection) */
+    min?: Rgb;
+    /** Maximum color values (upper bound for random selection) */
+    max?: Rgb;
+};
+/**
+ * Defines a burst emission event that emits a specific number of particles at a given time.
+ * Bursts are useful for explosions, impacts, fireworks, and other instantaneous particle effects.
+ *
+ * @property time - The time (in seconds) after the particle system starts when this burst should occur.
+ * @property count - The number of particles to emit. Can be a constant or a random range.
+ * @property cycles - The number of times this burst should repeat. Defaults to 1 (single burst).
+ * @property interval - The time interval (in seconds) between burst cycles. Only used when cycles > 1.
+ * @property probability - The probability (0.0 to 1.0) that this burst will occur. Defaults to 1.0.
+ *
+ * @example
+ * // Simple burst at start
+ * { time: 0, count: 50 }
+ *
+ * // Random count burst at 1 second
+ * { time: 1, count: { min: 20, max: 30 } }
+ *
+ * // Repeating burst with interval
+ * { time: 0.5, count: 10, cycles: 3, interval: 0.2 }
+ * // Emits at 0.5s, 0.7s, 0.9s
+ *
+ * // Probabilistic burst (50% chance)
+ * { time: 2, count: 100, probability: 0.5 }
+ */
+type Burst = {
+    /** Time in seconds when the burst should occur */
+    time: number;
+    /** Number of particles to emit (constant or random range) */
+    count: Constant | RandomBetweenTwoConstants;
+    /** Number of times to repeat this burst. Defaults to 1. */
+    cycles?: number;
+    /** Time interval in seconds between burst cycles. Defaults to 0. */
+    interval?: number;
+    /** Probability (0-1) that this burst will occur. Defaults to 1. */
+    probability?: number;
+};
+/**
+ * Defines the emission behavior of the particles.
+ * Supports rates defined over time or distance using constant values, random ranges, or curves (B??zier or easing).
+ * Also supports burst emissions for instantaneous particle effects.
+ *
+ * @default
+ * rateOverTime: 10.0
+ * rateOverDistance: 0.0
+ * bursts: []
+ *
+ * @example
+ * // Rate over time as a constant value
+ * rateOverTime: 10;
+ *
+ * // Rate over time as a random range
+ * rateOverTime: { min: 5, max: 15 };
+ *
+ * // Rate over time using a B??zier curve
+ * rateOverTime: {
+ *   type: 'bezier',
+ *   bezierPoints: [
+ *     { x: 0, y: 0, percentage: 0 },
+ *     { x: 0.5, y: 50 },
+ *     { x: 1, y: 100, percentage: 1 }
+ *   ],
+ *   scale: 1
+ * };
+ *
+ * // Rate over distance as a constant value
+ * rateOverDistance: 2;
+ *
+ * // Rate over distance as a random range
+ * rateOverDistance: { min: 1, max: 3 };
+ *
+ * // Rate over distance using an easing curve
+ * rateOverDistance: {
+ *   type: 'easing',
+ *   curveFunction: (distance) => Math.sin(distance),
+ *   scale: 0.5
+ * };
+ *
+ * // Burst emissions for explosions
+ * bursts: [
+ *   { time: 0, count: 50 },
+ *   { time: 1, count: { min: 20, max: 30 }, probability: 0.8 },
+ *   { time: 0.5, count: 10, cycles: 3, interval: 0.2 }
+ * ];
+ */
+type Emission = {
+    rateOverTime?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    rateOverDistance?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /** Array of burst configurations for instantaneous particle emissions */
+    bursts?: Array<Burst>;
+};
+/**
+ * Configuration for a sphere shape used in particle systems.
+ *
+ * @property radius - The radius of the sphere.
+ * @property radiusThickness - The thickness of the sphere's shell (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the sphere (in radians).
+ *
+ * @example
+ * const sphere: Sphere = {
+ *   radius: 5,
+ *   radiusThickness: 0.8,
+ *   arc: Math.PI,
+ * };
+ */
+type Sphere = {
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a cone shape used in particle systems.
+ *
+ * @property angle - The angle of the cone (in radians).
+ * @property radius - The radius of the cone's base.
+ * @property radiusThickness - The thickness of the cone's base (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the cone's base (in radians).
+ *
+ * @example
+ * const cone: Cone = {
+ *   angle: Math.PI / 4,
+ *   radius: 10,
+ *   radiusThickness: 0.5,
+ *   arc: Math.PI * 2,
+ * };
+ */
+type Cone = {
+    angle?: number;
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a circle shape used in particle systems.
+ *
+ * @property radius - The radius of the circle.
+ * @property radiusThickness - The thickness of the circle's shell (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the circle (in radians).
+ *
+ * @example
+ * const circle: Circle = {
+ *   radius: 10,
+ *   radiusThickness: 0.5,
+ *   arc: Math.PI,
+ * };
+ */
+type Circle = {
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a rectangle shape used in particle systems.
+ *
+ * @property rotation - The rotation of the rectangle as a 3D point (in radians for each axis).
+ * @property scale - The scale of the rectangle as a 3D point.
+ *
+ * @example
+ * const rectangle: Rectangle = {
+ *   rotation: { x: Math.PI / 4, y: 0, z: 0 },
+ *   scale: { x: 10, y: 5, z: 1 },
+ * };
+ */
+type Rectangle = {
+    rotation?: Point3D;
+    scale?: Point3D;
+};
+/**
+ * Configuration for a box shape used in particle systems.
+ *
+ * @property scale - The scale of the box as a 3D point.
+ * @property emitFrom - Specifies where particles are emitted from within the box.
+ *
+ * @example
+ * const box: Box = {
+ *   scale: { x: 10, y: 10, z: 10 },
+ *   emitFrom: EmitFrom.EDGE,
+ * };
+ */
+type Box = {
+    scale?: Point3D;
+    emitFrom?: EmitFrom;
+};
+/**
+ * Configuration for defining a 3D shape used in particle systems.
+ * Specifies the shape type and its parameters, including spheres, cones, circles, rectangles, and boxes.
+ *
+ * @property shape - The type of the shape to be used.
+ * @property sphere - Configuration for a sphere shape.
+ * @property cone - Configuration for a cone shape.
+ * @property circle - Configuration for a circle shape.
+ * @property rectangle - Configuration for a rectangle shape.
+ * @property box - Configuration for a box shape.
+ *
+ * @example
+ * const shapeConfig: ShapeConfig = {
+ *   shape: Shape.SPHERE,
+ *   sphere: {
+ *     radius: 5,
+ *     radiusThickness: 0.8,
+ *     arc: Math.PI,
+ *   },
+ * };
+ */
+type ShapeConfig = {
+    shape?: Shape;
+    sphere?: Sphere;
+    cone?: Cone;
+    circle?: Circle;
+    rectangle?: Rectangle;
+    box?: Box;
+};
+/**
+ * Defines the texture sheet animation settings for particles.
+ * Allows configuring the animation frames, timing mode, frames per second, and the starting frame.
+ *
+ * @default
+ * tiles: new THREE.Vector2(1.0, 1.0)
+ * timeMode: TimeMode.LIFETIME
+ * fps: 30.0
+ * startFrame: 0
+ *
+ * @example
+ * // Basic configuration with default values
+ * textureSheetAnimation: {
+ *   tiles: new THREE.Vector2(1.0, 1.0),
+ *   timeMode: TimeMode.LIFETIME,
+ *   fps: 30.0,
+ *   startFrame: 0
+ * };
+ *
+ * // Custom configuration
+ * textureSheetAnimation: {
+ *   tiles: new THREE.Vector2(4, 4), // 4x4 grid of animation tiles
+ *   timeMode: TimeMode.SPEED,
+ *   fps: 60.0,
+ *   startFrame: { min: 0, max: 15 } // Random start frame between 0 and 15
+ * };
+ */
+type TextureSheetAnimation = {
+    tiles?: THREE.Vector2;
+    timeMode?: TimeMode;
+    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;
+    };
+    /**
+     * 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.
+ * Controls which 3D geometry is used when `rendererType` is `RendererType.MESH`.
+ *
+ * @property geometry - A `THREE.BufferGeometry` to render for each particle.
+ *   Built-in Three.js primitives like `BoxGeometry`, `SphereGeometry`, `TorusGeometry`
+ *   all work. The geometry's own normals and UVs are preserved.
+ *
+ * @example
+ * ```typescript
+ * // Cube mesh particles
+ * mesh: {
+ *   geometry: new THREE.BoxGeometry(1, 1, 1),
+ * }
+ *
+ * // Icosahedron mesh particles
+ * mesh: {
+ *   geometry: new THREE.IcosahedronGeometry(0.5, 0),
+ * }
+ * ```
+ */
+type MeshConfig = {
+    /** The geometry to render for each particle. */
+    geometry: THREE.BufferGeometry;
+};
+/**
+ * Configuration for the particle system renderer, controlling blending, transparency, depth, and background color behavior.
+ *
+ * @property blending - Defines the blending mode for the particle system (e.g., additive blending).
+ * @property discardBackgroundColor - Whether to discard particles that match the background color.
+ * @property backgroundColorTolerance - The tolerance for matching the background color when `discardBackgroundColor` is true.
+ * @property backgroundColor - The background color as an RGB value, used when `discardBackgroundColor` is enabled.
+ * @property transparent - Whether the particle system uses transparency.
+ * @property depthTest - Whether to enable depth testing for particles (determines if particles are rendered behind or in front of other objects).
+ * @property depthWrite - Whether to write depth information for the particles (affects sorting and rendering order).
+ *
+ * @example
+ * // A renderer configuration with additive blending and transparent particles
+ * const renderer: Renderer = {
+ *   blending: THREE.AdditiveBlending,
+ *   discardBackgroundColor: true,
+ *   backgroundColorTolerance: 0.1,
+ *   backgroundColor: { r: 0, g: 0, b: 0 },
+ *   transparent: true,
+ *   depthTest: true,
+ *   depthWrite: false,
+ * };
+ *
+ * @default
+ * // Default values for the renderer configuration
+ * const renderer: Renderer = {
+ *   blending: THREE.NormalBlending,
+ *   discardBackgroundColor: false,
+ *   backgroundColorTolerance: 1.0,
+ *   backgroundColor: { r: 0, g: 0, b: 0 },
+ *   transparent: false,
+ *   depthTest: true,
+ *   depthWrite: true,
+ * };
+ */
+type Renderer = {
+    blending: THREE.Blending;
+    discardBackgroundColor: boolean;
+    backgroundColorTolerance: number;
+    backgroundColor: Rgb;
+    transparent: boolean;
+    depthTest: boolean;
+    depthWrite: boolean;
+    /**
+     * Selects the rendering technique for particles.
+     *
+     * - `RendererType.POINTS` (default) ??? classic point-sprite renderer using `THREE.Points`.
+     * - `RendererType.INSTANCED` ??? camera-facing quads via `InstancedBufferGeometry`,
+     *   removing the `gl_PointSize` hardware limit and enabling stretched billboards.
+     *
+     * @default RendererType.POINTS
+     */
+    rendererType?: RendererType;
+    /**
+     * Trail/ribbon renderer configuration.
+     * Only used when `rendererType` is `RendererType.TRAIL`.
+     *
+     * @see TrailConfig
+     */
+    trail?: TrailConfig;
+    /**
+     * Mesh particle renderer configuration.
+     * Only used when `rendererType` is `RendererType.MESH`.
+     *
+     * @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.
+ * Noise can affect particle position, rotation, and size dynamically.
+ *
+ * @property isActive - Whether noise is enabled for the particle system.
+ * @property strength - The overall strength of the noise effect.
+ * @property positionAmount - The amount of noise applied to particle positions.
+ * @property rotationAmount - The amount of noise applied to particle rotations.
+ * @property sizeAmount - The amount of noise applied to particle sizes.
+ * @property sampler - An optional noise sampler (e.g., FBM for fractal Brownian motion) to generate noise values.
+ * @property offsets - An optional array of offsets to randomize noise generation per particle.
+ *
+ * @example
+ * // A noise configuration with position and rotation noise
+ * const noise: Noise = {
+ *   isActive: true,
+ *   strength: 0.5,
+ *   positionAmount: 1.0,
+ *   rotationAmount: 0.3,
+ *   sizeAmount: 0.0,
+ *   sampler: new FBM(),
+ *   offsets: [0.1, 0.2, 0.3],
+ * };
+ *
+ * @default
+ * // Default values for noise configuration
+ * const noise: Noise = {
+ *   isActive: false,
+ *   strength: 1.0,
+ *   positionAmount: 0.0,
+ *   rotationAmount: 0.0,
+ *   sizeAmount: 0.0,
+ *   sampler: undefined,
+ *   offsets: undefined,
+ * };
+ */
+type Noise = {
+    isActive: boolean;
+    strength: number;
+    noisePower: number;
+    frequency: number;
+    positionAmount: number;
+    rotationAmount: number;
+    sizeAmount: number;
+    /** Pre-computed FBM normalisation divisor: `2 - 2^(-octaves)`. */
+    fbmMax: number;
+    sampler?: FBM;
+    offsets?: Array<number>;
+};
+type NoiseConfig = {
+    isActive: boolean;
+    useRandomOffset: boolean;
+    strength: number;
+    frequency: number;
+    octaves: number;
+    positionAmount: number;
+    rotationAmount: number;
+    sizeAmount: number;
+};
+/**
+ * Defines the velocity of particles over their lifetime, allowing for linear and orbital velocity (in degrees) adjustments.
+ * Supports constant values, random ranges, or curves (B??zier or easing) for each axis.
+ *
+ * @default
+ * isActive: false
+ * linear: { x: 0.0, y: 0.0, z: 0.0 }
+ * orbital: { x: 0.0, y: 0.0, z: 0.0 }
+ *
+ * @example
+ * // Linear velocity with a constant value
+ * linear: { x: 1, y: 0, z: -0.5 };
+ *
+ * // Linear velocity with random ranges
+ * linear: {
+ *   x: { min: -1, max: 1 },
+ *   y: { min: 0, max: 2 }
+ * };
+ *
+ * // Linear velocity using a B??zier curve
+ * linear: {
+ *   z: {
+ *     type: 'bezier',
+ *     bezierPoints: [
+ *       { x: 0, y: 0, percentage: 0 },
+ *       { x: 0.5, y: 2 },
+ *       { x: 1, y: 10, percentage: 1 }
+ *     ],
+ *     scale: 2
+ *   }
+ * };
+ *
+ * // Orbital velocity with a constant value
+ * orbital: { x: 3, y: 5, z: 0 };
+ *
+ * // Orbital velocity using an easing curve
+ * orbital: {
+ *   x: {
+ *     type: 'easing',
+ *     curveFunction: (time) => Math.sin(time * Math.PI),
+ *     scale: 1.5
+ *   }
+ * };
+ */
+type VelocityOverLifetime = {
+    isActive: boolean;
+    linear: {
+        x?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        y?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        z?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    };
+    orbital: {
+        x?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        y?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        z?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    };
+};
+/**
+ * Configuration for a sub-emitter that spawns child particle systems
+ * based on parent particle lifecycle events.
+ *
+ * @example
+ * ```typescript
+ * const subEmitter: SubEmitterConfig = {
+ *   trigger: SubEmitterTrigger.DEATH,
+ *   config: { startLifeTime: 0.5, startSpeed: 2, emission: { rateOverTime: 20 } },
+ *   inheritVelocity: 0.5,
+ *   maxInstances: 16,
+ * };
+ * ```
+ */
+type SubEmitterConfig = {
+    /** The particle system configuration used when spawning the sub-emitter. */
+    config: ParticleSystemConfig;
+    /**
+     * When to trigger the sub-emitter.
+     * @default SubEmitterTrigger.DEATH
+     */
+    trigger?: SubEmitterTrigger;
+    /**
+     * Multiplier (0???1) for inheriting the parent particle's velocity.
+     * 0 = no inheritance, 1 = full velocity inheritance.
+     * @default 0
+     */
+    inheritVelocity?: number;
+    /**
+     * Maximum number of concurrent sub-emitter instances for this configuration.
+     * Older completed instances are cleaned up to make room for new ones.
+     * @default 32
+     */
+    maxInstances?: number;
+};
+/**
+ * Configuration for a force field that affects particle velocities.
+ * Force fields can attract, repel, or push particles in a direction.
+ *
+ * @example
+ * ```typescript
+ * // Point attractor at origin
+ * const attractor: ForceFieldConfig = {
+ *   type: ForceFieldType.POINT,
+ *   position: new THREE.Vector3(0, 0, 0),
+ *   strength: 5.0,
+ *   range: 10,
+ *   falloff: ForceFieldFalloff.QUADRATIC,
+ * };
+ *
+ * // Repulsion shield
+ * const shield: ForceFieldConfig = {
+ *   type: ForceFieldType.POINT,
+ *   position: new THREE.Vector3(0, 0, 0),
+ *   strength: -3.0,
+ *   range: 5,
+ *   falloff: ForceFieldFalloff.LINEAR,
+ * };
+ *
+ * // Wind effect
+ * const wind: ForceFieldConfig = {
+ *   type: ForceFieldType.DIRECTIONAL,
+ *   direction: new THREE.Vector3(1, 0, 0),
+ *   strength: 2.0,
+ * };
+ * ```
+ */
+type ForceFieldConfig = {
+    /** Whether this force field is active. @default true */
+    isActive?: boolean;
+    /** Type of the force field. @default ForceFieldType.POINT */
+    type?: ForceFieldType;
+    /** Position in 3D space for POINT type force fields. @default (0,0,0) */
+    position?: THREE.Vector3;
+    /** Direction vector for DIRECTIONAL type force fields. @default (0,1,0) */
+    direction?: THREE.Vector3;
+    /**
+     * Force strength. Positive = attract (POINT) or push along direction (DIRECTIONAL).
+     * Negative = repel (POINT) or push against direction (DIRECTIONAL).
+     * Supports constant, random range, or lifetime curve (evaluated against system lifetime).
+     * @default 1
+     */
+    strength?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Maximum effective range for POINT type. Particles beyond this distance are unaffected.
+     * @default Infinity
+     */
+    range?: number;
+    /**
+     * How force diminishes with distance for POINT type.
+     * @default ForceFieldFalloff.LINEAR
+     */
+    falloff?: ForceFieldFalloff;
+};
+/**
+ * Internal normalized force field configuration where all properties are required.
+ * Created during particle system initialization from user-provided {@link ForceFieldConfig}.
+ */
+type NormalizedForceFieldConfig = {
+    isActive: boolean;
+    type: ForceFieldType;
+    position: THREE.Vector3;
+    direction: THREE.Vector3;
+    strength: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    range: number;
+    falloff: ForceFieldFalloff;
+};
+/**
+ * Configuration for a collision plane that constrains particle positions.
+ * Collision planes define infinite planes in 3D space. When a particle crosses
+ * from the front side (positive normal direction) to the back side, the
+ * configured response mode is triggered.
+ *
+ * @example
+ * ```typescript
+ * // Water surface ??? kill bubbles when they reach y=5
+ * const waterSurface: CollisionPlaneConfig = {
+ *   position: { x: 0, y: 5, z: 0 },
+ *   normal: { x: 0, y: -1, z: 0 },
+ *   mode: CollisionPlaneMode.KILL,
+ * };
+ *
+ * // Bouncy floor
+ * const floor: CollisionPlaneConfig = {
+ *   position: { x: 0, y: 0, z: 0 },
+ *   normal: { x: 0, y: 1, z: 0 },
+ *   mode: CollisionPlaneMode.BOUNCE,
+ *   dampen: 0.6,
+ * };
+ *
+ * // Invisible wall clamp
+ * const wall: CollisionPlaneConfig = {
+ *   position: { x: 5, y: 0, z: 0 },
+ *   normal: { x: -1, y: 0, z: 0 },
+ *   mode: CollisionPlaneMode.CLAMP,
+ * };
+ * ```
+ */
+type CollisionPlaneConfig = {
+    /** Whether this collision plane is active. @default true */
+    isActive?: boolean;
+    /** A point on the plane surface. @default (0,0,0) */
+    position?: Point3D;
+    /**
+     * The plane normal vector (will be normalized internally).
+     * Defines the "front" side of the plane. Particles crossing from front
+     * to back trigger the collision response.
+     * @default (0,1,0)
+     */
+    normal?: Point3D;
+    /** The collision response mode. @default CollisionPlaneMode.KILL */
+    mode?: CollisionPlaneMode;
+    /**
+     * Energy retention factor for BOUNCE mode (0???1).
+     * 0 = no bounce (all energy absorbed), 1 = perfect bounce (no energy loss).
+     * @default 0.5
+     */
+    dampen?: number;
+    /**
+     * Fraction of the particle's start lifetime to subtract on collision (0???1).
+     * Applied on each collision for BOUNCE mode; ignored for KILL and CLAMP.
+     * @default 0
+     */
+    lifetimeLoss?: number;
+};
+/**
+ * Internal normalized collision plane configuration where all properties are required.
+ * Created during particle system initialization from user-provided {@link CollisionPlaneConfig}.
+ */
+type NormalizedCollisionPlaneConfig = {
+    isActive: boolean;
+    position: THREE.Vector3;
+    normal: THREE.Vector3;
+    mode: CollisionPlaneMode;
+    dampen: number;
+    lifetimeLoss: number;
+};
+/**
+ * Configuration object for the particle system.
+ * Defines all aspects of the particle system, including its appearance, behavior, and runtime events.
+ */
+type ParticleSystemConfig = {
+    /**
+     * Defines the position, rotation, and scale of the particle system.
+     *
+     * @see Transform
+     * @default
+     * transform: {
+     *   position: new THREE.Vector3(),
+     *   rotation: new THREE.Vector3(),
+     *   scale: new THREE.Vector3(1, 1, 1),
+     * }
+     */
+    transform?: Transform;
+    /**
+     * Duration of the particle system in seconds.
+     * Must be a positive value.
+     * @default 5.0
+     * @example
+     * const duration: number = 5; // System runs for 5 seconds.
+     */
+    duration?: number;
+    /**
+     * Indicates whether the system should loop after finishing.
+     * @default true
+     * @example
+     * looping: true; // System loops continuously.
+     */
+    looping?: boolean;
+    /**
+     * Delay before the particle system starts emitting particles.
+     * Supports a fixed value (`Constant`) or a random range (`RandomBetweenTwoConstants`).
+     * @default 0.0
+     * @example
+     * startDelay: 2; // Fixed 2-second delay.
+     * startDelay: { min: 0.5, max: 2 }; // Random delay between 0.5 and 2 seconds.
+     */
+    startDelay?: Constant | RandomBetweenTwoConstants;
+    /**
+     * Initial lifetime of the particles.
+     * Supports constant value, random range, or curves (B??zier or easing).
+     * @default 5.0
+     * @example
+     * // Constant 3 seconds.
+     * startLifetime: 3;
+     *
+     * // Random range between 1 and 4 seconds.
+     * startLifetime: { min: 1, max: 4 };
+     *
+     * // B??zier curve example with scaling.
+     * startLifetime: {
+     *   type: LifeTimeCurve.BEZIER,
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startLifetime: {
+     *   type: LifeTimeCurve.EASING,
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 0.5
+     * };
+     */
+    startLifetime?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial speed of the particles.
+     * Supports constant values, random ranges, or curves (B??zier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startSpeed: 3;
+     *
+     * // Random range
+     * startSpeed: { min: 1, max: 4 };
+     *
+     * // B??zier curve example with scaling.
+     * startSpeed: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startSpeed: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startSpeed?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial size of the particles.
+     * Supports constant values, random ranges, or curves (B??zier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startSize: 3;
+     *
+     * // Random range
+     * startSize: { min: 1, max: 4 };
+     *
+     * // B??zier curve example with scaling.
+     * startSize: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startSize: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startSize?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial opacity of the particles.
+     * Supports constant values, random ranges, or curves (B??zier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startOpacity: 3;
+     *
+     * // Random range
+     * startOpacity: { min: 1, max: 4 };
+     *
+     * // B??zier curve example with scaling.
+     * startOpacity: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startOpacity: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startOpacity?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial rotation of the particles in degrees.
+     * Supports constant values, random ranges, or curves (B??zier or easing).
+     * @default 0.0
+     * @example
+     * // Constant value
+     * startRotation: 3;
+     *
+     * // Random range
+     * startRotation: { min: 1, max: 4 };
+     *
+     * // B??zier curve example with scaling.
+     * startRotation: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startRotation: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startRotation?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Initial color of the particles.
+     * Supports a min-max range for color interpolation.
+     *
+     * @default
+     * startColor: {
+     *   min: { r: 1.0, g: 1.0, b: 1.0 },
+     *   max: { r: 1.0, g: 1.0, b: 1.0 },
+     * }
+     */
+    startColor?: MinMaxColor;
+    /**
+     * Defines the gravity strength applied to particles.
+     * This value affects the downward acceleration of particles over time.
+     *
+     * @default 0.0
+     *
+     * @example
+     * // No gravity
+     * gravity: 0;
+     *
+     * // Moderate gravity
+     * gravity: 9.8; // Similar to Earth's gravity
+     *
+     * // Strong gravity
+     * gravity: 20.0;
+     */
+    gravity?: Constant;
+    /**
+     * Defines the simulation space in which particles are simulated.
+     * Determines whether the particles move relative to the local object space or the world space.
+     *
+     * @default SimulationSpace.LOCAL
+     *
+     * @example
+     * // Simulate particles in local space (default)
+     * simulationSpace: SimulationSpace.LOCAL;
+     *
+     * // Simulate particles in world space
+     * simulationSpace: SimulationSpace.WORLD;
+     */
+    simulationSpace?: SimulationSpace;
+    /**
+     * Selects the simulation backend for particle updates.
+     *
+     * - `AUTO` (default): Uses GPU compute when a WebGPU-capable renderer is
+     *   detected, otherwise falls back to CPU.
+     * - `CPU`: Always uses the JavaScript update loop (works with any renderer).
+     * - `GPU`: Requests GPU compute simulation. Falls back to CPU if the renderer
+     *   does not support compute shaders.
+     *
+     * @default SimulationBackend.AUTO
+     */
+    simulationBackend?: SimulationBackend;
+    /**
+     * Defines the maximum number of particles allowed in the system.
+     * This value limits the total number of active particles at any given time.
+     *
+     * @default 100.0
+     *
+     * @example
+     * // Default value
+     * maxParticles: 100.0;
+     *
+     * // Increase the maximum number of particles
+     * maxParticles: 500.0;
+     *
+     * // Limit to a small number of particles
+     * maxParticles: 10.0;
+     */
+    maxParticles?: Constant;
+    /**
+     * Defines the particle emission settings.
+     * Configures the emission rate over time and distance.
+     *
+     * @see Emission
+     * @default
+     * emission: {
+     *   rateOverTime: 10.0,
+     *   rateOverDistance: 0.0,
+     * }
+     */
+    emission?: Emission;
+    /**
+     * Configuration for the emitter shape.
+     * Determines the shape and parameters for particle emission.
+     *
+     * @see ShapeConfig
+     */
+    shape?: ShapeConfig;
+    /**
+     * Defines the texture used for rendering particles.
+     * This texture is applied to all particles in the system, and can be used to control their appearance.
+     *
+     * @default undefined
+     *
+     * @example
+     * // Using a predefined texture
+     * map: new THREE.TextureLoader().load('path/to/texture.png');
+     *
+     * // No texture (default behavior)
+     * map: undefined;
+     */
+    map?: THREE.Texture;
+    /**
+     * Renderer configuration for blending, transparency, and depth testing.
+     *
+     * @see Renderer
+     * @default
+     * renderer: {
+     *   blending: THREE.NormalBlending,
+     *   discardBackgroundColor: false,
+     *   backgroundColorTolerance: 1.0,
+     *   backgroundColor: { r: 1.0, g: 1.0, b: 1.0 },
+     *   transparent: true,
+     *   depthTest: true,
+     *   depthWrite: false
+     * }
+     */
+    renderer?: Renderer;
+    /**
+     * Defines the velocity settings of particles over their lifetime.
+     * Configures both linear and orbital velocity changes.
+     *
+     * @see VelocityOverLifetime
+     * @default
+     * velocityOverLifetime: {
+     *   isActive: false,
+     *   linear: {
+     *     x: 0,
+     *     y: 0,
+     *     z: 0,
+     *   },
+     *   orbital: {
+     *     x: 0,
+     *     y: 0,
+     *     z: 0,
+     *   },
+     * }
+     */
+    velocityOverLifetime?: VelocityOverLifetime;
+    /**
+     * Controls the size of particles over their lifetime.
+     * The size can be adjusted using a lifetime curve (B??zier or other supported types).
+     *
+     * @default
+     * sizeOverLifetime: {
+     *   isActive: false,
+     *   lifetimeCurve: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    sizeOverLifetime?: {
+        isActive: boolean;
+        lifetimeCurve: LifetimeCurve;
+    };
+    /**
+     * Controls the opacity of particles over their lifetime.
+     * The opacity can be adjusted using a lifetime curve (B??zier or other supported types).
+     *
+     * @default
+     * opacityOverLifetime: {
+     *   isActive: false,
+     *   lifetimeCurve: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    opacityOverLifetime?: {
+        isActive: boolean;
+        lifetimeCurve: LifetimeCurve;
+    };
+    /**
+     * Controls the color of particles over their lifetime.
+     * Each RGB channel can be adjusted independently using a lifetime curve (B??zier or easing).
+     * The curves act as multipliers (0-1 range) that are applied to the particle's start color.
+     *
+     * This follows Unity's Color over Lifetime behavior where the final color is:
+     * finalColor = startColor * colorOverLifetime
+     *
+     * **IMPORTANT**: To achieve full color transitions, set startColor to white { r: 1, g: 1, b: 1 }.
+     * If startColor has any channel set to 0, that channel cannot be modified by colorOverLifetime.
+     *
+     * @example
+     * // Rainbow effect - requires white startColor
+     * startColor: { min: { r: 1, g: 1, b: 1 }, max: { r: 1, g: 1, b: 1 } }
+     * colorOverLifetime: {
+     *   isActive: true,
+     *   r: { // Red: full -> half -> off
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 0.5, y: 0.5, percentage: 0.5 },
+     *       { x: 1, y: 0, percentage: 1 },
+     *     ],
+     *   },
+     *   g: { // Green: off -> full -> off
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 0.5, y: 1, percentage: 0.5 },
+     *       { x: 1, y: 0, percentage: 1 },
+     *     ],
+     *   },
+     *   b: { // Blue: off -> half -> full
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 0.5, y: 0.5, percentage: 0.5 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     *
+     * @default
+     * colorOverLifetime: {
+     *   isActive: false,
+     *   r: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     *   g: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     *   b: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    colorOverLifetime?: {
+        isActive: boolean;
+        r: LifetimeCurve;
+        g: LifetimeCurve;
+        b: LifetimeCurve;
+    };
+    /**
+     * Controls the rotation of particles over their lifetime.
+     * The rotation can be randomized between two constants, and the feature can be toggled on or off.
+     *
+     * @default
+     * rotationOverLifetime: {
+     *   isActive: false,
+     *   min: 0.0,
+     *   max: 0.0,
+     * }
+     */
+    rotationOverLifetime?: {
+        isActive: boolean;
+    } & RandomBetweenTwoConstants;
+    /**
+     * Noise configuration affecting position, rotation, and size.
+     *
+     * @see NoiseConfig
+     * @default
+     * noise: {
+     *   isActive: false,
+     *   useRandomOffset: false,
+     *   strength: 1.0,
+     *   frequency: 0.5,
+     *   octaves: 1,
+     *   positionAmount: 1.0,
+     *   rotationAmount: 0.0,
+     *   sizeAmount: 0.0,
+     * }
+     */
+    noise?: NoiseConfig;
+    /**
+     * Configures the texture sheet animation settings for particles.
+     * Controls how textures are animated over the lifetime of particles.
+     *
+     * @see TextureSheetAnimation
+     * @default
+     * textureSheetAnimation: {
+     *   tiles: new THREE.Vector2(1.0, 1.0),
+     *   timeMode: TimeMode.LIFETIME,
+     *   fps: 30.0,
+     *   startFrame: 0,
+     * }
+     */
+    textureSheetAnimation?: TextureSheetAnimation;
+    /**
+     * Sub-emitters that spawn child particle systems on particle lifecycle events.
+     * Each sub-emitter is triggered when a particle is born or dies, creating a new
+     * particle system at the parent particle's position.
+     *
+     * @example
+     * ```typescript
+     * subEmitters: [
+     *   {
+     *     trigger: SubEmitterTrigger.DEATH,
+     *     config: { startLifeTime: 0.5, startSpeed: 1, emission: { rateOverTime: 10 } },
+     *   },
+     * ]
+     * ```
+     */
+    subEmitters?: Array<SubEmitterConfig>;
+    /**
+     * Force fields that affect particle velocities.
+     * Each force field can attract, repel, or push particles in a direction.
+     * Multiple force fields are applied cumulatively.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * forceFields: [
+     *   {
+     *     type: ForceFieldType.POINT,
+     *     position: new THREE.Vector3(0, 0, 0),
+     *     strength: 5.0,
+     *     range: 10,
+     *     falloff: ForceFieldFalloff.QUADRATIC,
+     *   },
+     * ]
+     * ```
+     */
+    forceFields?: Array<ForceFieldConfig>;
+    /**
+     * Collision planes that constrain particle positions.
+     *
+     * Each plane defines an infinite surface in 3D space. When a particle crosses
+     * from the front side (positive normal direction) to the back side, the
+     * configured response mode is triggered: KILL (remove), CLAMP (stop at surface),
+     * or BOUNCE (reflect with energy loss).
+     *
+     * Plane positions and normals are in world space. Multiple planes are checked
+     * in order; for KILL mode, the first collision deactivates the particle.
+     *
+     * @default []
+     *
+     * @example
+     * ```typescript
+     * collisionPlanes: [
+     *   {
+     *     position: { x: 0, y: 5, z: 0 },
+     *     normal: { x: 0, y: -1, z: 0 },
+     *     mode: CollisionPlaneMode.KILL,
+     *   },
+     * ]
+     * ```
+     */
+    collisionPlanes?: Array<CollisionPlaneConfig>;
+    /**
+     * Called on every update frame with particle system data.
+     */
+    onUpdate?: (data: {
+        particleSystem: THREE.Points | THREE.Mesh;
+        delta: number;
+        elapsed: number;
+        lifetime: number;
+        iterationCount: number;
+    }) => void;
+    /**
+     * Called when the system completes an iteration.
+     */
+    onComplete?: () => void;
+};
+type NormalizedParticleSystemConfig = Required<ParticleSystemConfig>;
+/**
+ * Tracks the state of a burst emission event.
+ * Used internally to determine when bursts should fire and how many cycles remain.
+ */
+type BurstState = {
+    /** Number of cycles that have been executed so far */
+    cyclesExecuted: number;
+    /** Time (in ms) when the last cycle was executed */
+    lastCycleTime: number;
+    /** Whether the probability check passed for this iteration */
+    probabilityPassed: boolean;
+};
+type GeneralData = {
+    particleSystemId: number;
+    normalizedLifetimePercentage: number;
+    creationTimes: Float32Array;
+    distanceFromLastEmitByDistance: number;
+    lastWorldPosition: THREE.Vector3;
+    currentWorldPosition: THREE.Vector3;
+    worldPositionChange: THREE.Vector3;
+    /**
+     * For WORLD simulation space: the full world transform of the emitter
+     * (parent.matrixWorld ?? particleSystem.matrix). Used to position new
+     * particles in world coordinates at emit time and to orient the
+     * emission shape. The particleSystem's own matrixWorld is forced to
+     * identity so the buffer coordinates render as world coordinates.
+     */
+    sourceWorldMatrix: THREE.Matrix4;
+    wrapperQuaternion: THREE.Quaternion;
+    worldQuaternion: THREE.Quaternion;
+    /**
+     * Emitter world scale (decomposed from the full parent chain). Used to
+     * match Unity's parent-scale semantics:
+     *   - WORLD mode: scales the shape-emission offset at spawn time (the
+     *     Shape module in Unity obeys parent scale when Scaling Mode is
+     *     Local/Hierarchy). Live particles are unaffected.
+     *   - LOCAL mode: gravity is stored in local units, so it is divided by
+     *     this scale so the rendered fall matches world -g m/s?? regardless
+     *     of parent scale.
+     */
+    worldScale: THREE.Vector3;
+    worldEuler: THREE.Euler;
+    gravityVelocity: THREE.Vector3;
+    startValues: Record<string, Array<number>>;
+    linearVelocityData?: Array<{
+        speed: THREE.Vector3;
+        valueModifiers: {
+            x?: CurveFunction;
+            y?: CurveFunction;
+            z?: CurveFunction;
+        };
+    }>;
+    orbitalVelocityData?: Array<{
+        speed: THREE.Vector3;
+        positionOffset: THREE.Vector3;
+        valueModifiers: {
+            x?: CurveFunction;
+            y?: CurveFunction;
+            z?: CurveFunction;
+        };
+    }>;
+    lifetimeValues: Record<string, Array<number>>;
+    noise: Noise;
+    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;
+    /**
+     * 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;
+    /**
+     * Number of trail vertex-buffer slots filled per particle in the previous
+     * frame. Lets the trail update skip re-clearing slots that are already
+     * cleared (they stay invisible via zero alpha/half-width).
+     */
+    trailPrevFilledCount?: Uint16Array;
+    /**
+     * Highest particle index ever written on the CPU path (monotonic).
+     * The per-frame buffer flush uploads `[0, watermark]` as a single update
+     * range ??? a provably covering superset of every write since the last GPU
+     * upload, independent of render timing. -1 = nothing written yet.
+     */
+    cpuDirtyParticleWatermark: number;
+    /** Highest ever-active slot + 1 (monotonic). Bounds every per-frame per-particle walk. 0 = nothing emitted yet. */
+    highWaterIndex: number;
+    /**
+     * Pre-resolved lifetime-curve functions for the size / opacity / color
+     * modifiers (scale already applied). Resolved once at system creation and
+     * re-resolved by `updateConfig` ??? evaluating these per particle per frame
+     * avoids the curve-function lookup and closure allocations of
+     * `calculateValue`. Undefined entries fall back to `calculateValue`
+     * (e.g. constant or random-range values).
+     */
+    modifierCurves?: {
+        size?: CurveFunction;
+        opacity?: CurveFunction;
+        colorR?: CurveFunction;
+        colorG?: CurveFunction;
+        colorB?: CurveFunction;
+    };
+};
+/** Union of all buffer attribute types Three.js uses in geometry. */
+type AnyBufferAttribute = THREE.BufferAttribute | THREE.InstancedBufferAttribute | THREE.InterleavedBufferAttribute;
+/**
+ * A view that maps standard attribute names (e.g. 'position', 'size') to
+ * their actual geometry attribute objects, which may have different names
+ * in the instanced renderer (e.g. 'instanceOffset', 'instanceSize').
+ */
+type MappedAttributes = {
+    position: AnyBufferAttribute;
+    isActive: AnyBufferAttribute;
+    lifetime: AnyBufferAttribute;
+    startLifetime: AnyBufferAttribute;
+    startFrame: AnyBufferAttribute;
+    size: AnyBufferAttribute;
+    rotation: AnyBufferAttribute;
+    /** Packed RGBA color (vec4). */
+    color: AnyBufferAttribute;
+    /** Packed quaternion vec4 for 3D mesh rotation (only present for RendererType.MESH). */
+    quat?: AnyBufferAttribute;
+};
+type ParticleSystemInstance = {
+    particleSystem: THREE.Points | THREE.Mesh;
+    mappedAttributes: MappedAttributes;
+    /** Shared interleaved Float32Array backing all scalar per-particle attributes. */
+    scalarArray: Float32Array;
+    /** The InterleavedBuffer (or InstancedInterleavedBuffer) for scalar attributes. */
+    scalarInterleavedBuffer: THREE.InterleavedBuffer;
+    elapsedUniform: {
+        value: number;
+    };
+    generalData: GeneralData;
+    onUpdate: (data: {
+        particleSystem: THREE.Points | THREE.Mesh;
+        delta: number;
+        elapsed: number;
+        lifetime: number;
+        normalizedLifetime: number;
+        iterationCount: number;
+    }) => void;
+    onComplete: (data: {
+        particleSystem: THREE.Points | THREE.Mesh;
+    }) => void;
+    creationTime: number;
+    lastEmissionTime: number;
+    /**
+     * Fractional particles carried over between frames by time-based emission.
+     * Prevents `Math.floor` from systematically dropping the remainder
+     * (e.g. rate 100/s at 60 FPS = 1.66 particles/frame).
+     */
+    emissionAccumulator: number;
+    duration: number;
+    looping: boolean;
+    simulationSpace: SimulationSpace;
+    gravity: number;
+    normalizedForceFields: Array<NormalizedForceFieldConfig>;
+    normalizedCollisionPlanes: Array<NormalizedCollisionPlaneConfig>;
+    emission: Emission;
+    normalizedConfig: NormalizedParticleSystemConfig;
+    iterationCount: number;
+    velocities: Array<THREE.Vector3>;
+    freeList: Array<number>;
+    deactivateParticle: (particleIndex: number) => void;
+    /**
+     * Deactivates a particle and fires death sub-emitters first (when
+     * configured). Stable per-system callback so the collision-plane hot loop
+     * does not allocate a closure per particle per frame.
+     */
+    killParticle: (particleIndex: number) => void;
+    activateParticle: (data: {
+        particleIndex: number;
+        activationTime: number;
+        position: Required<Point3D>;
+    }) => void;
+    /** Called when a particle dies to trigger death sub-emitters */
+    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 geometry next-position attribute (cached to avoid repeated getAttribute) */
+    trailNextAttr?: THREE.BufferAttribute;
+    /** Trail geometry half-width attribute (cached) */
+    trailHalfWidthAttr?: THREE.BufferAttribute;
+    /** Trail geometry UV attribute (cached) */
+    trailUVAttr?: 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, and advanced features) */
+    trailConfig?: {
+        length: number;
+        width: number;
+        minVertexDistance: number;
+        maxTime: number;
+        smoothing: boolean;
+        smoothingSubdivisions: number;
+        twistPrevention: boolean;
+        ribbonId?: number;
+    };
+    /** GPU compute pipeline for WebGPU simulation. Opaque type to avoid pulling TSL types into DTS. */
+    computePipeline?: {
+        computeNode: unknown;
+        /** Ordered list of compute dispatches: [emitNode, simNode] on the GPU-only engine. */
+        computeNodes?: unknown[];
+        /** Emission dispatch; its numeric `count` is refreshed from `emitCount` per frame. */
+        emitNode?: unknown;
+        /** Per-frame simulation dispatch (count = `maxParticles`). */
+        simNode?: unknown;
+        /** Dedicated trail-history pass node (after simulate; 4 storage bindings). */
+        trailHistoryNode?: unknown;
+        /** Dedicated sub-emitter BIRTH event pass node (5..7 storage bindings). */
+        subBirthEventsNode?: unknown;
+        /** Dedicated sub-emitter DEATH event pass node (5..7 storage bindings). */
+        subDeathEventsNode?: unknown;
+        /** Real per-pass storage/uniform budgets (every pass <= 8 storages). */
+        passLayouts?: Array<{
+            name: string;
+            storageBindings: number;
+            uniformBindings: number;
+        }>;
+        uniforms: Record<string, unknown>;
+        /** GPU storage buffers that are ALSO attached as geometry attributes. */
+        buffers: Record<string, unknown>;
+        /** Element count of the uint atomic allocator stack (`maxParticles + 1`). */
+        allocatorCount?: number;
+        /** Non-atomic f32 uniform-table node (baked curves + force fields + collision planes). */
+        packedDataNode?: unknown;
+        /**
+         * Emitter-pose uniforms written per frame by the update loop:
+         * `positionW` = (x, y, z, isWorldFlag), `wrapperQuat` = (x, y, z, w),
+         * `worldScale` = (sx, sy, sz).
+         */
+        emitterPose?: {
+            positionW: unknown;
+            wrapperQuat: unknown;
+            worldScale: unknown;
+        };
+        forceFieldInfo: {
+            offset: number;
+            countUniform: unknown;
+        } | null;
+        /** Optional for backwards compat with the older single-forceFieldInfo shape. */
+        collisionPlaneInfo?: {
+            offset: number;
+            countUniform: unknown;
+        } | null;
+        /** Shape/start-value scalar uniforms for construction-time diagnostics. */
+        shapeUniforms?: Record<string, unknown>;
+        /** Semantic compute pass names in dispatch order. */
+        passNames?: string[];
+        /** Trail ring integer metadata attribute (null when there is no trail). */
+        trailMeta?: unknown;
+    };
+    /** Whether this system uses GPU compute for simulation. */
+    useGPUCompute?: boolean;
+    /** Flag set by update loop, consumed by onBeforeRender to dispatch compute. */
+    computeDispatchReady?: boolean;
+    /** Storage-pool capacity, used to cap `instanceCount` on the geometry. */
+    maxParticles?: number;
+    /** Attached material (TSL NodeMaterial or legacy ShaderMaterial). */
+    material?: THREE.Material;
+    /** Attached geometry (used to sync `instanceCount` on CPU/GPU transitions). */
+    geometry?: THREE.BufferGeometry | THREE.InstancedBufferGeometry;
+    /** Chosen renderer type; used to derive `instanceCount` behaviour after `updateConfig`. */
+    rrType?: "POINTS" | "INSTANCED" | "MESH" | "TRAIL";
+    /** Original `renderer.rendererType` from the config (§2). */
+    requestedRendererType?: "POINTS" | "INSTANCED" | "MESH" | "TRAIL";
+    /** Canonical effective GPU renderer class after POINTS resolution (§2). */
+    effectiveRendererType?: "POINTS" | "INSTANCED" | "MESH" | "TRAIL";
+    /** Cached TSL shared uniform table. */
+    sharedUniforms?: {
+        [k: string]: {
+            value: unknown;
+        };
+    };
+    /**
+     * Every compute node of this system in dispatch order:
+     * `[emit, sim, ribbon?, (init, childEmit, childSim)?]`.
+     */
+    allComputeNodes?: unknown[];
+    /** Semantic pass names in dispatch order (for `[PS:pipeline]` logging). */
+    passNames?: string[];
+    /** Per-system sub-emitter child kernels + their own scalar state. */
+    subEntries?: {
+        fifo: {
+            capacity: number;
+            windowSize: number;
+        };
+        requestedRendererType?: "POINTS" | "INSTANCED" | "MESH" | "TRAIL";
+        effectiveRendererType?: "POINTS" | "INSTANCED" | "MESH" | "TRAIL";
+        pipeline: Record<string, any> | undefined;
+        init: {
+            commandBuildNode: unknown;
+            childInitNode: unknown;
+            counterClearNode?: unknown;
+            commandBuffer?: unknown;
+            passLayouts?: Array<{
+                name: string;
+                storageBindings: number;
+                uniformBindings: number;
+            }>;
+            passName?: string;
+            counterClearPassName?: string;
+            uniforms: Record<string, {
+                value: unknown;
+            }>;
+        };
+        gravity: number;
+        noise: GeneralData['noise'] | null;
+        rate: number;
+        acc: number;
+        isWorld: 0 | 1;
+        quat: [number, number, number, number];
+        scale: [number, number, number];
+        position: [number, number, number];
+    }[];
+    /** Shared ping-pong window stride of the FIFO buffers. */
+    fifoBaseStride?: number;
+    /** Trail ribbon kernel uniforms (`nowMs`), present for RendererType.TRAIL. */
+    ribbonUniforms?: {
+        [k: string]: {
+            value: unknown;
+        };
+    };
+    /** Trail ribbon storage attributes (first-frame upload only). */
+    ribbonBuffers?: {
+        [k: string]: THREE.BufferAttribute;
+    };
+    /** Frame parity counter (0/1) driving the FIFO ping-pong windows. */
+    frameParity?: number;
+};
+/**
+ * Represents a particle system instance, providing methods to control and manage its lifecycle.
+ *
+ * @property instance - The underlying Three.js `Points` or `Mesh` object used for particle rendering.
+ * @property resumeEmitter - Resumes the particle emitter, allowing particles to be emitted again.
+ * @property pauseEmitter - Pauses the particle emitter, stopping any new particles from being emitted.
+ * @property dispose - Disposes of the particle system, cleaning up resources to free memory.
+ *
+ * @example
+ * const particleSystem: ParticleSystem = {
+ *   instance: new THREE.Points(geometry, material),
+ *   resumeEmitter: () => { /* resume logic * / },
+ *   pauseEmitter: () => { /* pause logic * / },
+ *   dispose: () => { /* cleanup logic * / },
+ * };
+ *
+ * particleSystem.pauseEmitter(); // Stop particle emission
+ * particleSystem.resumeEmitter(); // Resume particle emission
+ * particleSystem.dispose(); // Cleanup the particle system
+ */
+type ParticleSystem = {
+    instance: THREE.Points | THREE.Mesh;
+    resumeEmitter: () => void;
+    pauseEmitter: () => void;
+    dispose: () => void;
+    update: (cycleData: CycleData) => void;
+    /**
+     * ?? Deprecated synchronous count ???? Returns `-1` (unsupported) on the
+     * GPU-only engine. Authoritative value: `maxParticles - allocator[0]`, read
+     * on demand through `renderer.getArrayBufferAsync` + `gpuDebug`.
+     */
+    getActiveParticleCount?: () => number;
+    /**
+     * ?? Temporary / deprecated one-shot GPU debug handle ????
+     * Raw material for an explicit `renderer.getArrayBufferAsync(...)` read-back
+     * (byte offset + byte count, multiples of 4). No per-frame cost.
+     */
+    gpuDebug?: {
+        maxParticles: number;
+        allocatorCount: number;
+        buffers: Record<string, unknown>;
+        emitNode: unknown;
+        simNode: unknown;
+        passNames?: string[];
+        allPassNames?: string[];
+        storageBindingCount?: number;
+        passBindingCounts?: Array<[string, number]>;
+        lastEmitCount: () => number;
+        snapshot?: () => Record<string, unknown>;
+    };
+    /** Ordered WebGPU compute nodes, dispatched in order. `renderer.compute(...)` accepts a single `Node` or an array; the GPU-only engine returns the [emitNode, simNode] pair. */
+    computeNode: unknown | unknown[] | null;
+    /**
+     * Updates the particle system configuration at runtime without recreating the system.
+     *
+     * System-level properties (gravity, force fields, noise, emission rates, color/size/opacity
+     * over lifetime curves) take effect immediately for all particles.
+     * Per-particle spawn properties (startColor, startSize, startSpeed, startLifetime, etc.)
+     * only affect newly emitted particles ??? already-alive particles retain their original values.
+     *
+     * @param config - A partial configuration object. Only the provided properties will be updated;
+     *   all other settings remain unchanged.
+     *
+     * @remarks
+     * Structural properties that are set at creation time cannot be changed at runtime:
+     * `maxParticles`, `renderer.rendererType`, `shape`, and `map` (texture).
+     * Passing these will update the internal config but have no visible effect since the
+     * geometry and material are pre-allocated.
+     *
+     * **GPU compute limitation:** when the system runs on the WebGPU compute
+     * backend, modifier activation flags and lifetime curves
+     * (`sizeOverLifetime`, `opacityOverLifetime`, `colorOverLifetime`,
+     * `rotationOverLifetime`, `velocityOverLifetime`, `noise.isActive`) are
+     * baked into the compute kernel at creation and cannot be changed live ???
+     * a console warning is emitted and the system must be recreated instead.
+     * On the CPU backend all of these update live.
+     *
+     * @example
+     * ```typescript
+     * const system = createParticleSystem(config);
+     *
+     * // Change wind direction in real time
+     * system.updateConfig({
+     *   forceFields: [{ type: ForceFieldType.DIRECTIONAL, direction: { x: 1, y: 0, z: 0 }, strength: 5 }],
+     * });
+     *
+     * // Gradually change color of new particles
+     * system.updateConfig({
+     *   startColor: { min: { r: 1, g: 0, b: 0 }, max: { r: 1, g: 0.5, b: 0 } },
+     * });
+     * ```
+     */
+    updateConfig: (config: Partial<ParticleSystemConfig>) => void;
+};
+/**
+ * Data representing the current cycle of the particle system's update loop.
+ *
+ * @property now - The current timestamp in milliseconds.
+ * @property delta - The time elapsed since the last update, in seconds.
+ * @property elapsed - The total time elapsed since the particle system started, in seconds.
+ *
+ * @example
+ * const cycleData: CycleData = {
+ *   now: performance.now(),
+ *   delta: 0.016, // 16ms frame time
+ *   elapsed: 1.25, // 1.25 seconds since start
+ * };
+ */
+type CycleData = {
+    now: number;
+    delta: number;
+    elapsed: number;
+};
+
+declare const createBezierCurveFunction: (particleSystemId: number, bezierPoints: Array<BezierPoint>) => CurveFunction;
+declare const removeBezierCurveFunction: (particleSystemId: number) => void;
+declare const getBezierCacheSize: () => number;
+
+/**
+ * Predefined easing function identifiers for animating particle properties
+ * over their lifetime.
+ *
+ * These functions control the rate of change and create different animation
+ * feels. Each type has three variants:
+ * - **IN**: Starts slow, accelerates toward the end
+ * - **OUT**: Starts fast, decelerates toward the end
+ * - **IN_OUT**: Combines both, slow at start and end, fast in middle
+ *
+ * @enum {string}
+ *
+ * @see {@link https://easings.net/} - Visual reference for easing functions
+ */
+declare const enum CurveFunctionId {
+    /** Use custom Bezier curve (not an easing function) */
+    BEZIER = "BEZIER",
+    /** Linear interpolation with constant rate of change */
+    LINEAR = "LINEAR",
+    /** Quadratic (t??) easing - gentle acceleration */
+    QUADRATIC_IN = "QUADRATIC_IN",
+    /** Quadratic (t??) easing - gentle deceleration */
+    QUADRATIC_OUT = "QUADRATIC_OUT",
+    /** Quadratic (t??) easing - gentle acceleration then deceleration */
+    QUADRATIC_IN_OUT = "QUADRATIC_IN_OUT",
+    /** Cubic (t??) easing - moderate acceleration */
+    CUBIC_IN = "CUBIC_IN",
+    /** Cubic (t??) easing - moderate deceleration */
+    CUBIC_OUT = "CUBIC_OUT",
+    /** Cubic (t??) easing - moderate acceleration then deceleration */
+    CUBIC_IN_OUT = "CUBIC_IN_OUT",
+    /** Quartic (t???) easing - strong acceleration */
+    QUARTIC_IN = "QUARTIC_IN",
+    /** Quartic (t???) easing - strong deceleration */
+    QUARTIC_OUT = "QUARTIC_OUT",
+    /** Quartic (t???) easing - strong acceleration then deceleration */
+    QUARTIC_IN_OUT = "QUARTIC_IN_OUT",
+    /** Quintic (t???) easing - very strong acceleration */
+    QUINTIC_IN = "QUINTIC_IN",
+    /** Quintic (t???) easing - very strong deceleration */
+    QUINTIC_OUT = "QUINTIC_OUT",
+    /** Quintic (t???) easing - very strong acceleration then deceleration */
+    QUINTIC_IN_OUT = "QUINTIC_IN_OUT",
+    /** Sinusoidal easing - smooth, natural acceleration */
+    SINUSOIDAL_IN = "SINUSOIDAL_IN",
+    /** Sinusoidal easing - smooth, natural deceleration */
+    SINUSOIDAL_OUT = "SINUSOIDAL_OUT",
+    /** Sinusoidal easing - smooth acceleration then deceleration */
+    SINUSOIDAL_IN_OUT = "SINUSOIDAL_IN_OUT",
+    /** Exponential easing - dramatic, explosive acceleration */
+    EXPONENTIAL_IN = "EXPONENTIAL_IN",
+    /** Exponential easing - dramatic, explosive deceleration */
+    EXPONENTIAL_OUT = "EXPONENTIAL_OUT",
+    /** Exponential easing - dramatic acceleration then deceleration */
+    EXPONENTIAL_IN_OUT = "EXPONENTIAL_IN_OUT",
+    /** Circular easing - sharp acceleration with curved trajectory */
+    CIRCULAR_IN = "CIRCULAR_IN",
+    /** Circular easing - sharp deceleration with curved trajectory */
+    CIRCULAR_OUT = "CIRCULAR_OUT",
+    /** Circular easing - sharp acceleration then deceleration */
+    CIRCULAR_IN_OUT = "CIRCULAR_IN_OUT",
+    /** Elastic easing - oscillates back before accelerating (spring-like) */
+    ELASTIC_IN = "ELASTIC_IN",
+    /** Elastic easing - overshoots then oscillates back (spring-like) */
+    ELASTIC_OUT = "ELASTIC_OUT",
+    /** Elastic easing - oscillates at both ends (spring-like) */
+    ELASTIC_IN_OUT = "ELASTIC_IN_OUT",
+    /** Back easing - pulls back before accelerating forward */
+    BACK_IN = "BACK_IN",
+    /** Back easing - overshoots forward then pulls back */
+    BACK_OUT = "BACK_OUT",
+    /** Back easing - pulls back, overshoots, then settles */
+    BACK_IN_OUT = "BACK_IN_OUT",
+    /** Bounce easing - bounces at the start */
+    BOUNCE_IN = "BOUNCE_IN",
+    /** Bounce easing - bounces at the end (like a ball landing) */
+    BOUNCE_OUT = "BOUNCE_OUT",
+    /** Bounce easing - bounces at both start and end */
+    BOUNCE_IN_OUT = "BOUNCE_IN_OUT"
+}
+declare const curveFunctionIdMap: Partial<Record<CurveFunctionId, CurveFunction>>;
+/**
+ * Resolves a curve function from an identifier or returns the function itself.
+ *
+ * This utility function allows you to use either a {@link CurveFunctionId} string
+ * identifier or a custom function directly.
+ *
+ * @param curveFunctionId - Either a {@link CurveFunctionId} enum value or a
+ *                          custom {@link CurveFunction} implementation
+ * @returns The actual easing function that takes a normalized time value (0-1)
+ *          and returns the eased value
+ *
+ * @example
+ * ```typescript
+ * import { getCurveFunction, CurveFunctionId } from '@cyberluke/three-particles';
+ *
+ * // Using a predefined easing function
+ * const easingFunc = getCurveFunction(CurveFunctionId.CUBIC_OUT);
+ * console.log(easingFunc(0.5)); // Returns eased value at 50% progress
+ *
+ * // Using a custom function
+ * const customEasing = (t: number) => t * t; // Quadratic
+ * const customFunc = getCurveFunction(customEasing);
+ * console.log(customFunc(0.5)); // Returns 0.25
+ * ```
+ */
+declare const getCurveFunction: (curveFunctionId: CurveFunctionId | CurveFunction) => CurveFunction;
+
+/**
+ * Applies all active modifiers to a single particle during the update cycle.
+ *
+ * This function handles the animation and modification of particle properties over its lifetime,
+ * including velocity (linear and orbital), size, opacity, color, rotation, and noise-based effects.
+ * It is called once per particle per frame by the {@link updateParticleSystems} function.
+ *
+ * @param params - Configuration object containing:
+ * @param params.delta - Time elapsed since the last frame in seconds. Used for velocity and rotation calculations.
+ * @param params.generalData - Internal particle system state and cached values.
+ * @param params.normalizedConfig - The normalized particle system configuration with all modifiers.
+ * @param params.attributes - Three.js buffer attributes for position, size, rotation, and color.
+ * @param params.particleLifetimePercentage - Normalized lifetime of the particle (0.0 to 1.0).
+ *   - 0.0 = particle just born
+ *   - 1.0 = particle at end of life
+ * @param params.particleIndex - Index of the particle in the buffer arrays.
+ *
+ * @remarks
+ * The function modifies the following particle properties based on configuration:
+ *
+ * - **Linear Velocity**: Moves particles in a straight line (velocityOverLifetime.linear)
+ * - **Orbital Velocity**: Rotates particles around their emission point (velocityOverLifetime.orbital)
+ * - **Size Over Lifetime**: Scales particle size based on lifetime curve (sizeOverLifetime)
+ * - **Opacity Over Lifetime**: Fades particles in/out based on lifetime curve (opacityOverLifetime)
+ * - **Color Over Lifetime**: Animates RGB channels independently based on lifetime curves (colorOverLifetime)
+ * - **Rotation Over Lifetime**: Rotates particles around their center (rotationOverLifetime)
+ * - **Noise**: Adds organic, turbulent motion to position, rotation, and size (noise)
+ *
+ * Each modifier only runs if it's active in the configuration, optimizing performance for simple effects.
+ *
+ * @example
+ * ```typescript
+ * // This function is called internally by updateParticleSystems
+ * // You typically don't need to call it directly
+ *
+ * // However, understanding its behavior helps configure particle systems:
+ * const config = {
+ *   sizeOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'BEZIER',
+ *       bezierPoints: [
+ *         { x: 0, y: 0, percentage: 0 },    // Start at 0% size
+ *         { x: 0.5, y: 1, percentage: 0.5 }, // Grow to 100% at midlife
+ *         { x: 1, y: 0, percentage: 1 }      // Shrink to 0% at end
+ *       ]
+ *     }
+ *   },
+ *   opacityOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'EASING',
+ *       curveFunction: 'easeOutQuad'
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link updateParticleSystems} - Calls this function for each active particle
+ * @see {@link VelocityOverLifetime} - Configuration for velocity modifiers
+ * @see {@link NoiseConfig} - Configuration for noise-based effects
+ */
+declare const applyModifiers: ({ delta, generalData, normalizedConfig, attributes, scalarArray, particleLifetimePercentage, particleIndex, updateFlags, }: {
+    delta: number;
+    generalData: GeneralData;
+    normalizedConfig: NormalizedParticleSystemConfig;
+    attributes: MappedAttributes;
+    scalarArray: Float32Array;
+    particleLifetimePercentage: number;
+    particleIndex: number;
+    /**
+     * Optional aggregation target for attribute dirty flags. When provided,
+     * `position`/`quat` are set to `true` here instead of writing
+     * `attribute.needsUpdate` — the caller flushes once per frame rather than
+     * bumping the attribute version once per particle.
+     */
+    updateFlags?: {
+        position: boolean;
+        quat: boolean;
+    };
+}) => void;
+
+/**
+ * Checks whether the given renderer supports GPU compute dispatches.
+ *
+ * Uses duck-typing: a renderer is considered WebGPU-capable when it exposes
+ * a `.compute()` method and a `.hasFeature()` method (both present on
+ * `THREE.WebGPURenderer` but absent from `THREE.WebGLRenderer`).
+ *
+ * @param renderer - Any Three.js renderer instance.
+ * @returns `true` when the renderer supports compute shaders.
+ */
+declare function isComputeCapableRenderer(renderer: unknown): boolean;
+/**
+ * Resolves the effective simulation backend based on the user's preference
+ * and the capabilities of the provided renderer.
+ *
+ * | Preference | WebGPURenderer | WebGLRenderer |
+ * |------------|---------------|---------------|
+ * | `AUTO`     | `GPU`         | `CPU`         |
+ * | `CPU`      | `CPU`         | `CPU`         |
+ * | `GPU`      | `GPU`         | `CPU` (fallback) |
+ *
+ * @param renderer - The Three.js renderer instance used for rendering.
+ * @param preference - The user-specified simulation backend preference.
+ * @returns The resolved {@link SimulationBackend} (`CPU` or `GPU`).
+ */
+declare function resolveSimulationBackend(renderer: unknown, preference?: SimulationBackend): SimulationBackend.CPU | SimulationBackend.GPU;
+
+/**
+ * Serializes a `ParticleSystemConfig` to a JSON string.
+ *
+ * - `THREE.Vector3` / `THREE.Vector2` are converted to plain `{x, y, z}` / `{x, y}` objects.
+ * - `renderer.blending` is converted to its string identifier (e.g. `"THREE.AdditiveBlending"`).
+ * - `EasingCurve.curveFunction` is replaced by a `curveFunctionId` string.
+ *   Only predefined `CurveFunctionId` functions can be serialized; custom functions throw.
+ * - `THREE.Texture` (`map`), callback fields (`onUpdate`, `onComplete`) are omitted.
+ * - An `_editorData` field and other unknown fields are preserved as-is.
+ * - A `_version` field is added for forward-compatibility.
+ *
+ * @param config - The particle system configuration to serialize.
+ * @returns A JSON string representation of the config.
+ * @throws If the config contains a custom (non-predefined) `curveFunction`.
+ *
+ * @example
+ * ```typescript
+ * import { serializeParticleSystem } from '@cyberluke/three-particles';
+ *
+ * const json = serializeParticleSystem(config);
+ * localStorage.setItem('myEffect', json);
+ * ```
+ */
+declare function serializeParticleSystem(config: ParticleSystemConfig): string;
+/**
+ * Deserializes a JSON string produced by `serializeParticleSystem` (or by the
+ * three-particles-editor) into a `ParticleSystemConfig` object.
+ *
+ * - Blending strings (e.g. `"THREE.AdditiveBlending"`) are converted back to
+ *   `THREE.Blending` constants.
+ * - `{x, y, z}` objects under `transform` are reconstructed as `THREE.Vector3`.
+ * - `{x, y}` objects under `textureSheetAnimation.tiles` are reconstructed as `THREE.Vector2`.
+ * - Legacy B??zier curves without a `type` field (editor format) are normalized.
+ * - Easing curves stored as `{ type: "EASING", curveFunctionId }` have their
+ *   `curveFunction` resolved from the predefined map.
+ * - `_editorData` and other unknown fields are preserved.
+ *
+ * @param json - A JSON string produced by `serializeParticleSystem` or the editor.
+ * @returns A fully reconstructed `ParticleSystemConfig`.
+ *
+ * @example
+ * ```typescript
+ * import { deserializeParticleSystem } from '@cyberluke/three-particles';
+ *
+ * const config = deserializeParticleSystem(localStorage.getItem('myEffect')!);
+ * createParticleSystem(config);
+ * ```
+ */
+declare function deserializeParticleSystem(json: string): ParticleSystemConfig;
+
+/**
+ * Calculates random position and velocity for particles emitted from a sphere.
+ *
+ * Supports emission from the entire volume or just the shell of the sphere.
+ * Uses spherical coordinates for uniform distribution across the surface.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Sphere configuration
+ * @param params.radius - Radius of the sphere
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full sphere, 180 = hemisphere)
+ *
+ * @remarks
+ * - `radiusThickness = 1.0`: Emit from entire volume
+ * - `radiusThickness = 0.0`: Emit only from surface shell
+ * - Particles are emitted radially outward from the center
+ *
+ * @see {@link Sphere} - Configuration type for sphere shape
+ */
+declare const calculateRandomPositionAndVelocityOnSphere: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, }: {
+    radius: number;
+    radiusThickness: number;
+    arc: number;
+}) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a cone.
+ *
+ * Useful for directional particle effects like fire, smoke plumes, fountains,
+ * or spray effects. The cone emits particles in a spreading pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Cone configuration
+ * @param params.radius - Base radius of the cone
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full cone, 180 = half cone)
+ * @param params.angle - Cone opening angle in degrees (default: 90)
+ *                       Smaller values create tighter cones
+ *
+ * @remarks
+ * - The cone emits from its base (circular area) outward
+ * - Particles travel in a conical spread pattern
+ * - `angle = 0`: Straight line (no spread)
+ * - `angle = 90`: Wide cone
+ * - Common for fire (10-30°), smoke (30-60°), explosions (60-90°)
+ *
+ * @see {@link Cone} - Configuration type for cone shape
+ */
+declare const calculateRandomPositionAndVelocityOnCone: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, angle, }: {
+    radius: number;
+    radiusThickness: number;
+    arc: number;
+    angle?: number;
+}) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a box.
+ *
+ * Supports three emission modes: volume, shell (surface), and edges.
+ * Useful for area-based effects like dust clouds, rain, or geometric patterns.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Box configuration
+ * @param params.scale - Size of the box on each axis (width, height, depth)
+ * @param params.emitFrom - Emission mode:
+ *   - `VOLUME`: Random positions throughout the entire box volume
+ *   - `SHELL`: Random positions on the 6 faces (surface)
+ *   - `EDGE`: Random positions along the 12 edges
+ *
+ * @remarks
+ * - All particles emit with velocity along the +Z axis (forward)
+ * - Box is centered at the origin before rotation
+ * - VOLUME mode: Best for rain, snow, or volumetric clouds
+ * - SHELL mode: Best for hollow effects or surface particles
+ * - EDGE mode: Best for wireframe effects or particle outlines
+ *
+ * @see {@link Box} - Configuration type for box shape
+ * @see {@link EmitFrom} - Emission mode enum
+ */
+declare const calculateRandomPositionAndVelocityOnBox: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { scale, emitFrom }: {
+    scale: Point3D;
+    emitFrom: EmitFrom;
+}) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a circle.
+ *
+ * Emits particles from a circular area or ring. Useful for ground impacts,
+ * radial effects, magic circles, or any circular planar emission.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Circle configuration
+ * @param params.radius - Radius of the circle
+ * @param params.radiusThickness - Controls emission from area (1.0) vs edge (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full circle, 180 = semicircle)
+ *
+ * @remarks
+ * - Circle lies in the XY plane by default (Z = 0)
+ * - Particles emit along the +Z axis (perpendicular to circle)
+ * - `radiusThickness = 1.0`: Filled circle (disc)
+ * - `radiusThickness = 0.0`: Ring (circle edge only)
+ * - Good for ground impact effects, teleport circles, or radial bursts
+ *
+ * @see {@link Circle} - Configuration type for circle shape
+ */
+declare const calculateRandomPositionAndVelocityOnCircle: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, }: {
+    radius: number;
+    radiusThickness: number;
+    arc: number;
+}) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a rectangle.
+ *
+ * Emits particles from a rectangular planar area. Useful for rain on a surface,
+ * screen-space effects, or any planar emission pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Rectangle configuration
+ * @param params.rotation - Local rotation of the rectangle (degrees) before
+ *                          applying quaternion
+ * @param params.scale - Size of the rectangle (width and height)
+ *
+ * @remarks
+ * - Rectangle lies in the XY plane by default
+ * - Particles emit along the +Z axis (perpendicular to rectangle)
+ * - The rotation parameter allows tilting the rectangle before the main
+ *   quaternion rotation is applied
+ * - Good for rain effects, screen particles, or planar area emissions
+ *
+ * @see {@link Rectangle} - Configuration type for rectangle shape
+ */
+declare const calculateRandomPositionAndVelocityOnRectangle: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { rotation, scale }: {
+    rotation: Point3D;
+    scale: Point3D;
+}) => void;
+/**
+ * Creates a solid white 1x1 texture for mesh particles.
+ * Unlike the circle texture used by point/billboard renderers, mesh particles
+ * need a neutral texture so the geometry shape is visible.
+ * @returns {THREE.CanvasTexture | null} The generated texture or null if context fails.
+ */
+declare const createDefaultMeshTexture: () => THREE.CanvasTexture | null;
+/**
+ * Creates a default white circle texture using CanvasTexture.
+ * @returns {THREE.CanvasTexture | null} The generated texture or null if context fails.
+ */
+declare const createDefaultParticleTexture: () => THREE.CanvasTexture | null;
+declare const isLifeTimeCurve: (value: Constant | RandomBetweenTwoConstants | LifetimeCurve) => value is LifetimeCurve;
+declare const getCurveFunctionFromConfig: (particleSystemId: number, lifetimeCurve: LifetimeCurve) => CurveFunction;
+declare const calculateValue: (particleSystemId: number, value: Constant | RandomBetweenTwoConstants | LifetimeCurve, time?: number) => number;
+
+/**
+ * Interleaved scalar buffer layout constants.
+ *
+ * All per-particle float attributes (except position and quat) are packed
+ * into a single InterleavedBuffer to stay within the WebGPU vertex buffer
+ * limit of 8.
+ *
+ * Buffer layout per particle (stride = 10 floats):
+ * ```
+ * [isActive, lifetime, startLifetime, startFrame, size, rotation, colorR, colorG, colorB, colorA]
+ * ```
+ */
+/** Number of float32 elements per particle in the interleaved scalar buffer. */
+declare const SCALAR_STRIDE = 10;
+/** Offset for the isActive flag (0 = inactive, 1 = active). */
+declare const S_IS_ACTIVE = 0;
+/** Offset for the current lifetime of the particle in milliseconds. */
+declare const S_LIFETIME = 1;
+/** Offset for the total lifetime of the particle in milliseconds. */
+declare const S_START_LIFETIME = 2;
+/** Offset for the texture sheet animation start frame index. */
+declare const S_START_FRAME = 3;
+/** Offset for the particle size. */
+declare const S_SIZE = 4;
+/** Offset for the particle rotation (radians). */
+declare const S_ROTATION = 5;
+/** Offset for the red color channel (0..1). */
+declare const S_COLOR_R = 6;
+/** Offset for the green color channel (0..1). */
+declare const S_COLOR_G = 7;
+/** Offset for the blue color channel (0..1). */
+declare const S_COLOR_B = 8;
+/** Offset for the alpha (opacity) channel (0..1). */
+declare const S_COLOR_A = 9;
+
+/**
+ * `resolveWebGPUEffectiveRendererType` — canonical mapping between the four
+ * requested `rendererType` values and the four effective GPU render paths
+ * (native runtime classes in parentheses).
+ *
+ *   requested POINTS    -> effective POINTS   (billboard quad + `THREE.Points`).
+ *     POINTS IS a supported runtime class in this build: the billboard quad
+ *     is drawn as a non-instanced `THREE.Points`; the TSL point material uses
+ *     `pointUV` (r186 provides it for `PointsNodeMaterial`).
+ *   requested INSTANCED -> effective INSTANCED (quad/box + `THREE.Mesh` with
+ *     `InstancedBufferGeometry`).
+ *   requested TRAIL     -> effective TRAIL    (ribbon strip + `THREE.Mesh`).
+ *   requested MESH      -> effective MESH     (mesh/reused geometry +
+ *     `THREE.Mesh`).
+ *
+ * A missing / unknown request resolves to POINTS because `POINTS` is the
+ * default value of `renderer.rendererType` in the merged default config.
+ */
+declare function resolveWebGPUEffectiveRendererType(requested: RendererType | string | undefined): RendererType;
+
+type TSLMaterialFactory = {
+    createTSLParticleMaterial: (rendererType: RendererType, sharedUniforms: Record<string, {
+        value: unknown;
+    }>, rendererConfig: {
+        transparent: boolean;
+        blending: THREE.Blending;
+        depthTest: boolean;
+        depthWrite: boolean;
+    }, gpuCompute?: boolean) => THREE.Material;
+    createTSLTrailMaterial: (trailUniforms: Record<string, {
+        value: unknown;
+    }>, rendererConfig: {
+        transparent: boolean;
+        blending: THREE.Blending;
+        depthTest: boolean;
+        depthWrite: boolean;
+    }) => THREE.Material;
+    createComputePipeline?: (...args: any[]) => any;
+    writeParticleToModifierBuffers?: (...args: any[]) => void;
+    deactivateParticleInModifierBuffers?: (...args: any[]) => void;
+    flushEmitQueue?: (...args: any[]) => number;
+    registerCurveDataLength?: (...args: any[]) => void;
+    encodeForceFieldsForGPU?: (...args: any[]) => Float32Array;
+    encodeCollisionPlanesForGPU?: (...args: any[]) => Float32Array;
+    createSubEmitterFifoAttribute?: (...args: any[]) => any;
+    createSubEmitterInitUpdate?: (...args: any[]) => any;
+    createTrailRibbonUpdate?: (...args: any[]) => any;
+    encodeShapeEmitParams?: (...args: any[]) => any;
+};
+/**
+ * Registers the TSL (Three Shading Language) material factory for WebGPU support.
+ *
+ * Call this **once** before creating any particle systems that use WebGPU rendering.
+ * The factory functions are imported from the `@cyberluke/three-particles/webgpu` sub-module.
+ *
+ * When registered, all particle systems will use TSL-based `NodeMaterial` (compiles to WGSL)
+ * instead of GLSL `ShaderMaterial`. If the factory also includes the GPU compute functions
+ * (`createComputePipeline`, `writeParticleToModifierBuffers`, etc.), particle systems with
+ * `simulationBackend: 'AUTO'` or `'GPU'` will run physics and modifiers on the GPU.
+ *
+ * @param factory - Object containing TSL material creators and optional GPU compute helpers.
+ *
+ * @example
+ * ```typescript
+ * import { registerTSLMaterialFactory } from '@cyberluke/three-particles';
+ * import {
+ *   createTSLParticleMaterial,
+ *   createTSLTrailMaterial,
+ *   createComputePipeline,
+ *   writeParticleToModifierBuffers,
+ *   deactivateParticleInModifierBuffers,
+ *   flushEmitQueue,
+ *   registerCurveDataLength,
+ *   encodeForceFieldsForGPU,
+ * } from '@cyberluke/three-particles/webgpu';
+ *
+ * registerTSLMaterialFactory({
+ *   createTSLParticleMaterial,
+ *   createTSLTrailMaterial,
+ *   createComputePipeline,
+ *   writeParticleToModifierBuffers,
+ *   deactivateParticleInModifierBuffers,
+ *   flushEmitQueue,
+ *   registerCurveDataLength,
+ *   encodeForceFieldsForGPU,
+ * });
+ * ```
+ */
+declare const registerTSLMaterialFactory: (factory: TSLMaterialFactory, options?: {
+    renderer?: unknown;
+}) => boolean;
+/** Throw the first fatal, named (never empty) normalization error. */
+declare const assertNamed: (cond: unknown, message: string) => void;
+/**
+ * Canonical `Vector2` input: `THREE.Vector2 | [x,y] | [u,v] | {x,y} | {u,v}`
+ * (or undefined/null => fallback). Anything else throws a labeled error.
+ */
+declare const normalizeVector2Value: (raw: unknown, fallback: [number, number], label: string) => THREE.Vector2;
+/** Canonical map slot: `null` (no map -> white dummy in the material) or a
+ *  texture object with `.image`. Anything else throws a labeled error. */
+declare const normalizeTextureValue: (raw: unknown, label: string) => THREE.Texture | null;
+/** `null` (absent) or a texture object with `.image` — nothing else. */
+declare const normalizeDepthTextureValue: (raw: unknown, label: string) => THREE.Texture | null;
+/**
+ * Background color from serialized data: `{r,g,b,a?}` object, `0x` number,
+ * `#rgb`/`#rrggbb` string, or `[r,g,b]` array -> `Vector3`.
+ */
+declare const normalizeBackgroundToVector3: (raw: unknown, label: string) => THREE.Vector3;
+/**
+ * Mapping of blending mode string identifiers to Three.js blending constants.
+ *
+ * Used for converting serialized particle system configurations (e.g., from JSON)
+ * to actual Three.js blending mode constants.
+ *
+ * @example
+ * ```typescript
+ * import { blendingMap } from '@cyberluke/three-particles';
+ *
+ * // Convert string to Three.js constant
+ * const blending = blendingMap['THREE.AdditiveBlending'];
+ * // blending === THREE.AdditiveBlending
+ * ```
+ */
+declare const blendingMap: {
+    'THREE.NoBlending': 0;
+    'THREE.NormalBlending': 1;
+    'THREE.AdditiveBlending': 2;
+    'THREE.SubtractiveBlending': 3;
+    'THREE.MultiplyBlending': 4;
+};
+/**
+ * Returns a deep copy of the default particle system configuration.
+ *
+ * This is useful when you want to start with default settings and modify specific properties
+ * without affecting the internal default configuration object.
+ *
+ * @returns A new object containing all default particle system settings
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultParticleSystemConfig, createParticleSystem } from '@cyberluke/three-particles';
+ *
+ * // Get default config and modify it
+ * const config = getDefaultParticleSystemConfig();
+ * config.emission.rateOverTime = 100;
+ * config.startColor.min = { r: 1, g: 0, b: 0 };
+ *
+ * const { instance } = createParticleSystem(config);
+ * scene.add(instance);
+ * ```
+ */
+declare const getDefaultParticleSystemConfig: () => any;
+/**
+ * Create a new particle system (GPU-only). Every per-particle slot lives
+ * on the GPU inside the 8 storage buffers that the WebGPU compute kernels
+ * read/write. The CPU only:
+ *   - merges the incoming config,
+ *   - creates the TSL material + pipeline,
+ *   - writes ~12 scalar uniforms per frame,
+ *   - dispatches [emitNode, simNode] via renderer.compute(...).
+ */
+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 CollisionPlaneConfig, CollisionPlaneMode, 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 NormalizedCollisionPlaneConfig, type NormalizedForceFieldConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, REVISION, type RandomBetweenTwoConstants, type Rectangle, type Renderer, RendererType, type Rgb, SCALAR_STRIDE, S_COLOR_A, S_COLOR_B, S_COLOR_G, S_COLOR_R, S_IS_ACTIVE, S_LIFETIME, S_ROTATION, S_SIZE, S_START_FRAME, S_START_LIFETIME, Shape, type ShapeConfig, SimulationBackend, SimulationSpace, type SoftParticlesConfig, type Sphere, type SubEmitterConfig, SubEmitterTrigger, type TextureSheetAnimation, TimeMode, type TrailConfig, type Transform, type VelocityOverLifetime, applyModifiers, assertNamed, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultMeshTexture, createDefaultParticleTexture, createParticleSystem, curveFunctionIdMap, deserializeParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isComputeCapableRenderer, isLifeTimeCurve, linearToSRGB, normalizeBackgroundToVector3, normalizeDepthTextureValue, normalizeTextureValue, normalizeVector2Value, registerTSLMaterialFactory, removeBezierCurveFunction, resolveSimulationBackend, resolveWebGPUEffectiveRendererType, rgbSRGBToLinear, sRGBToLinear, serializeParticleSystem, updateParticleSystems };