@tsparticles/engine 3.0.0-alpha.0 → 3.0.0-alpha.1

package/README.md

@@ -30,48 +30,67 @@ React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Riot.j
 
 ## Table of Contents
 
-- [Use for your website](#Do-you-want-to-use-it-on-your-website)
-  - [Library installation](#Library-installation)
-- [Official components for some of the most used frameworks](#Official-components-for-some-of-the-most-used-frameworks)
-  - [Angular](#Angular)
-  - [Inferno](#Inferno)
-  - [jQuery](#jQuery)
-  - [Preact](#Preact)
-  - [ReactJS](#ReactJS)
-  - [RiotJS](#RiotJS)
-  - [SolidJS](#SolidJS)
-  - [Svelte](#Svelte)
-  - [VueJS 2.x](#VueJS-2x)
-  - [VueJS 3.x](#VueJS-3x)
-  - [Web Components](#Web-Components)
-  - [WordPress](#WordPress)
-  - [Elementor](#Elementor)
-- [Presets](#Presets)
-  - [Big Circles](#Big-Circles)
-  - [Bubbles](#Bubbles)
-  - [Confetti](#Confetti)
-  - [Fire](#Fire)
-  - [Firefly](#Firefly)
-  - [Fireworks](#Fireworks)
-  - [Fountain](#fountain)
-  - [Links](#links)
-  - [Sea Anemone](#Sea-Anemone)
-  - [Snow](#Snow)
-  - [Stars](#Stars)
-  - [Triangles](#Triangles)
-- [Templates and Resources](#Templates-and-Resources)
-- [Demo / Generator](#Demo--Generator)
-  - [Characters as particles](#Characters-as-particles)
-  - [Mouse hover connections](#Mouse-hover-connections)
-  - [Polygon mask](#Polygon-mask)
-  - [Animated stars](#Animated-stars)
-  - [Nyan cat flying on scrolling stars](#Nyan-cat-flying-on-scrolling-stars)
-  - [Background Mask particles](#Background-Mask-particles)
-- [Video Tutorials](#Video-Tutorials)
-- [Migrating from Particles.js](#Migrating-from-Particlesjs)
-- [Plugins/Customizations](#PluginsCustomizations)
-- [Dependency Graphs](#Dependency-Graphs)
-- [Sponsors](#Sponsors)
+- [tsParticles - TypeScript Particles](#tsparticles---typescript-particles)
+- [Table of Contents](#table-of-contents)
+- [Do you want to use it on your website?](#do-you-want-to-use-it-on-your-website)
+- [**_Library installation_**](#library-installation)
+- [**_Hosting / CDN_**](#hosting--cdn)
+- [jsDelivr](#jsdelivr)
+- [cdnjs](#cdnjs)
+- [unpkg](#unpkg)
+- [**_npm_**](#npm)
+- [**_yarn_**](#yarn)
+- [**_pnpm_**](#pnpm)
+- [Import and require](#import-and-require)
+- [**_NuGet_**](#nuget)
+- [**_Usage_**](#usage)
+- [Official components for some of the most used frameworks](#official-components-for-some-of-the-most-used-frameworks)
+- [Angular](#angular)
+- [Ember](#ember)
+- [Inferno](#inferno)
+- [jQuery](#jquery)
+- [Preact](#preact)
+- [ReactJS](#reactjs)
+- [RiotJS](#riotjs)
+- [`@tsparticles/riot`](#tsparticlesriot)
+- [SolidJS](#solidjs)
+- [`@tsparticles/solid`](#tsparticlessolid)
+- [Svelte](#svelte)
+- [VueJS 2.x](#vuejs-2x)
+- [VueJS 3.x](#vuejs-3x)
+- [Web Components](#web-components)
+- [`@tsparticles/webcomponents`](#tsparticleswebcomponents)
+- [WordPress](#wordpress)
+- [`@tsparticles/wordpress`](#tsparticleswordpress)
+- [Elementor](#elementor)
+- [Presets](#presets)
+- [Big Circles](#big-circles)
+- [Bubbles](#bubbles)
+- [Confetti](#confetti)
+- [Fire](#fire)
+- [Firefly](#firefly)
+- [Fireworks](#fireworks)
+- [Fountain](#fountain)
+- [Links](#links)
+- [Sea Anemone](#sea-anemone)
+- [Snow](#snow)
+- [Stars](#stars)
+- [Triangles](#triangles)
+- [Templates and Resources](#templates-and-resources)
+- [**_Demo / Generator_**](#demo--generator)
+- [**_Video Tutorials_**](#video-tutorials)
+- [Characters as particles](#characters-as-particles)
+- [Polygon mask](#polygon-mask)
+- [Animated stars](#animated-stars)
+- [Nyan cat flying on scrolling stars](#nyan-cat-flying-on-scrolling-stars)
+- [Snow particles](#snow-particles)
+- [Background Mask particles](#background-mask-particles)
+- [**_Options_**](#options)
+- [Want to see it in action and try it?](#want-to-see-it-in-action-and-try-it)
+- [Migrating from Particles.js](#migrating-from-particlesjs)
+- [Plugins/Customizations](#pluginscustomizations)
+- [Dependency Graphs](#dependency-graphs)
+- [Huge thanks to JetBrains for the 2020-2022 Open Source Licenses!](#huge-thanks-to-jetbrains-for-the-2020-2022-open-source-licenses)
 
 ---
 
@@ -636,28 +655,7 @@ _Read more [here](https://particles.js.org/docs/modules/Core_Interfaces_IPlugin.
 
 ---
 
-## Dependency Graphs
-
-```mermaid
-flowchart TD
-
-subgraph c [Components]
-ca[Angular]
-ci[Inferno.js]
-cj[JQuery]
-cp[Preact]
-cre[React.js]
-cri[Riot.js]
-cso[Solid.js]
-csv[Svelte]
-cv2[Vue.js 2.x]
-cv3[Vue.js 3.x]
-cwc[Web Components]
-cwp[WordPress]
-end
-
-e[tsParticles Engine] --> c
-```
+## Dependency Graph
 
 ```mermaid
 flowchart LR
@@ -787,23 +785,6 @@ uw[Wobble]
 end
 
 e --> u
-
-subgraph pr [Presets]
-prbi[Big Circles]
-prbu[Bubbles]
-prc[Confetti]
-prf[Fire]
-prff[Firefly]
-prfw[Fireworks]
-prfo[Fountain]
-prl[Links]
-prsa[Sea Anemone]
-prsn[Snow]
-prst[Stars]
-prt[Triangles]
-end
-
-e --> pr
 ```
 
 ---
@@ -820,5 +801,3 @@ e --> pr
 ### Huge thanks to [JetBrains](https://www.jetbrains.com/?from=tsParticles) for the 2020-2022 Open Source Licenses!
 
 [JetBrains WebStorm](https://www.jetbrains.com/webstorm/?from=tsParticles) is used to maintain this project.
-
----

package/browser/Core/Particle.js

@@ -301,7 +301,10 @@ export class Particle {
     _loadShapeData(shapeOptions, reduceDuplicates) {
         const shapeData = shapeOptions.options[this.shape];
         if (shapeData) {
-            return deepExtend({}, itemFromSingleOrMultiple(shapeData, this.id, reduceDuplicates));
+            return deepExtend({
+                close: shapeOptions.close,
+                fill: shapeOptions.fill,
+            }, itemFromSingleOrMultiple(shapeData, this.id, reduceDuplicates));
         }
     }
 }

package/browser/Core/Particles.js

@@ -27,10 +27,14 @@ export class Particles {
     addManualParticles() {
         const container = this.container, options = container.actualOptions;
         for (const particle of options.manualParticles) {
-            this.addParticle(calcPositionFromSize({
-                size: container.canvas.size,
-                position: particle.position,
-            }), particle.options);
+            this.addParticle(particle.position
+                ? particle.position.mode === "precise"
+                    ? particle.position
+                    : calcPositionFromSize({
+                        size: container.canvas.size,
+                        position: particle.position,
+                    })
+                : undefined, particle.options);
         }
     }
     addParticle(position, overrideOptions, group, initializer) {
@@ -127,22 +131,9 @@ export class Particles {
         }
         let deleted = 0;
         for (let i = index; deleted < quantity && i < this.count; i++) {
-            const particle = this.array[i];
-            if (!particle || particle.group !== group) {
-                continue;
+            if (this._removeParticle(i--, group, override)) {
+                deleted++;
             }
-            particle.destroy(override);
-            this.array.splice(i--, 1);
-            const idx = this.zArray.indexOf(particle);
-            this.zArray.splice(idx, 1);
-            this.pool.push(particle);
-            deleted++;
-            this._engine.dispatchEvent("particleRemoved", {
-                container: this.container,
-                data: {
-                    particle,
-                },
-            });
         }
     }
     removeQuantity(quantity, group) {
@@ -259,4 +250,22 @@ export class Particles {
             return;
         }
     }
+    _removeParticle(index, group, override) {
+        const particle = this.array[index];
+        if (!particle || particle.group !== group) {
+            return false;
+        }
+        particle.destroy(override);
+        this.array.splice(index, 1);
+        const zIdx = this.zArray.indexOf(particle);
+        this.zArray.splice(zIdx, 1);
+        this.pool.push(particle);
+        this._engine.dispatchEvent("particleRemoved", {
+            container: this.container,
+            data: {
+                particle,
+            },
+        });
+        return true;
+    }
 }

package/browser/Core/Utils/EventListeners.js

@@ -21,28 +21,28 @@ export class EventListeners {
         this.container = container;
         this.canPush = true;
         this.handlers = {
-            mouseMove: (e) => this.mouseTouchMove(e),
-            touchStart: (e) => this.mouseTouchMove(e),
-            touchMove: (e) => this.mouseTouchMove(e),
-            touchEnd: () => this.mouseTouchFinish(),
-            mouseLeave: () => this.mouseTouchFinish(),
-            touchCancel: () => this.mouseTouchFinish(),
-            touchEndClick: (e) => this.mouseTouchClick(e),
-            mouseUp: (e) => this.mouseTouchClick(e),
-            mouseDown: () => this.mouseDown(),
-            visibilityChange: () => this.handleVisibilityChange(),
-            themeChange: (e) => this.handleThemeChange(e),
-            oldThemeChange: (e) => this.handleThemeChange(e),
-            resize: () => this.handleWindowResize(),
+            mouseMove: (e) => this._mouseTouchMove(e),
+            touchStart: (e) => this._mouseTouchMove(e),
+            touchMove: (e) => this._mouseTouchMove(e),
+            touchEnd: () => this._mouseTouchFinish(),
+            mouseLeave: () => this._mouseTouchFinish(),
+            touchCancel: () => this._mouseTouchFinish(),
+            touchEndClick: (e) => this._mouseTouchClick(e),
+            mouseUp: (e) => this._mouseTouchClick(e),
+            mouseDown: () => this._mouseDown(),
+            visibilityChange: () => this._handleVisibilityChange(),
+            themeChange: (e) => this._handleThemeChange(e),
+            oldThemeChange: (e) => this._handleThemeChange(e),
+            resize: () => this._handleWindowResize(),
         };
     }
     addListeners() {
-        this.manageListeners(true);
+        this._manageListeners(true);
     }
     removeListeners() {
-        this.manageListeners(false);
+        this._manageListeners(false);
     }
-    doMouseTouchClick(e) {
+    _doMouseTouchClick(e) {
         const container = this.container, options = container.actualOptions;
         if (this.canPush) {
             const mouseInteractivity = container.interactivity.mouse, mousePos = mouseInteractivity.position;
@@ -52,33 +52,32 @@ export class EventListeners {
             mouseInteractivity.clickPosition = Object.assign({}, mousePos);
             mouseInteractivity.clickTime = new Date().getTime();
             const onClick = options.interactivity.events.onClick;
-            executeOnSingleOrMultiple(onClick.mode, (mode) => this.handleClickMode(mode));
+            executeOnSingleOrMultiple(onClick.mode, (mode) => this._handleClickMode(mode));
         }
         if (e.type === "touchend") {
-            setTimeout(() => this.mouseTouchFinish(), 500);
+            setTimeout(() => this._mouseTouchFinish(), 500);
         }
     }
-    handleClickMode(mode) {
+    _handleClickMode(mode) {
         this.container.handleClickMode(mode);
     }
-    handleThemeChange(e) {
+    _handleThemeChange(e) {
         const mediaEvent = e, container = this.container, options = container.options, defaultThemes = options.defaultThemes, themeName = mediaEvent.matches ? defaultThemes.dark : defaultThemes.light, theme = options.themes.find((theme) => theme.name === themeName);
         if (theme && theme.default.auto) {
             container.loadTheme(themeName);
         }
     }
-    handleVisibilityChange() {
+    _handleVisibilityChange() {
         const container = this.container, options = container.actualOptions;
-        this.mouseTouchFinish();
+        this._mouseTouchFinish();
         if (!options.pauseOnBlur) {
             return;
         }
-        if (document === null || document === void 0 ? void 0 : document.hidden) {
-            container.pageHidden = true;
+        container.pageHidden = (document === null || document === void 0 ? void 0 : document.hidden) || false;
+        if (container.pageHidden) {
             container.pause();
         }
         else {
-            container.pageHidden = false;
             if (container.getAnimationStatus()) {
                 container.play(true);
             }
@@ -87,14 +86,14 @@ export class EventListeners {
             }
         }
     }
-    handleWindowResize() {
+    _handleWindowResize() {
         if (this.resizeTimeout) {
             clearTimeout(this.resizeTimeout);
             delete this.resizeTimeout;
         }
         this.resizeTimeout = setTimeout(async () => { var _a; return (_a = this.container.canvas) === null || _a === void 0 ? void 0 : _a.windowResize(); }, this.container.actualOptions.interactivity.events.resize.delay * 1000);
     }
-    manageListeners(add) {
+    _manageInteractivityEvents(add) {
         var _a;
         const handlers = this.handlers, container = this.container, options = container.actualOptions, detectType = options.interactivity.detectsOn;
         let mouseLeaveTmpEvent = mouseLeaveEvent;
@@ -109,20 +108,6 @@ export class EventListeners {
         else {
             container.interactivity.element = container.canvas.element;
         }
-        const mediaMatch = safeMatchMedia("(prefers-color-scheme: dark)");
-        if (mediaMatch) {
-            if (mediaMatch.addEventListener !== undefined) {
-                manageListener(mediaMatch, "change", handlers.themeChange, add);
-            }
-            else if (mediaMatch.addListener !== undefined) {
-                if (add) {
-                    mediaMatch.addListener(handlers.oldThemeChange);
-                }
-                else {
-                    mediaMatch.removeListener(handlers.oldThemeChange);
-                }
-            }
-        }
         const interactivityEl = container.interactivity.element;
         if (!interactivityEl) {
             return;
@@ -146,35 +131,65 @@ export class EventListeners {
         if (container.canvas.element) {
             container.canvas.element.style.pointerEvents = html === container.canvas.element ? "initial" : "none";
         }
-        if (options.interactivity.events.resize) {
-            if (typeof ResizeObserver !== "undefined") {
-                if (this.resizeObserver && !add) {
-                    if (container.canvas.element) {
-                        this.resizeObserver.unobserve(container.canvas.element);
-                    }
-                    this.resizeObserver.disconnect();
-                    delete this.resizeObserver;
-                }
-                else if (!this.resizeObserver && add && container.canvas.element) {
-                    this.resizeObserver = new ResizeObserver((entries) => {
-                        const entry = entries.find((e) => e.target === container.canvas.element);
-                        if (!entry) {
-                            return;
-                        }
-                        this.handleWindowResize();
-                    });
-                    this.resizeObserver.observe(container.canvas.element);
-                }
+    }
+    _manageListeners(add) {
+        this._manageMediaEvents(add);
+        this._manageInteractivityEvents(add);
+        this._manageResizeEvent(add);
+        this._manageVisibilityEvent(add);
+    }
+    _manageMediaEvents(add) {
+        const handlers = this.handlers, mediaMatch = safeMatchMedia("(prefers-color-scheme: dark)");
+        if (!mediaMatch) {
+            return;
+        }
+        if (mediaMatch.addEventListener !== undefined) {
+            manageListener(mediaMatch, "change", handlers.themeChange, add);
+            return;
+        }
+        if (mediaMatch.addListener !== undefined) {
+            if (add) {
+                mediaMatch.addListener(handlers.oldThemeChange);
             }
             else {
-                manageListener(window, resizeEvent, handlers.resize, add);
+                mediaMatch.removeListener(handlers.oldThemeChange);
+            }
+        }
+    }
+    _manageResizeEvent(add) {
+        const handlers = this.handlers, container = this.container, options = container.actualOptions;
+        if (!options.interactivity.events.resize) {
+            return;
+        }
+        if (typeof ResizeObserver === "undefined") {
+            manageListener(window, resizeEvent, handlers.resize, add);
+            return;
+        }
+        if (this.resizeObserver && !add) {
+            if (container.canvas.element) {
+                this.resizeObserver.unobserve(container.canvas.element);
             }
+            this.resizeObserver.disconnect();
+            delete this.resizeObserver;
+        }
+        else if (!this.resizeObserver && add && container.canvas.element) {
+            this.resizeObserver = new ResizeObserver((entries) => {
+                const entry = entries.find((e) => e.target === container.canvas.element);
+                if (!entry) {
+                    return;
+                }
+                this._handleWindowResize();
+            });
+            this.resizeObserver.observe(container.canvas.element);
         }
-        if (document) {
-            manageListener(document, visibilityChangeEvent, handlers.visibilityChange, add, false);
+    }
+    _manageVisibilityEvent(add) {
+        if (!document) {
+            return;
         }
+        manageListener(document, visibilityChangeEvent, this.handlers.visibilityChange, add);
     }
-    mouseDown() {
+    _mouseDown() {
         const interactivity = this.container.interactivity;
         if (interactivity) {
             const mouse = interactivity.mouse;
@@ -182,7 +197,7 @@ export class EventListeners {
             mouse.downPosition = mouse.position;
         }
     }
-    mouseTouchClick(e) {
+    _mouseTouchClick(e) {
         const container = this.container, options = container.actualOptions, mouse = container.interactivity.mouse;
         mouse.inside = true;
         let handled = false;
@@ -200,11 +215,11 @@ export class EventListeners {
             }
         }
         if (!handled) {
-            this.doMouseTouchClick(e);
+            this._doMouseTouchClick(e);
         }
         mouse.clicking = false;
     }
-    mouseTouchFinish() {
+    _mouseTouchFinish() {
         const interactivity = this.container.interactivity;
         if (!interactivity) {
             return;
@@ -217,7 +232,7 @@ export class EventListeners {
         mouse.inside = false;
         mouse.clicking = false;
     }
-    mouseTouchMove(e) {
+    _mouseTouchMove(e) {
         var _a, _b, _c, _d, _e, _f, _g;
         const container = this.container, options = container.actualOptions;
         if (!((_a = container.interactivity) === null || _a === void 0 ? void 0 : _a.element)) {

package/browser/Enums/Modes/AnimationMode.js

@@ -0,0 +1 @@
+export {};

package/browser/Options/Classes/AnimationOptions.js

@@ -31,6 +31,7 @@ export class AnimationOptions {
 export class RangedAnimationOptions extends AnimationOptions {
     constructor() {
         super();
+        this.mode = "auto";
         this.startValue = "random";
     }
     load(data) {
@@ -41,6 +42,9 @@ export class RangedAnimationOptions extends AnimationOptions {
         if (data.minimumValue !== undefined) {
             this.minimumValue = data.minimumValue;
         }
+        if (data.mode !== undefined) {
+            this.mode = data.mode;
+        }
         if (data.startValue !== undefined) {
             this.startValue = data.startValue;
         }

package/browser/Options/Classes/ManualParticle.js

@@ -1,7 +1,7 @@
 import { deepExtend } from "../../Utils/Utils";
 export class ManualParticle {
     load(data) {
-        var _a, _b;
+        var _a, _b, _c;
         if (!data) {
             return;
         }
@@ -9,6 +9,7 @@ export class ManualParticle {
             this.position = {
                 x: (_a = data.position.x) !== null && _a !== void 0 ? _a : 50,
                 y: (_b = data.position.y) !== null && _b !== void 0 ? _b : 50,
+                mode: (_c = data.position.mode) !== null && _c !== void 0 ? _c : "percent",
             };
         }
         if (data.options !== undefined) {

package/browser/Options/Classes/Particles/Shape/Shape.js

@@ -3,12 +3,20 @@ export class Shape {
     constructor() {
         this.options = {};
         this.type = "circle";
+        this.close = true;
+        this.fill = true;
     }
     load(data) {
         var _a;
         if (!data) {
             return;
         }
+        if (data.close !== undefined) {
+            this.close = data.close;
+        }
+        if (data.fill !== undefined) {
+            this.fill = data.fill;
+        }
         const options = data.options;
         if (options !== undefined) {
             for (const shape in options) {

package/browser/Utils/Utils.js

@@ -224,21 +224,41 @@ export function initParticleNumericAnimationValue(options, pxRatio) {
         maxLoops: getRangeValue(options.animation.count),
     };
     if (animationOptions.enable) {
-        res.status = "increasing";
         res.decay = 1 - getRangeValue(animationOptions.decay);
+        let autoStatus = false;
+        switch (animationOptions.mode) {
+            case "increase":
+                res.status = "increasing";
+                break;
+            case "decrease":
+                res.status = "decreasing";
+                break;
+            case "random":
+                res.status = getRandom() >= 0.5 ? "increasing" : "decreasing";
+                break;
+            case "auto":
+                autoStatus = true;
+                break;
+        }
         switch (animationOptions.startValue) {
             case "min":
                 res.value = res.min;
-                res.status = "increasing";
+                if (autoStatus) {
+                    res.status = "increasing";
+                }
                 break;
             case "random":
                 res.value = randomInRange(res);
-                res.status = getRandom() >= 0.5 ? "increasing" : "decreasing";
+                if (autoStatus) {
+                    res.status = getRandom() >= 0.5 ? "increasing" : "decreasing";
+                }
                 break;
             case "max":
             default:
                 res.value = res.max;
-                res.status = "decreasing";
+                if (autoStatus) {
+                    res.status = "decreasing";
+                }
                 break;
         }
     }

package/browser/bundle.js

@@ -18,6 +18,7 @@ export * from "./Core/Utils/Vector3d";
 export * from "./Enums/Directions/MoveDirection";
 export * from "./Enums/Directions/RotateDirection";
 export * from "./Enums/Directions/OutModeDirection";
+export * from "./Enums/Modes/AnimationMode";
 export * from "./Enums/Modes/ClickMode";
 export * from "./Enums/Modes/DivMode";
 export * from "./Enums/Modes/HoverMode";

package/browser/index.js

@@ -53,6 +53,7 @@ export * from "./Core/Utils/Vector3d";
 export * from "./Enums/Directions/MoveDirection";
 export * from "./Enums/Directions/RotateDirection";
 export * from "./Enums/Directions/OutModeDirection";
+export * from "./Enums/Modes/AnimationMode";
 export * from "./Enums/Modes/ClickMode";
 export * from "./Enums/Modes/DivMode";
 export * from "./Enums/Modes/HoverMode";

package/cjs/Core/Particle.js

@@ -304,7 +304,10 @@ class Particle {
     _loadShapeData(shapeOptions, reduceDuplicates) {
         const shapeData = shapeOptions.options[this.shape];
         if (shapeData) {
-            return (0, Utils_1.deepExtend)({}, (0, Utils_1.itemFromSingleOrMultiple)(shapeData, this.id, reduceDuplicates));
+            return (0, Utils_1.deepExtend)({
+                close: shapeOptions.close,
+                fill: shapeOptions.fill,
+            }, (0, Utils_1.itemFromSingleOrMultiple)(shapeData, this.id, reduceDuplicates));
         }
     }
 }