@tsparticles/engine 4.0.5 → 4.1.0

package/esm/Core/Engine.js

@@ -62,17 +62,17 @@ const getCanvasFromContainer = (domContainer) => {
 };
 export class Engine {
     pluginManager = new PluginManager(this);
-    _domArray = [];
-    _eventDispatcher = new EventDispatcher();
-    _initialized = false;
+    #domArray = [];
+    #eventDispatcher = new EventDispatcher();
+    #initialized = false;
     get items() {
-        return this._domArray;
+        return this.#domArray;
     }
     get version() {
-        return "4.0.5";
+        return "4.1.0";
     }
     addEventListener(type, listener) {
-        this._eventDispatcher.addEventListener(type, listener);
+        this.#eventDispatcher.addEventListener(type, listener);
     }
     checkVersion(pluginVersion) {
         if (this.version === pluginVersion) {
@@ -81,17 +81,17 @@ export class Engine {
         throw new Error(`The tsParticles version is different from the loaded plugins version. Engine version: ${this.version}. Plugin version: ${pluginVersion}`);
     }
     dispatchEvent(type, args) {
-        this._eventDispatcher.dispatchEvent(type, args);
+        this.#eventDispatcher.dispatchEvent(type, args);
     }
     async init() {
-        if (this._initialized) {
+        if (this.#initialized) {
             return;
         }
         await this.pluginManager.init();
-        this._initialized = true;
+        this.#initialized = true;
     }
     item(index) {
-        const { items } = this, item = items[index];
+        const items = this.items, item = items[index];
         if (item?.destroyed) {
             items.splice(index, removeDeleteCount);
             return;
@@ -145,6 +145,6 @@ export class Engine {
         await Promise.all(this.items.map(t => t.refresh()));
     }
     removeEventListener(type, listener) {
-        this._eventDispatcher.removeEventListener(type, listener);
+        this.#eventDispatcher.removeEventListener(type, listener);
     }
 }

package/esm/Core/Particle.js

@@ -1,11 +1,12 @@
 import { Vector, Vector3d } from "./Utils/Vectors.js";
 import { alterHsl, getHslFromAnimation } from "../Utils/ColorUtils.js";
 import { calcExactPositionOrRandomFromSize, clamp, degToRad, getParticleBaseVelocity, getParticleDirectionAngle, getRandom, getRangeValue, randomInRangeValue, setRangeValue, } from "../Utils/MathUtils.js";
-import { deepExtend, getPosition, initParticleNumericAnimationValue, isInArray, itemFromSingleOrMultiple, } from "../Utils/Utils.js";
+import { deepExtend, getPosition, isInArray, itemFromSingleOrMultiple } from "../Utils/Utils.js";
 import { defaultAngle, defaultOpacity, defaultRetryCount, defaultTransform, double, doublePI, half, identity, minZ, randomColorValue, squareExp, triple, tryCountIncrement, zIndexFactorOffset, } from "./Utils/Constants.js";
 import { EventType } from "../Enums/Types/EventType.js";
 import { MoveDirection } from "../Enums/Directions/MoveDirection.js";
 import { OutMode } from "../Enums/Modes/OutMode.js";
+import { OutModeDirection } from "../Enums/Directions/OutModeDirection.js";
 import { ParticleOutType } from "../Enums/Types/ParticleOutType.js";
 import { loadParticlesOptions } from "../Utils/OptionsUtils.js";
 function loadEffectData(effect, effectOptions, id, reduceDuplicates) {
@@ -76,24 +77,24 @@ export class Particle {
     unbreakable;
     velocity;
     zIndexFactor;
-    _cachedOpacityData = {
+    #cachedOpacityData = {
         fillOpacity: defaultOpacity,
         opacity: defaultOpacity,
         strokeOpacity: defaultOpacity,
     };
-    _cachedPosition = Vector3d.origin;
-    _cachedRotateData = { sin: 0, cos: 0 };
-    _cachedTransform = {
+    #cachedPosition = Vector3d.origin;
+    #cachedRotateData = { sin: 0, cos: 0 };
+    #cachedTransform = {
         a: 1,
         b: 0,
         c: 0,
         d: 1,
     };
-    _container;
-    _pluginManager;
+    #container;
+    #pluginManager;
     constructor(pluginManager, container) {
-        this._pluginManager = pluginManager;
-        this._container = container;
+        this.#pluginManager = pluginManager;
+        this.#container = container;
     }
     destroy(override) {
         if (this.unbreakable || this.destroyed) {
@@ -102,7 +103,7 @@ export class Particle {
         this.destroyed = true;
         this.bubble.inRange = false;
         this.slow.inRange = false;
-        const container = this._container, shapeDrawer = this.shape ? container.shapeDrawers.get(this.shape) : undefined;
+        const container = this.#container, shapeDrawer = this.shape ? container.shapeDrawers.get(this.shape) : undefined;
         shapeDrawer?.particleDestroy?.(this);
         for (const plugin of container.particleDestroyedPlugins) {
             plugin.particleDestroyed?.(this, override);
@@ -110,12 +111,12 @@ export class Particle {
         for (const updater of container.particleUpdaters) {
             updater.particleDestroyed?.(this, override);
         }
-        this._container.dispatchEvent(EventType.particleDestroyed, {
+        this.#container.dispatchEvent(EventType.particleDestroyed, {
             particle: this,
         });
     }
     draw(delta) {
-        const container = this._container, render = container.canvas.render;
+        const container = this.#container, render = container.canvas.render;
         render.drawParticlePlugins(this, delta);
         render.drawParticle(this, delta);
     }
@@ -123,50 +124,50 @@ export class Particle {
         return this.rotation + (this.pathRotation ? this.velocity.angle : defaultAngle);
     }
     getFillColor() {
-        return this._getRollColor(this.bubble.color ?? getHslFromAnimation(this.fillColor));
+        return this.#getRollColor(this.bubble.color ?? getHslFromAnimation(this.fillColor));
     }
     getMass() {
         return this.getRadius() ** squareExp * Math.PI * half;
     }
     getOpacity() {
         const zIndexOptions = this.options.zIndex, zIndexFactor = zIndexFactorOffset - this.zIndexFactor, zOpacityFactor = zIndexFactor ** zIndexOptions.opacityRate, opacity = this.bubble.opacity ?? getRangeValue(this.opacity?.value ?? defaultOpacity), fillOpacity = this.fillOpacity ?? defaultOpacity, strokeOpacity = this.strokeOpacity ?? defaultOpacity;
-        this._cachedOpacityData.fillOpacity = opacity * fillOpacity * zOpacityFactor;
-        this._cachedOpacityData.opacity = opacity * zOpacityFactor;
-        this._cachedOpacityData.strokeOpacity = opacity * strokeOpacity * zOpacityFactor;
-        return this._cachedOpacityData;
+        this.#cachedOpacityData.fillOpacity = opacity * fillOpacity * zOpacityFactor;
+        this.#cachedOpacityData.opacity = opacity * zOpacityFactor;
+        this.#cachedOpacityData.strokeOpacity = opacity * strokeOpacity * zOpacityFactor;
+        return this.#cachedOpacityData;
     }
     getPosition() {
-        this._cachedPosition.x = this.position.x + this.offset.x;
-        this._cachedPosition.y = this.position.y + this.offset.y;
-        this._cachedPosition.z = this.position.z;
-        return this._cachedPosition;
+        this.#cachedPosition.x = this.position.x + this.offset.x;
+        this.#cachedPosition.y = this.position.y + this.offset.y;
+        this.#cachedPosition.z = this.position.z;
+        return this.#cachedPosition;
     }
     getRadius() {
         return this.bubble.radius ?? this.size.value;
     }
     getRotateData() {
         const angle = this.getAngle();
-        this._cachedRotateData.sin = Math.sin(angle);
-        this._cachedRotateData.cos = Math.cos(angle);
-        return this._cachedRotateData;
+        this.#cachedRotateData.sin = Math.sin(angle);
+        this.#cachedRotateData.cos = Math.cos(angle);
+        return this.#cachedRotateData;
     }
     getStrokeColor() {
-        return this._getRollColor(this.bubble.color ?? getHslFromAnimation(this.strokeColor));
+        return this.#getRollColor(this.bubble.color ?? getHslFromAnimation(this.strokeColor));
     }
     getTransformData(externalTransform) {
         const rotateData = this.getRotateData(), rotating = this.isRotating;
-        this._cachedTransform.a = rotateData.cos * (externalTransform.a ?? defaultTransform.a);
-        this._cachedTransform.b = rotating
+        this.#cachedTransform.a = rotateData.cos * (externalTransform.a ?? defaultTransform.a);
+        this.#cachedTransform.b = rotating
             ? rotateData.sin * (externalTransform.b ?? identity)
             : (externalTransform.b ?? defaultTransform.b);
-        this._cachedTransform.c = rotating
+        this.#cachedTransform.c = rotating
             ? -rotateData.sin * (externalTransform.c ?? identity)
             : (externalTransform.c ?? defaultTransform.c);
-        this._cachedTransform.d = rotateData.cos * (externalTransform.d ?? defaultTransform.d);
-        return this._cachedTransform;
+        this.#cachedTransform.d = rotateData.cos * (externalTransform.d ?? defaultTransform.d);
+        return this.#cachedTransform;
     }
     init(id, position, overrideOptions, group) {
-        const container = this._container;
+        const container = this.#container;
         this.id = id;
         this.group = group;
         this.justWarped = false;
@@ -186,21 +187,27 @@ export class Particle {
             moveSpeed: 0,
             sizeAnimationSpeed: 0,
         };
+        this.size = {
+            value: 1,
+            max: 1,
+            min: 1,
+            enable: false,
+        };
         this.outType = ParticleOutType.normal;
         this.ignoresResizeRatio = true;
-        const pxRatio = container.retina.pixelRatio, mainOptions = container.actualOptions, particlesOptions = loadParticlesOptions(this._pluginManager, container, mainOptions.particles), reduceDuplicates = particlesOptions.reduceDuplicates, effectType = particlesOptions.effect.type, shapeType = particlesOptions.shape.type;
+        const mainOptions = container.actualOptions, particlesOptions = loadParticlesOptions(this.#pluginManager, container, mainOptions.particles), reduceDuplicates = particlesOptions.reduceDuplicates, effectType = particlesOptions.effect.type, shapeType = particlesOptions.shape.type;
         this.effect = itemFromSingleOrMultiple(effectType, this.id, reduceDuplicates);
         this.shape = itemFromSingleOrMultiple(shapeType, this.id, reduceDuplicates);
         const effectOptions = particlesOptions.effect, shapeOptions = particlesOptions.shape;
         if (overrideOptions) {
-            if (overrideOptions.effect?.type) {
+            if (overrideOptions.effect?.type && overrideOptions.effect.type !== this.effect) {
                 const overrideEffectType = overrideOptions.effect.type, effect = itemFromSingleOrMultiple(overrideEffectType, this.id, reduceDuplicates);
                 if (effect) {
                     this.effect = effect;
                     effectOptions.load(overrideOptions.effect);
                 }
             }
-            if (overrideOptions.shape?.type) {
+            if (overrideOptions.shape?.type && overrideOptions.shape.type !== this.shape) {
                 const overrideShapeType = overrideOptions.shape.type, shape = itemFromSingleOrMultiple(overrideShapeType, this.id, reduceDuplicates);
                 if (shape) {
                     this.shape = shape;
@@ -209,21 +216,20 @@ export class Particle {
             }
         }
         if (this.effect === randomColorValue) {
-            const availableEffects = [...this._container.effectDrawers.keys()];
+            const availableEffects = [...this.#container.effectDrawers.keys()];
             this.effect = availableEffects[Math.floor(getRandom() * availableEffects.length)];
         }
         if (this.shape === randomColorValue) {
-            const availableShapes = [...this._container.shapeDrawers.keys()];
+            const availableShapes = [...this.#container.shapeDrawers.keys()];
             this.shape = availableShapes[Math.floor(getRandom() * availableShapes.length)];
         }
         this.effectData = this.effect ? loadEffectData(this.effect, effectOptions, this.id, reduceDuplicates) : undefined;
         this.shapeData = this.shape ? loadShapeData(this.shape, shapeOptions, this.id, reduceDuplicates) : undefined;
         particlesOptions.load(overrideOptions);
-        const effectData = this.effectData;
+        const effectData = this.effectData, shapeData = this.shapeData;
         if (effectData) {
             particlesOptions.load(effectData.particles);
         }
-        const shapeData = this.shapeData;
         if (shapeData) {
             particlesOptions.load(shapeData.particles);
         }
@@ -231,7 +237,9 @@ export class Particle {
         this.shapeClose = shapeData?.close ?? particlesOptions.shape.close;
         this.options = particlesOptions;
         container.retina.initParticle(this);
-        this.size = initParticleNumericAnimationValue(this.options.size, pxRatio);
+        for (const updater of container.particleUpdaters) {
+            updater.preInit?.(this);
+        }
         this.bubble = {
             inRange: false,
         };
@@ -239,8 +247,8 @@ export class Particle {
             inRange: false,
             factor: 1,
         };
-        this._initPosition(position);
-        this.initialVelocity = this._calculateVelocity();
+        this.#initPosition(position);
+        this.initialVelocity = this.#calculateVelocity();
         this.velocity = this.initialVelocity.copy();
         this.zIndexFactor = this.position.z / container.zLayers;
         this.sides = 24;
@@ -271,12 +279,11 @@ export class Particle {
             plugin.particleCreated?.(this);
         }
     }
-    isInsideCanvas() {
-        const radius = this.getRadius(), canvasSize = this._container.canvas.size, position = this.position;
-        return (position.x >= -radius &&
-            position.y >= -radius &&
-            position.y <= canvasSize.height + radius &&
-            position.x <= canvasSize.width + radius);
+    isInsideCanvas(direction) {
+        return this.#getInsideCanvasResult({ direction }).inside;
+    }
+    isInsideCanvasForOutMode(outMode, direction) {
+        return this.#getInsideCanvasResult({ direction, outMode }).inside;
     }
     isShowingBack() {
         if (!this.roll) {
@@ -301,13 +308,13 @@ export class Particle {
         return !this.destroyed && !this.spawning && this.isInsideCanvas();
     }
     reset() {
-        for (const updater of this._container.particleUpdaters) {
+        for (const updater of this.#container.particleUpdaters) {
             updater.reset?.(this);
         }
     }
-    _calcPosition = (position, zIndex) => {
+    #calcPosition = (position, zIndex) => {
         let tryCount = defaultRetryCount, posVec = position ? Vector3d.create(position.x, position.y, zIndex) : undefined;
-        const container = this._container, plugins = container.particlePositionPlugins, outModes = this.options.move.outModes, radius = this.getRadius(), canvasSize = container.canvas.size, abortController = new AbortController(), { signal } = abortController;
+        const container = this.#container, plugins = container.particlePositionPlugins, outModes = this.options.move.outModes, radius = this.getRadius(), canvasSize = container.canvas.size, abortController = new AbortController(), { signal } = abortController;
         while (!signal.aborted) {
             for (const plugin of plugins) {
                 const pluginPos = plugin.particlePosition?.(posVec, this);
@@ -319,10 +326,10 @@ export class Particle {
                 size: canvasSize,
                 position: posVec,
             }), pos = Vector3d.create(exactPosition.x, exactPosition.y, zIndex);
-            this._fixHorizontal(pos, radius, outModes.left ?? outModes.default);
-            this._fixHorizontal(pos, radius, outModes.right ?? outModes.default);
-            this._fixVertical(pos, radius, outModes.top ?? outModes.default);
-            this._fixVertical(pos, radius, outModes.bottom ?? outModes.default);
+            this.#fixHorizontal(pos, radius, outModes.left ?? outModes.default);
+            this.#fixHorizontal(pos, radius, outModes.right ?? outModes.default);
+            this.#fixVertical(pos, radius, outModes.top ?? outModes.default);
+            this.#fixVertical(pos, radius, outModes.bottom ?? outModes.default);
             let isValidPosition = true;
             for (const plugin of container.particles.checkParticlePositionPlugins) {
                 isValidPosition = plugin.checkParticlePosition?.(this, pos, tryCount) ?? true;
@@ -338,8 +345,8 @@ export class Particle {
         }
         return posVec;
     };
-    _calculateVelocity = () => {
-        const baseVelocity = getParticleBaseVelocity(this.direction), res = baseVelocity.copy(), moveOptions = this.options.move;
+    #calculateVelocity = () => {
+        const moveOptions = this.options.move, baseVelocity = getParticleBaseVelocity(this.direction), res = baseVelocity.copy();
         if (moveOptions.direction === MoveDirection.inside || moveOptions.direction === MoveDirection.outside) {
             return res;
         }
@@ -355,27 +362,86 @@ export class Particle {
         }
         return res;
     };
-    _fixHorizontal = (pos, radius, outMode) => {
+    #fixHorizontal = (pos, radius, outMode) => {
         fixOutMode({
             outMode,
             checkModes: [OutMode.bounce],
             coord: pos.x,
-            maxCoord: this._container.canvas.size.width,
+            maxCoord: this.#container.canvas.size.width,
             setCb: (value) => (pos.x += value),
             radius,
         });
     };
-    _fixVertical = (pos, radius, outMode) => {
+    #fixVertical = (pos, radius, outMode) => {
         fixOutMode({
             outMode,
             checkModes: [OutMode.bounce],
             coord: pos.y,
-            maxCoord: this._container.canvas.size.height,
+            maxCoord: this.#container.canvas.size.height,
             setCb: (value) => (pos.y += value),
             radius,
         });
     };
-    _getRollColor = color => {
+    #getDefaultInsideCanvasResult = (direction, outMode) => {
+        const radius = this.getRadius(), canvasSize = this.#container.canvas.size, position = this.position, isBounce = outMode === OutMode.bounce;
+        if (direction === OutModeDirection.bottom) {
+            return {
+                inside: isBounce ? position.y + radius < canvasSize.height : position.y - radius < canvasSize.height,
+                reason: "default",
+            };
+        }
+        if (direction === OutModeDirection.left) {
+            return {
+                inside: isBounce ? position.x - radius > defaultAngle : position.x + radius > defaultAngle,
+                reason: "default",
+            };
+        }
+        if (direction === OutModeDirection.right) {
+            return {
+                inside: isBounce ? position.x + radius < canvasSize.width : position.x - radius < canvasSize.width,
+                reason: "default",
+            };
+        }
+        if (direction === OutModeDirection.top) {
+            return {
+                inside: isBounce ? position.y - radius > defaultAngle : position.y + radius > defaultAngle,
+                reason: "default",
+            };
+        }
+        return {
+            inside: position.x >= -radius &&
+                position.y >= -radius &&
+                position.y <= canvasSize.height + radius &&
+                position.x <= canvasSize.width + radius,
+            reason: "default",
+        };
+    };
+    #getInsideCanvasCallbackData = (direction, outMode) => {
+        return {
+            canvasSize: this.#container.canvas.size,
+            direction,
+            outMode,
+            particle: this,
+            radius: this.getRadius(),
+        };
+    };
+    #getInsideCanvasResult = (data) => {
+        const defaultResult = this.#getDefaultInsideCanvasResult(data.direction, data.outMode), container = this.#container, shapeDrawer = this.shape ? container.shapeDrawers.get(this.shape) : undefined, effectDrawer = this.effect ? container.effectDrawers.get(this.effect) : undefined, shapeCheck = shapeDrawer?.isInsideCanvas, effectCheck = effectDrawer?.isInsideCanvas;
+        if (!shapeCheck && !effectCheck) {
+            return defaultResult;
+        }
+        const callbackData = this.#getInsideCanvasCallbackData(data.direction, data.outMode), shapeResult = shapeCheck ? this.#normalizeInsideCanvasResult(shapeCheck(callbackData), "shape") : undefined, effectResult = effectCheck ? this.#normalizeInsideCanvasResult(effectCheck(callbackData), "effect") : undefined;
+        if (shapeResult && effectResult) {
+            const margin = Math.max(shapeResult.margin ?? defaultAngle, effectResult.margin ?? defaultAngle);
+            return {
+                inside: shapeResult.inside && effectResult.inside,
+                margin: margin > defaultAngle ? margin : undefined,
+                reason: "combined",
+            };
+        }
+        return shapeResult ?? effectResult ?? defaultResult;
+    };
+    #getRollColor = color => {
         if (!color || !this.roll || (!this.backColor && !this.roll.alter)) {
             return color;
         }
@@ -390,8 +456,8 @@ export class Particle {
         }
         return color;
     };
-    _initPosition = position => {
-        const container = this._container, zIndexValue = Math.floor(getRangeValue(this.options.zIndex.value)), initialPosition = this._calcPosition(position, clamp(zIndexValue, minZ, container.zLayers));
+    #initPosition = position => {
+        const container = this.#container, zIndexValue = Math.floor(getRangeValue(this.options.zIndex.value)), initialPosition = this.#calcPosition(position, clamp(zIndexValue, minZ, container.zLayers));
         if (!initialPosition) {
             throw new Error("a valid position cannot be found for particle");
         }
@@ -416,4 +482,17 @@ export class Particle {
         }
         this.offset = Vector.origin;
     };
+    #normalizeInsideCanvasResult = (result, reason) => {
+        if (typeof result === "boolean") {
+            return {
+                inside: result,
+                reason,
+            };
+        }
+        return {
+            inside: result.inside,
+            margin: result.margin,
+            reason: result.reason ?? reason,
+        };
+    };
 }