@tsparticles/engine 4.0.0-beta.8 → 4.0.0

package/browser/Core/Retina.js

@@ -13,9 +13,8 @@ export class Retina {
         const container = this.container, options = container.actualOptions;
         this.pixelRatio = options.detectRetina ? devicePixelRatio : defaultRatio;
         this.reduceFactor = defaultReduceFactor;
-        const ratio = this.pixelRatio, canvas = container.canvas;
-        if (canvas.element) {
-            const element = canvas.element;
+        const ratio = this.pixelRatio, canvas = container.canvas, element = canvas.domElement;
+        if (element) {
             canvas.size.width = element.offsetWidth * ratio;
             canvas.size.height = element.offsetHeight * ratio;
         }

package/browser/Core/Utils/EventListeners.js

@@ -66,7 +66,7 @@ export class EventListeners {
             manageListener(globalThis, resizeEvent, handlers.resize, add);
             return;
         }
-        const canvasEl = container.canvas.element;
+        const canvasEl = container.canvas.domElement;
         if (this._resizeObserver && !add) {
             if (canvasEl) {
                 this._resizeObserver.unobserve(canvasEl);

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

@@ -7,8 +7,6 @@ export class Fill {
     opacity;
     constructor() {
         this.enable = true;
-        this.color = new AnimatableColor();
-        this.color.value = "#fff";
         this.opacity = 1;
     }
     load(data) {

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

@@ -0,0 +1,25 @@
+import { AnimatableColor } from "../AnimatableColor.js";
+import { Fill } from "./Fill.js";
+import { Stroke } from "./Stroke.js";
+import { isNull } from "../../../Utils/TypeUtils.js";
+export class Paint {
+    color;
+    fill;
+    stroke;
+    load(data) {
+        if (isNull(data)) {
+            return;
+        }
+        if (data.color !== undefined) {
+            this.color = AnimatableColor.create(this.color, data.color);
+        }
+        if (data.fill !== undefined) {
+            this.fill ??= new Fill();
+            this.fill.load(data.fill);
+        }
+        if (data.stroke !== undefined) {
+            this.stroke ??= new Stroke();
+            this.stroke.load(data.stroke);
+        }
+    }
+}

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

@@ -1,28 +1,28 @@
 import { deepExtend, executeOnSingleOrMultiple } from "../../../Utils/Utils.js";
+import { isArray, isNull } from "../../../Utils/TypeUtils.js";
+import { AnimatableColor } from "../AnimatableColor.js";
 import { Effect } from "./Effect/Effect.js";
 import { Fill } from "./Fill.js";
 import { Move } from "./Move/Move.js";
 import { Opacity } from "./Opacity/Opacity.js";
+import { Paint } from "./Paint.js";
 import { ParticlesBounce } from "./Bounce/ParticlesBounce.js";
 import { ParticlesNumber } from "./Number/ParticlesNumber.js";
 import { Shape } from "./Shape/Shape.js";
 import { Size } from "./Size/Size.js";
-import { Stroke } from "./Stroke.js";
 import { ZIndex } from "./ZIndex/ZIndex.js";
-import { isNull } from "../../../Utils/TypeUtils.js";
 export class ParticlesOptions {
     bounce;
     effect;
-    fill;
     groups;
     move;
     number;
     opacity;
+    paint;
     palette;
     reduceDuplicates;
     shape;
     size;
-    stroke;
     zIndex;
     _container;
     _pluginManager;
@@ -31,15 +31,18 @@ export class ParticlesOptions {
         this._container = container;
         this.bounce = new ParticlesBounce();
         this.effect = new Effect();
-        this.fill = new Fill();
         this.groups = {};
         this.move = new Move();
         this.number = new ParticlesNumber();
         this.opacity = new Opacity();
+        this.paint = new Paint();
+        this.paint.color = new AnimatableColor();
+        this.paint.color.value = "#fff";
+        this.paint.fill = new Fill();
+        this.paint.fill.enable = true;
         this.reduceDuplicates = false;
         this.shape = new Shape();
         this.size = new Size();
-        this.stroke = new Stroke();
         this.zIndex = new ZIndex();
     }
     load(data) {
@@ -69,25 +72,26 @@ export class ParticlesOptions {
         this.move.load(data.move);
         this.number.load(data.number);
         this.opacity.load(data.opacity);
+        const paintToLoad = data.paint;
+        if (paintToLoad) {
+            if (isArray(paintToLoad)) {
+                this.paint = executeOnSingleOrMultiple(paintToLoad, t => {
+                    const tmp = new Paint();
+                    tmp.load(t);
+                    return tmp;
+                });
+            }
+            else if (isArray(this.paint)) {
+                this.paint = new Paint();
+                this.paint.load(paintToLoad);
+            }
+            else {
+                this.paint.load(paintToLoad);
+            }
+        }
         this.shape.load(data.shape);
         this.size.load(data.size);
         this.zIndex.load(data.zIndex);
-        const fillToLoad = data.fill;
-        if (fillToLoad) {
-            this.fill = executeOnSingleOrMultiple(fillToLoad, t => {
-                const tmp = new Fill();
-                tmp.load(t);
-                return tmp;
-            });
-        }
-        const strokeToLoad = data.stroke;
-        if (strokeToLoad) {
-            this.stroke = executeOnSingleOrMultiple(strokeToLoad, t => {
-                const tmp = new Stroke();
-                tmp.load(t);
-                return tmp;
-            });
-        }
         if (this._container) {
             for (const plugin of this._pluginManager.plugins) {
                 if (plugin.loadParticlesOptions) {
@@ -109,21 +113,40 @@ export class ParticlesOptions {
         if (!paletteData) {
             return;
         }
+        const paletteColors = paletteData.colors, defaultPaintStrokeWidth = 0, defaultPaintVariantsLength = 1, firstPaintVariantIndex = 0, defaultPalettePaintVariant = {}, colorVariants = isArray(paletteColors) ? paletteColors : [paletteColors], palettePaintVariants = colorVariants.flatMap(variant => {
+            const paletteFill = variant.fill, paletteStroke = variant.stroke, fillPart = paletteFill
+                ? {
+                    color: {
+                        value: paletteFill.value,
+                    },
+                    enable: paletteFill.enable,
+                    opacity: paletteFill.opacity,
+                }
+                : undefined;
+            if (!paletteStroke) {
+                return [
+                    {
+                        fill: fillPart,
+                    },
+                ];
+            }
+            return [
+                {
+                    fill: fillPart,
+                    stroke: {
+                        color: {
+                            value: paletteStroke.value,
+                        },
+                        opacity: paletteStroke.opacity,
+                        width: paletteStroke.width || defaultPaintStrokeWidth,
+                    },
+                },
+            ];
+        }), palettePaint = palettePaintVariants.length > defaultPaintVariantsLength
+            ? palettePaintVariants
+            : (palettePaintVariants[firstPaintVariantIndex] ?? defaultPalettePaintVariant);
         this.load({
-            fill: {
-                color: paletteData.fill
-                    ? {
-                        value: paletteData.colors,
-                    }
-                    : undefined,
-                enable: paletteData.fill,
-            },
-            stroke: paletteData.fill
-                ? undefined
-                : paletteData.colors.map(color => ({
-                    color: { value: color },
-                    width: 1,
-                })),
+            paint: palettePaint,
             blend: {
                 enable: true,
                 mode: paletteData.blendMode,

package/browser/Utils/CanvasUtils.js

@@ -88,12 +88,12 @@ export function drawShape(drawer, data) {
     if (particle.shapeClose) {
         context.closePath();
     }
-    if (stroke) {
-        context.stroke();
-    }
     if (fill) {
         context.fill();
     }
+    if (stroke) {
+        context.stroke();
+    }
 }
 export function drawShapeAfterDraw(drawer, data) {
     if (!drawer?.afterDraw) {

package/browser/Utils/LogUtils.js

@@ -1,22 +1,39 @@
 const errorPrefix = "tsParticles - Error";
-const _logger = {
-    debug: console.debug,
-    error: (message, optionalParams) => {
-        console.error(`${errorPrefix} - ${message}`, optionalParams);
+const wrap = (fn) => (...args) => {
+    fn(...args);
+}, _logger = {
+    debug: wrap(console.debug),
+    error: (message, ...optionalParams) => {
+        console.error(`${errorPrefix} - ${message}`, ...optionalParams);
     },
-    info: console.info,
-    log: console.log,
-    trace: console.trace,
-    verbose: console.log,
-    warning: console.warn,
+    info: wrap(console.info),
+    log: wrap(console.log),
+    trace: wrap(console.trace),
+    verbose: wrap(console.log),
+    warning: wrap(console.warn),
 };
 export function setLogger(logger) {
-    _logger.debug = logger.debug;
-    _logger.error = logger.error;
-    _logger.info = logger.info;
-    _logger.log = logger.log;
-    _logger.verbose = logger.verbose;
-    _logger.warning = logger.warning;
+    if (logger.debug) {
+        _logger.debug = wrap(logger.debug);
+    }
+    if (logger.error) {
+        _logger.error = wrap(logger.error);
+    }
+    if (logger.info) {
+        _logger.info = wrap(logger.info);
+    }
+    if (logger.log) {
+        _logger.log = wrap(logger.log);
+    }
+    if (logger.trace) {
+        _logger.trace = wrap(logger.trace);
+    }
+    if (logger.verbose) {
+        _logger.verbose = wrap(logger.verbose);
+    }
+    if (logger.warning) {
+        _logger.warning = wrap(logger.warning);
+    }
 }
 export function getLogger() {
     return _logger;

package/browser/Utils/Utils.js

@@ -405,6 +405,7 @@ function computeFullScreenStyle(zIndex) {
         "z-index": zIndex.toString(radix),
         top: "0",
         left: "0",
+        "pointer-events": "none",
     };
     for (const key in style) {
         const value = style[key];

package/browser/browser.js

@@ -0,0 +1,5 @@
+import { tsParticles } from "./index.js";
+const globalObject = globalThis;
+globalObject.__tsParticlesInternals = globalObject.__tsParticlesInternals ?? {};
+globalObject.tsParticles = tsParticles;
+export * from "./index.js";

package/browser/exports.js

@@ -28,6 +28,7 @@ export * from "./Options/Classes/Particles/Bounce/ParticlesBounce.js";
 export * from "./Options/Classes/Particles/Bounce/ParticlesBounceFactor.js";
 export * from "./Options/Classes/Particles/ParticlesOptions.js";
 export * from "./Options/Classes/Particles/Fill.js";
+export * from "./Options/Classes/Particles/Paint.js";
 export * from "./Options/Classes/Particles/Stroke.js";
 export * from "./Options/Classes/Particles/Move/Move.js";
 export * from "./Options/Classes/Particles/Move/MoveAngle.js";

package/browser/index.js

@@ -1,5 +1,4 @@
 import { initEngine } from "./initEngine.js";
 const tsParticles = initEngine();
-globalThis.tsParticles = tsParticles;
 export * from "./exports.js";
 export { tsParticles };

package/cjs/Core/CanvasManager.js

@@ -2,6 +2,25 @@ import { cloneStyle, getFullScreenStyle, safeMatchMedia, safeMutationObserver }
 import { defaultZoom, generatedAttribute, half } from "./Utils/Constants.js";
 import { getStyleFromRgb, rangeColorToRgb } from "../Utils/ColorUtils.js";
 import { RenderManager } from "./RenderManager.js";
+const transferredCanvases = new WeakMap(), getTransferredCanvas = (canvas) => {
+    const transferredCanvas = transferredCanvases.get(canvas);
+    if (transferredCanvas) {
+        return transferredCanvas;
+    }
+    if (typeof canvas.transferControlToOffscreen !== "function") {
+        throw new TypeError("OffscreenCanvas is required but not supported by this browser");
+    }
+    try {
+        const offscreenCanvas = canvas.transferControlToOffscreen();
+        transferredCanvases.set(canvas, offscreenCanvas);
+        return offscreenCanvas;
+    }
+    catch {
+        throw new TypeError("OffscreenCanvas transfer failed");
+    }
+}, isHtmlCanvasElement = (canvas) => {
+    return typeof HTMLCanvasElement !== "undefined" && canvas instanceof HTMLCanvasElement;
+};
 function setStyle(canvas, style, important = false) {
     if (!style) {
         return;
@@ -32,8 +51,9 @@ function setStyle(canvas, style, important = false) {
     }
 }
 export class CanvasManager {
-    element;
+    domElement;
     render;
+    renderCanvas;
     size;
     zoom = defaultZoom;
     _container;
@@ -68,9 +88,10 @@ export class CanvasManager {
     destroy() {
         this.stop();
         if (this._generated) {
-            const element = this.element;
+            const element = this.domElement;
             element?.remove();
-            this.element = undefined;
+            this.domElement = undefined;
+            this.renderCanvas = undefined;
         }
         else {
             this._resetOriginalStyle();
@@ -103,16 +124,17 @@ export class CanvasManager {
         this._initStyle();
         this.initBackground();
         this._safeMutationObserver(obs => {
-            if (!this.element || !(this.element instanceof Node)) {
+            const element = this.domElement;
+            if (!element || !(element instanceof Node)) {
                 return;
             }
-            obs.observe(this.element, { attributes: true });
+            obs.observe(element, { attributes: true });
         });
         this.initPlugins();
         this.render.init();
     }
     initBackground() {
-        const { _container } = this, options = _container.actualOptions, background = options.background, element = this.element;
+        const { _container } = this, options = _container.actualOptions, background = options.background, element = this.domElement;
         if (!element) {
             return;
         }
@@ -137,21 +159,30 @@ export class CanvasManager {
         }
     }
     loadCanvas(canvas) {
-        if (this._generated && this.element) {
-            this.element.remove();
+        if (this._generated && this.domElement) {
+            this.domElement.remove();
+        }
+        const container = this._container, domCanvas = isHtmlCanvasElement(canvas) ? canvas : undefined;
+        this.domElement = domCanvas;
+        this._generated = domCanvas ? domCanvas.dataset[generatedAttribute] === "true" : false;
+        this.renderCanvas = domCanvas ? getTransferredCanvas(domCanvas) : canvas;
+        const domElement = this.domElement;
+        if (domElement) {
+            domElement.ariaHidden = "true";
+            this._originalStyle = cloneStyle(domElement.style);
+        }
+        const standardSize = this._standardSize, renderCanvas = this.renderCanvas;
+        if (domElement) {
+            standardSize.height = domElement.offsetHeight;
+            standardSize.width = domElement.offsetWidth;
+        }
+        else {
+            standardSize.height = renderCanvas.height;
+            standardSize.width = renderCanvas.width;
         }
-        const container = this._container;
-        this._generated =
-            generatedAttribute in canvas.dataset ? canvas.dataset[generatedAttribute] === "true" : this._generated;
-        this.element = canvas;
-        this.element.ariaHidden = "true";
-        this._originalStyle = cloneStyle(this.element.style);
-        const standardSize = this._standardSize;
-        standardSize.height = canvas.offsetHeight;
-        standardSize.width = canvas.offsetWidth;
         const pxRatio = this._container.retina.pixelRatio, retinaSize = this.size;
-        canvas.height = retinaSize.height = standardSize.height * pxRatio;
-        canvas.width = retinaSize.width = standardSize.width * pxRatio;
+        renderCanvas.height = retinaSize.height = standardSize.height * pxRatio;
+        renderCanvas.width = retinaSize.width = standardSize.width * pxRatio;
         const canSupportHdrQuery = safeMatchMedia("(color-gamut: p3)");
         this.render.setContextSettings({
             alpha: true,
@@ -159,42 +190,48 @@ export class CanvasManager {
             desynchronized: true,
             willReadFrequently: false,
         });
-        this.render.setContext(this.element.getContext("2d", this.render.settings));
+        this.render.setContext(renderCanvas.getContext("2d", this.render.settings));
         this._safeMutationObserver(obs => {
             obs.disconnect();
         });
         container.retina.init();
         this.initBackground();
         this._safeMutationObserver(obs => {
-            if (!this.element || !(this.element instanceof Node)) {
+            const element = this.domElement;
+            if (!element || !(element instanceof Node)) {
                 return;
             }
-            obs.observe(this.element, { attributes: true });
+            obs.observe(element, { attributes: true });
         });
     }
     resize() {
-        if (!this.element) {
+        const element = this.domElement;
+        if (!element) {
+            return false;
+        }
+        const container = this._container, renderCanvas = this.renderCanvas;
+        if (renderCanvas === undefined) {
             return false;
         }
-        const container = this._container, currentSize = container.canvas._standardSize, newSize = {
-            width: this.element.offsetWidth,
-            height: this.element.offsetHeight,
+        const currentSize = container.canvas._standardSize, newSize = {
+            width: element.offsetWidth,
+            height: element.offsetHeight,
         }, pxRatio = container.retina.pixelRatio, retinaSize = {
             width: newSize.width * pxRatio,
             height: newSize.height * pxRatio,
         };
         if (newSize.height === currentSize.height &&
             newSize.width === currentSize.width &&
-            retinaSize.height === this.element.height &&
-            retinaSize.width === this.element.width) {
+            retinaSize.height === renderCanvas.height &&
+            retinaSize.width === renderCanvas.width) {
             return false;
         }
         const oldSize = { ...currentSize };
         currentSize.height = newSize.height;
         currentSize.width = newSize.width;
         const canvasSize = this.size;
-        this.element.width = canvasSize.width = retinaSize.width;
-        this.element.height = canvasSize.height = retinaSize.height;
+        renderCanvas.width = canvasSize.width = retinaSize.width;
+        renderCanvas.height = canvasSize.height = retinaSize.height;
         if (this._container.started) {
             container.particles.setResizeFactor({
                 width: currentSize.width / oldSize.width,
@@ -204,7 +241,7 @@ export class CanvasManager {
         return true;
     }
     setPointerEvents(type) {
-        const element = this.element;
+        const element = this.domElement;
         if (!element) {
             return;
         }
@@ -223,7 +260,7 @@ export class CanvasManager {
         this.render.stop();
     }
     async windowResize() {
-        if (!this.element || !this.resize()) {
+        if (!this.domElement || !this.resize()) {
             return;
         }
         const container = this._container, needsRefresh = container.updateActualOptions();
@@ -239,7 +276,7 @@ export class CanvasManager {
         }
     };
     _initStyle = () => {
-        const element = this.element, options = this._container.actualOptions;
+        const element = this.domElement, options = this._container.actualOptions;
         if (!element) {
             return;
         }
@@ -261,7 +298,7 @@ export class CanvasManager {
         }
     };
     _repairStyle = () => {
-        const element = this.element;
+        const element = this.domElement;
         if (!element) {
             return;
         }
@@ -272,7 +309,7 @@ export class CanvasManager {
         this.initBackground();
         const pointerEvents = this._pointerEvents;
         element.style.pointerEvents = pointerEvents;
-        element.setAttribute("pointer-events", pointerEvents);
+        element.style.setProperty("pointer-events", pointerEvents);
         this._safeMutationObserver(observer => {
             if (!(element instanceof Node)) {
                 return;
@@ -281,7 +318,7 @@ export class CanvasManager {
         });
     };
     _resetOriginalStyle = () => {
-        const element = this.element, originalStyle = this._originalStyle;
+        const element = this.domElement, originalStyle = this._originalStyle;
         if (!element || !originalStyle) {
             return;
         }
@@ -294,7 +331,7 @@ export class CanvasManager {
         callback(this._mutationObserver);
     };
     _setFullScreenStyle = () => {
-        const element = this.element;
+        const element = this.domElement;
         if (!element) {
             return;
         }

package/cjs/Core/Engine.js

@@ -20,12 +20,19 @@ async function getDataFromUrl(data) {
 const getCanvasFromContainer = (domContainer) => {
     const documentSafe = safeDocument();
     let canvasEl;
-    if (domContainer instanceof HTMLCanvasElement || domContainer.tagName.toLowerCase() === canvasTag) {
+    const isCanvas = domContainer instanceof HTMLCanvasElement || domContainer.tagName.toLowerCase() === canvasTag;
+    if (isCanvas) {
         canvasEl = domContainer;
         canvasEl.dataset[generatedAttribute] ??= generatedFalse;
+        if (canvasEl.dataset[generatedAttribute] === generatedTrue) {
+            canvasEl.style.width ||= fullPercent;
+            canvasEl.style.height ||= fullPercent;
+            canvasEl.style.pointerEvents = "none";
+            canvasEl.style.setProperty("pointer-events", "none");
+        }
     }
     else {
-        const existingCanvases = domContainer.getElementsByTagName(canvasTag), foundCanvas = existingCanvases[canvasFirstIndex];
+        const existingCanvases = domContainer.getElementsByTagName(canvasTag), foundCanvas = existingCanvases.item(canvasFirstIndex);
         if (foundCanvas) {
             canvasEl = foundCanvas;
             canvasEl.dataset[generatedAttribute] = generatedFalse;
@@ -35,9 +42,11 @@ const getCanvasFromContainer = (domContainer) => {
             canvasEl.dataset[generatedAttribute] = generatedTrue;
             domContainer.appendChild(canvasEl);
         }
+        canvasEl.style.width ||= fullPercent;
+        canvasEl.style.height ||= fullPercent;
+        canvasEl.style.pointerEvents = "none";
+        canvasEl.style.setProperty("pointer-events", "none");
     }
-    canvasEl.style.width ||= fullPercent;
-    canvasEl.style.height ||= fullPercent;
     return canvasEl;
 }, getDomContainer = (id, source) => {
     const documentSafe = safeDocument();
@@ -60,7 +69,7 @@ export class Engine {
         return this._domArray;
     }
     get version() {
-        return "4.0.0-beta.8";
+        return "4.0.0";
     }
     addEventListener(type, listener) {
         this._eventDispatcher.addEventListener(type, listener);
@@ -91,7 +100,11 @@ export class Engine {
     }
     async load(params) {
         await this.init();
-        const { Container } = await import("./Container.js"), id = params.id ?? params.element?.id ?? `tsparticles${Math.floor(getRandom() * loadRandomFactor).toString()}`, { index, url } = params, options = url ? await getDataFromUrl({ fallback: params.options, url, index }) : params.options, currentOptions = itemFromSingleOrMultiple(options, index), { items } = this, oldIndex = items.findIndex(v => v.id.description === id), newItem = new Container({
+        let domSourceElement;
+        if (typeof HTMLElement !== "undefined" && params.element instanceof HTMLElement) {
+            domSourceElement = params.element;
+        }
+        const { Container } = await import("./Container.js"), id = params.id ?? domSourceElement?.id ?? `tsparticles${Math.floor(getRandom() * loadRandomFactor).toString()}`, { index, url } = params, options = url ? await getDataFromUrl({ fallback: params.options, url, index }) : params.options, currentOptions = itemFromSingleOrMultiple(options, index), { items } = this, oldIndex = items.findIndex(v => v.id.description === id), newItem = new Container({
             dispatchCallback: (eventType, args) => {
                 this.dispatchEvent(eventType, args);
             },
@@ -118,8 +131,10 @@ export class Engine {
         else {
             items.push(newItem);
         }
-        const domContainer = getDomContainer(id, params.element), canvasEl = getCanvasFromContainer(domContainer);
-        newItem.canvas.loadCanvas(canvasEl);
+        const sourceCanvas = typeof OffscreenCanvas !== "undefined" && params.element instanceof OffscreenCanvas
+            ? params.element
+            : getCanvasFromContainer(getDomContainer(id, domSourceElement));
+        newItem.canvas.loadCanvas(sourceCanvas);
         await newItem.start();
         return newItem;
     }

package/cjs/Core/Particle.js

@@ -49,6 +49,7 @@ export class Particle {
     initialPosition;
     initialVelocity;
     isRotating;
+    justWarped;
     lastPathTime;
     misplaced;
     moveCenter;
@@ -168,6 +169,7 @@ export class Particle {
         const container = this._container;
         this.id = id;
         this.group = group;
+        this.justWarped = false;
         this.effectClose = true;
         this.shapeClose = true;
         this.pathRotation = false;
@@ -240,8 +242,6 @@ export class Particle {
         this._initPosition(position);
         this.initialVelocity = this._calculateVelocity();
         this.velocity = this.initialVelocity.copy();
-        const particles = container.particles;
-        particles.setLastZIndex(this.position.z);
         this.zIndexFactor = this.position.z / container.zLayers;
         this.sides = 24;
         let effectDrawer, shapeDrawer;
@@ -391,7 +391,7 @@ export class Particle {
         return color;
     };
     _initPosition = position => {
-        const container = this._container, zIndexValue = getRangeValue(this.options.zIndex.value), initialPosition = this._calcPosition(position, clamp(zIndexValue, minZ, container.zLayers));
+        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");
         }