tsparticles 1.35.2 → 1.37.0

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];
@@ -17,19 +28,20 @@ export class Loader {
         }
         dom.splice(index, 1);
     }
-    static async load(tagId, options, index) {
-        let domContainer = document.getElementById(tagId);
+    static async loadOptions(params) {
+        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");
             domContainer.id = tagId;
-            document.append(domContainer);
+            (_c = document.querySelector("body")) === null || _c === void 0 ? void 0 : _c.append(domContainer);
         }
-        return Loader.set(tagId, domContainer, options, index);
-    }
-    static async set(id, domContainer, options, index) {
         const currentOptions = options instanceof Array ? itemFromArray(options, index) : options;
         const dom = Loader.dom();
-        const oldIndex = dom.findIndex((v) => v.id === id);
+        const oldIndex = dom.findIndex((v) => v.id === tagId);
         if (oldIndex >= 0) {
             const old = Loader.domItem(oldIndex);
             if (old && !old.destroyed) {
@@ -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,14 +67,18 @@ 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);
             }
         }
-        const newItem = new Container(id, currentOptions);
+        /* launch tsParticles */
+        const newItem = new Container(tagId, currentOptions);
         if (oldIndex >= 0) {
             dom.splice(oldIndex, 0, newItem);
         }
@@ -72,27 +89,123 @@ export class Loader {
         await newItem.start();
         return newItem;
     }
-    static async loadJSON(tagId, jsonUrl, index) {
+    static async loadRemoteOptions(params) {
+        const { url: jsonUrl, index } = params;
         const url = jsonUrl instanceof Array ? itemFromArray(jsonUrl, index) : jsonUrl;
+        if (!url) {
+            return;
+        }
         const response = await fetch(url);
-        if (response.ok) {
-            return Loader.load(tagId, await response.json());
+        if (!response.ok) {
+            fetchError(response.status);
+            return;
+        }
+        const data = await response.json();
+        return await Loader.loadOptions({
+            tagId: params.tagId,
+            element: params.element,
+            index,
+            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") {
+            params.tagId = tagId;
         }
         else {
-            fetchError(response.status);
+            params.options = tagId;
+        }
+        if (typeof options === "number") {
+            params.index = options !== null && options !== void 0 ? options : params.index;
+        }
+        else {
+            params.options = options !== null && options !== void 0 ? options : params.options;
+        }
+        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") {
+            params.tagId = id;
+        }
+        else {
+            params.element = id;
+        }
+        if (domContainer instanceof HTMLElement) {
+            params.element = domContainer;
+        }
+        else {
+            params.options = domContainer;
         }
+        if (typeof options === "number") {
+            params.index = options;
+        }
+        else {
+            params.options = options !== null && options !== void 0 ? options : params.options;
+        }
+        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) {
+            url = tagId;
+        }
+        else {
+            id = tagId;
+            url = jsonUrl;
+        }
+        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) {
-        const url = jsonUrl instanceof Array ? itemFromArray(jsonUrl, index) : jsonUrl;
-        const response = await fetch(url);
-        if (response.ok) {
-            const options = await response.json();
-            return Loader.set(id, domContainer, options);
+        let url, newId, newIndex, element;
+        if (id instanceof HTMLElement) {
+            element = id;
+            url = domContainer;
+            newIndex = jsonUrl;
         }
         else {
-            fetchError(response.status);
+            newId = id;
+            element = domContainer;
+            url = jsonUrl;
+            newIndex = index;
         }
+        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,14 +4,24 @@ 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;
@@ -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;
@@ -26,6 +30,7 @@ export class Particles {
     get count() {
         return this.array.length;
     }
+    /* --------- tsParticles functions - particles ----------- */
     init() {
         var _a;
         const container = this.container;
@@ -92,6 +97,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 +130,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 +143,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";