tsparticles 1.35.4 → 1.37.2

package/browser/Core/Loader.js

@@ -5,10 +5,21 @@ function fetchError(statusCode) {
     console.error(`Error tsParticles - fetch status: ${statusCode}`);
     console.error("Error tsParticles - File config not found");
 }
+/**
+ * Main class for creating the [[Container]] objects
+ * @category Core
+ */
 export class Loader {
+    /**
+     * All the [[Container]] objects loaded
+     */
     static dom() {
         return tsParticlesDom;
     }
+    /**
+     * Retrieves a [[Container]] from all the objects loaded
+     * @param index the object index
+     */
     static domItem(index) {
         const dom = Loader.dom();
         const item = dom[index];
@@ -21,6 +32,7 @@ export class Loader {
         var _a, _b, _c;
         const tagId = (_a = params.tagId) !== null && _a !== void 0 ? _a : `tsparticles${Math.floor(Math.random() * 10000)}`;
         const { options, index } = params;
+        /* elements */
         let domContainer = (_b = params.element) !== null && _b !== void 0 ? _b : document.getElementById(tagId);
         if (!domContainer) {
             domContainer = document.createElement("div");
@@ -45,6 +57,7 @@ export class Loader {
         }
         else {
             const existingCanvases = domContainer.getElementsByTagName("canvas");
+            /* get existing canvas if present, otherwise a new one will be created */
             if (existingCanvases.length) {
                 canvasEl = existingCanvases[0];
                 if (!canvasEl.className) {
@@ -54,13 +67,17 @@ export class Loader {
             }
             else {
                 generatedCanvas = true;
+                /* create canvas element */
                 canvasEl = document.createElement("canvas");
                 canvasEl.className = Constants.canvasClass;
+                /* set size canvas */
                 canvasEl.style.width = "100%";
                 canvasEl.style.height = "100%";
+                /* append canvas */
                 domContainer.appendChild(canvasEl);
             }
         }
+        /* launch tsParticles */
         const newItem = new Container(tagId, currentOptions);
         if (oldIndex >= 0) {
             dom.splice(oldIndex, 0, newItem);
@@ -91,6 +108,12 @@ export class Loader {
             options: data,
         });
     }
+    /**
+     * Loads the provided options to create a [[Container]] object.
+     * @param tagId the particles container element id
+     * @param options the options object to initialize the [[Container]]
+     * @param index if an options array is provided, this will retrieve the exact index of that array
+     */
     static load(tagId, options, index) {
         const params = { index };
         if (typeof tagId === "string") {
@@ -107,6 +130,13 @@ export class Loader {
         }
         return this.loadOptions(params);
     }
+    /**
+     * Loads the provided options to create a [[Container]] object.
+     * @param id the particles container element id
+     * @param domContainer the dom container
+     * @param options the options object to initialize the [[Container]]
+     * @param index if an options array is provided, this will retrieve the exact index of that array
+     */
     static async set(id, domContainer, options, index) {
         const params = { index };
         if (typeof id === "string") {
@@ -129,6 +159,14 @@ export class Loader {
         }
         return this.loadOptions(params);
     }
+    /**
+     * Loads the provided json with a GET request. The content will be used to create a [[Container]] object.
+     * This method is async, so if you need a callback refer to JavaScript function `fetch`
+     * @param tagId the particles container element id
+     * @param jsonUrl the json path (or paths array) to use in the GET request
+     * @param index the index of the paths array, if a single path is passed this value is ignored
+     * @returns A Promise with the [[Container]] object created
+     */
     static async loadJSON(tagId, jsonUrl, index) {
         let url, id;
         if (typeof jsonUrl === "number" || jsonUrl === undefined) {
@@ -140,6 +178,15 @@ export class Loader {
         }
         return await Loader.loadRemoteOptions({ tagId: id, url, index });
     }
+    /**
+     * Loads the provided json with a GET request. The content will be used to create a [[Container]] object.
+     * This method is async, so if you need a callback refer to JavaScript function `fetch`
+     * @param id the particles container element id
+     * @param domContainer the container used to contains the particles
+     * @param jsonUrl the json path (or paths array) to use in the GET request
+     * @param index the index of the paths array, if a single path is passed this value is ignored
+     * @returns A Promise with the [[Container]] object created
+     */
     static async setJSON(id, domContainer, jsonUrl, index) {
         let url, newId, newIndex, element;
         if (id instanceof HTMLElement) {
@@ -155,6 +202,10 @@ export class Loader {
         }
         return await Loader.loadRemoteOptions({ tagId: newId, url, index: newIndex, element });
     }
+    /**
+     * Adds an additional click handler to all the loaded [[Container]] objects.
+     * @param callback the function called after the click event is fired
+     */
     static setOnClickHandler(callback) {
         const dom = Loader.dom();
         if (dom.length === 0) {

package/browser/Core/Particle/Mover.d.ts

@@ -1,6 +1,9 @@
 import type { Container } from "../Container";
 import type { Particle } from "../Particle";
 import type { IDelta } from "../Interfaces";
+/**
+ * @category Core
+ */
 export declare class Mover {
     private readonly container;
     constructor(container: Container);

package/browser/Core/Particle/Mover.js

@@ -31,6 +31,9 @@ function applyDistance(particle) {
         }
     }
 }
+/**
+ * @category Core
+ */
 export class Mover {
     constructor(container) {
         this.container = container;
@@ -40,6 +43,7 @@ export class Mover {
             return;
         }
         this.moveParticle(particle, delta);
+        /* parallax */
         this.moveParallax(particle);
     }
     moveParticle(particle, delta) {
@@ -152,12 +156,13 @@ export class Mover {
         };
         const parallaxSmooth = options.interactivity.events.onHover.parallax.smooth;
         const factor = particle.getRadius() / parallaxForce;
+        /* smaller is the particle, longer is the offset distance */
         const tmp = {
             x: (mousePos.x - canvasCenter.x) * factor,
             y: (mousePos.y - canvasCenter.y) * factor,
         };
-        particle.offset.x += (tmp.x - particle.offset.x) / parallaxSmooth;
-        particle.offset.y += (tmp.y - particle.offset.y) / parallaxSmooth;
+        particle.offset.x += (tmp.x - particle.offset.x) / parallaxSmooth; // Easing equation
+        particle.offset.y += (tmp.y - particle.offset.y) / parallaxSmooth; // Easing equation
     }
     getProximitySpeedFactor(particle) {
         const container = this.container;

package/browser/Core/Particle.d.ts

@@ -9,6 +9,10 @@ import type { IBubbleParticleData, ICoordinates, ICoordinates3d, IDelta, IHsl, I
 import { Vector3d } from "./Particle/Vector3d";
 import { IParticleRoll } from "./Interfaces/IParticleRoll";
 import { IParticleWobble } from "./Interfaces/IParticleWobble";
+/**
+ * The single particle object
+ * @category Core
+ */
 export declare class Particle implements IParticle {
     readonly id: number;
     readonly container: Container;
@@ -62,6 +66,9 @@ export declare class Particle implements IParticle {
     getFillColor(): IHsl | undefined;
     getStrokeColor(): IHsl | undefined;
     destroy(override?: boolean): void;
+    /**
+     * This method is used when the particle has lost a life and needs some value resets
+     */
     reset(): void;
     private split;
     private calcPosition;

package/browser/Core/Particle.js

@@ -14,6 +14,10 @@ const fixOutMode = (data) => {
         }
     }
 };
+/**
+ * The single particle object
+ * @category Core
+ */
 export class Particle {
     constructor(id, container, position, overrideOptions, group) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j;
@@ -66,6 +70,7 @@ export class Particle {
         this.pathDelay = getValue(this.options.move.path.delay) * 1000;
         const zIndexValue = getRangeValue(this.options.zIndex.value);
         container.retina.initParticle(this);
+        /* size */
         const sizeOptions = this.options.size, sizeRange = sizeOptions.value;
         this.size = {
             enable: sizeOptions.animation.enable,
@@ -104,15 +109,19 @@ export class Particle {
         this.bubble = {
             inRange: false,
         };
+        /* animation - velocity for speed */
         this.initialVelocity = this.calculateVelocity();
         this.velocity = this.initialVelocity.copy();
         this.moveDecay = 1 - getRangeValue(this.options.move.decay);
+        /* position */
         this.position = this.calcPosition(container, position, clamp(zIndexValue, 0, container.zLayers));
         this.initialPosition = this.position.copy();
+        /* parallax */
         this.offset = Vector.origin;
         const particles = container.particles;
         particles.needsSort = particles.needsSort || particles.lastZIndex < this.position.z;
         particles.lastZIndex = this.position.z;
+        // Scale z-index factor
         this.zIndexFactor = this.position.z / container.zLayers;
         this.sides = 24;
         let drawer = container.drawers.get(this.shape);
@@ -235,6 +244,9 @@ export class Particle {
             this.split();
         }
     }
+    /**
+     * This method is used when the particle has lost a life and needs some value resets
+     */
     reset() {
         if (this.opacity) {
             this.opacity.loops = 0;
@@ -262,6 +274,7 @@ export class Particle {
         const canvasSize = container.canvas.size;
         const pos = Vector3d.create((_a = position === null || position === void 0 ? void 0 : position.x) !== null && _a !== void 0 ? _a : Math.random() * canvasSize.width, (_b = position === null || position === void 0 ? void 0 : position.y) !== null && _b !== void 0 ? _b : Math.random() * canvasSize.height, zIndex);
         const radius = this.getRadius();
+        /* check position  - into the canvas */
         const outModes = this.options.move.outModes, fixHorizontal = (outMode) => {
             fixOutMode({
                 outMode,

package/browser/Core/Particles.d.ts

@@ -4,20 +4,30 @@ import { QuadTree } from "../Utils";
 import type { RecursivePartial } from "../Types";
 import type { IParticles } from "../Options/Interfaces/Particles/IParticles";
 import type { ICoordinates, IDelta, IMouseData, IParticle, IRgb } from "./Interfaces";
+/**
+ * Particles manager object
+ * @category Core
+ */
 export declare class Particles {
     private readonly container;
     get count(): number;
+    /**
+     * The quad tree used to search particles withing ranges
+     */
     quadTree: QuadTree;
     linksColors: Map<string, string | IRgb | undefined>;
     limit: number;
     needsSort: boolean;
     lastZIndex: number;
+    /**
+     * All the particles used in canvas
+     */
     array: Particle[];
     zArray: Particle[];
     pushing?: boolean;
     linksColor?: IRgb | string;
     grabLineColor?: IRgb | string;
-    readonly updaters: import("./Interfaces").IParticleUpdater[];
+    updaters: import("./Interfaces").IParticleUpdater[];
     private interactionManager;
     private nextId;
     private readonly freqs;
@@ -29,6 +39,9 @@ export declare class Particles {
     remove(particle: Particle, group?: string, override?: boolean): void;
     update(delta: IDelta): void;
     draw(delta: IDelta): void;
+    /**
+     * Removes all particles from the array
+     */
     clear(): void;
     push(nb: number, mouse?: IMouseData, overrideOptions?: RecursivePartial<IParticles>, group?: string): void;
     addParticle(position?: ICoordinates, overrideOptions?: RecursivePartial<IParticles>, group?: string): Particle | undefined;

package/browser/Core/Particles.js

@@ -3,6 +3,10 @@ import { getRangeValue, Plugins, Point, QuadTree, randomInRange, Rectangle, setR
 import { InteractionManager } from "./InteractionManager";
 import { ParticlesOptions } from "../Options/Classes/Particles/ParticlesOptions";
 import { Mover } from "./Particle/Mover";
+/**
+ * Particles manager object
+ * @category Core
+ */
 export class Particles {
     constructor(container) {
         this.container = container;
@@ -21,11 +25,12 @@ export class Particles {
         const canvasSize = this.container.canvas.size;
         this.linksColors = new Map();
         this.quadTree = new QuadTree(new Rectangle(-canvasSize.width / 4, -canvasSize.height / 4, (canvasSize.width * 3) / 2, (canvasSize.height * 3) / 2), 4);
-        this.updaters = Plugins.getUpdaters(container);
+        this.updaters = Plugins.getUpdaters(container, true);
     }
     get count() {
         return this.array.length;
     }
+    /* --------- tsParticles functions - particles ----------- */
     init() {
         var _a;
         const container = this.container;
@@ -35,6 +40,8 @@ export class Particles {
         this.freqs.links = new Map();
         this.freqs.triangles = new Map();
         let handled = false;
+        this.updaters = Plugins.getUpdaters(container, true);
+        this.interactionManager.init();
         for (const [, plugin] of container.plugins) {
             if (plugin.particlesInitialization !== undefined) {
                 handled = plugin.particlesInitialization();
@@ -92,6 +99,14 @@ export class Particles {
             }
         }
         for (const particle of this.array) {
+            // let d = ( dx = container.interactivity.mouse.click_pos_x - p.x ) * dx +
+            //         ( dy = container.interactivity.mouse.click_pos_y - p.y ) * dy;
+            // let f = -BANG_SIZE / d;
+            // if ( d < BANG_SIZE ) {
+            //     let t = Math.atan2( dy, dx );
+            //     p.vx = f * Math.cos(t);
+            //     p.vy = f * Math.sin(t);
+            // }
             const resizeFactor = container.canvas.resizeFactor;
             if (resizeFactor) {
                 particle.position.x *= resizeFactor.width;
@@ -117,6 +132,7 @@ export class Particles {
             this.remove(particle);
         }
         this.interactionManager.externalInteract(delta);
+        // this loop is required to be done after mouse interactions
         for (const particle of container.particles.array) {
             for (const updater of this.updaters) {
                 updater.update(particle, delta);
@@ -129,26 +145,37 @@ export class Particles {
     }
     draw(delta) {
         const container = this.container;
+        /* clear canvas */
         container.canvas.clear();
         const canvasSize = this.container.canvas.size;
         this.quadTree = new QuadTree(new Rectangle(-canvasSize.width / 4, -canvasSize.height / 4, (canvasSize.width * 3) / 2, (canvasSize.height * 3) / 2), 4);
+        /* update each particles param */
         this.update(delta);
         if (this.needsSort) {
             this.zArray.sort((a, b) => b.position.z - a.position.z || a.id - b.id);
             this.lastZIndex = this.zArray[this.zArray.length - 1].position.z;
             this.needsSort = false;
         }
+        /* draw polygon shape in debug mode */
         for (const [, plugin] of container.plugins) {
             container.canvas.drawPlugin(plugin, delta);
         }
+        /*if (container.canvas.context) {
+            this.quadTree.draw(container.canvas.context);
+        }*/
+        /* draw each particle */
         for (const p of this.zArray) {
             p.draw(delta);
         }
     }
+    /**
+     * Removes all particles from the array
+     */
     clear() {
         this.array = [];
         this.zArray = [];
     }
+    /* ---------- tsParticles functions - modes events ------------ */
     push(nb, mouse, overrideOptions, group) {
         this.pushing = true;
         for (let i = 0; i < nb; i++) {

package/browser/Core/Retina.d.ts

@@ -1,5 +1,8 @@
 import type { Container } from "./Container";
 import type { Particle } from "./Particle";
+/**
+ * @category Core
+ */
 export declare class Retina {
     private readonly container;
     reduceFactor: number;
@@ -20,6 +23,9 @@ export declare class Retina {
     maxSpeed: number;
     orbitRadius?: number;
     constructor(container: Container);
+    /**
+     * Initializes all the values needing a pixel ratio factor (sizes, widths, distances)
+     */
     init(): void;
     initParticle(particle: Particle): void;
     private handleMotionChange;

package/browser/Core/Retina.js

@@ -1,8 +1,14 @@
 import { getRangeValue, isSsr } from "../Utils";
+/**
+ * @category Core
+ */
 export class Retina {
     constructor(container) {
         this.container = container;
     }
+    /**
+     * Initializes all the values needing a pixel ratio factor (sizes, widths, distances)
+     */
     init() {
         const container = this.container;
         const options = container.actualOptions;
@@ -15,10 +21,13 @@ export class Retina {
             else {
                 const mediaQuery = matchMedia("(prefers-reduced-motion: reduce)");
                 if (mediaQuery) {
+                    // Check if the media query matches or is not available.
                     this.handleMotionChange(mediaQuery);
+                    // Ads an event listener to check for changes in the media query's value.
                     const handleChange = () => {
                         this.handleMotionChange(mediaQuery);
                         container.refresh().catch(() => {
+                            // ignore
                         });
                     };
                     if (mediaQuery.addEventListener !== undefined) {

package/browser/Enums/Directions/MoveDirection.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum MoveDirection {
     bottom = "bottom",
     bottomLeft = "bottom-left",

package/browser/Enums/Directions/MoveDirection.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var MoveDirection;
 (function (MoveDirection) {
     MoveDirection["bottom"] = "bottom";

package/browser/Enums/Directions/RotateDirection.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum RotateDirection {
     clockwise = "clockwise",
     counterClockwise = "counter-clockwise",

package/browser/Enums/Directions/RotateDirection.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var RotateDirection;
 (function (RotateDirection) {
     RotateDirection["clockwise"] = "clockwise";

package/browser/Enums/Directions/TiltDirection.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum TiltDirection {
     clockwise = "clockwise",
     counterClockwise = "counter-clockwise",

package/browser/Enums/Directions/TiltDirection.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var TiltDirection;
 (function (TiltDirection) {
     TiltDirection["clockwise"] = "clockwise";

package/browser/Enums/InteractivityDetect.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum InteractivityDetect {
     canvas = "canvas",
     parent = "parent",

package/browser/Enums/InteractivityDetect.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var InteractivityDetect;
 (function (InteractivityDetect) {
     InteractivityDetect["canvas"] = "canvas";

package/browser/Enums/Modes/ClickMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum ClickMode {
     attract = "attract",
     bubble = "bubble",

package/browser/Enums/Modes/ClickMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var ClickMode;
 (function (ClickMode) {
     ClickMode["attract"] = "attract";

package/browser/Enums/Modes/CollisionMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum CollisionMode {
     absorb = "absorb",
     bounce = "bounce",

package/browser/Enums/Modes/CollisionMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var CollisionMode;
 (function (CollisionMode) {
     CollisionMode["absorb"] = "absorb";

package/browser/Enums/Modes/DivMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum DivMode {
     bounce = "bounce",
     bubble = "bubble",

package/browser/Enums/Modes/DivMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var DivMode;
 (function (DivMode) {
     DivMode["bounce"] = "bounce";

package/browser/Enums/Modes/HoverMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum HoverMode {
     attract = "attract",
     bounce = "bounce",

package/browser/Enums/Modes/HoverMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var HoverMode;
 (function (HoverMode) {
     HoverMode["attract"] = "attract";

package/browser/Enums/Modes/OutMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum OutMode {
     bounce = "bounce",
     bounceHorizontal = "bounce-horizontal",

package/browser/Enums/Modes/OutMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var OutMode;
 (function (OutMode) {
     OutMode["bounce"] = "bounce";

package/browser/Enums/Modes/ResponsiveMode.d.ts

@@ -0,0 +1,4 @@
+export declare enum ResponsiveMode {
+    screen = "screen",
+    canvas = "canvas"
+}

package/browser/Enums/Modes/ResponsiveMode.js

@@ -0,0 +1,5 @@
+export var ResponsiveMode;
+(function (ResponsiveMode) {
+    ResponsiveMode["screen"] = "screen";
+    ResponsiveMode["canvas"] = "canvas";
+})(ResponsiveMode || (ResponsiveMode = {}));

package/browser/Enums/Modes/SizeMode.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum SizeMode {
     precise = "precise",
     percent = "percent"

package/browser/Enums/Modes/SizeMode.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var SizeMode;
 (function (SizeMode) {
     SizeMode["precise"] = "precise";

package/browser/Enums/Modes/index.d.ts

@@ -7,3 +7,4 @@ export * from "./OutMode";
 export * from "./RollMode";
 export * from "./SizeMode";
 export * from "./ThemeMode";
+export * from "./ResponsiveMode";

package/browser/Enums/Modes/index.js

@@ -7,3 +7,4 @@ export * from "./OutMode";
 export * from "./RollMode";
 export * from "./SizeMode";
 export * from "./ThemeMode";
+export * from "./ResponsiveMode";

package/browser/Enums/Types/DestroyType.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum DestroyType {
     none = "none",
     max = "max",

package/browser/Enums/Types/DestroyType.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var DestroyType;
 (function (DestroyType) {
     DestroyType["none"] = "none";

package/browser/Enums/Types/DivType.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum DivType {
     circle = "circle",
     rectangle = "rectangle"

package/browser/Enums/Types/DivType.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var DivType;
 (function (DivType) {
     DivType["circle"] = "circle";

package/browser/Enums/Types/OrbitType.d.ts

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export declare enum OrbitType {
     front = "front",
     back = "back"

package/browser/Enums/Types/OrbitType.js

@@ -1,3 +1,6 @@
+/**
+ * @category Enums
+ */
 export var OrbitType;
 (function (OrbitType) {
     OrbitType["front"] = "front";