canvasparticles-js 4.2.4 → 4.3.1

package/README.md

@@ -15,6 +15,7 @@ Creating a fun and interactive background. Colors, interaction and gravity can b
 [Implementation](#implementation)<br>
 [Class Instantiation](#class-instantiation)<br>
 [Options](#options)<br>
+[Manually creating particles](#manually-creating-particles)<br>
 [One Pager Example](#one-pager-example)
 
 ---
@@ -212,18 +213,18 @@ Your screen resolution and refresh rate will directly impact perfomance!
 
 ### `particles`
 
-| Option                         | Type      | Default    | Description                                                                                       |
-| ------------------------------ | --------- | ---------- | ------------------------------------------------------------------------------------------------- |
-| `particles.color`              | `string`  | `'black'`  | Particle and connection color. Any CSS color format.                                              |
-| `particles.ppm`                | `integer` | `100`      | Particles per million pixels. _Heavily impacts performance_                                       |
-| `particles.max`                | `integer` | `Infinity` | Maximum number of particles allowed.                                                              |
-| `particles.maxWork`            | `integer` | `Infinity` | Maximum total connection length per particle. Lower values stabilize performance but may flicker. |
-| `particles.connectDistance`    | `integer` | `150`      | Maximum distance for particle connections (px). _Heavily impacts performance_                     |
-| `particles.relSpeed`           | `float`   | `1`        | Relative particle speed multiplier.                                                               |
-| `particles.relSize`            | `float`   | `1`        | Relative particle size multiplier.                                                                |
-| `particles.rotationSpeed`      | `float`   | `2`        | Direction change speed.                                                                           |
-| `particles.regenerateOnResize` | `boolean` | `false`    | Regenerate all particles when the canvas resizes.                                                 |
-| `particles.drawLines`          | `boolean` | `true`     | Whether to draw lines between particles.                                                          |
+| Option                      | Type          | Default    | Description                                                                                              |
+| --------------------------- | ------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
+| `particles.generationType`  | `0 \| 1 \| 2` | `false`    | Auto-generate particles on initialization and when the canvas resizes. `0 = OFF`, `1 = NEW`, `2 = MATCH` |
+| `particles.color`           | `string`      | `'black'`  | Particle and connection color. Any CSS color format.                                                     |
+| `particles.ppm`             | `integer`     | `100`      | Particles per million pixels. _Heavily impacts performance_                                              |
+| `particles.max`             | `integer`     | `Infinity` | Maximum number of particles allowed.                                                                     |
+| `particles.maxWork`         | `integer`     | `Infinity` | Maximum total connection length per particle. Lower values stabilize performance but may flicker.        |
+| `particles.connectDistance` | `integer`     | `150`      | Maximum distance for particle connections (px). _Heavily impacts performance_                            |
+| `particles.relSpeed`        | `float`       | `1`        | Relative particle speed multiplier.                                                                      |
+| `particles.relSize`         | `float`       | `1`        | Relative particle size multiplier.                                                                       |
+| `particles.rotationSpeed`   | `float`       | `2`        | Direction change speed.                                                                                  |
+| `particles.drawLines`       | `boolean`     | `true`     | Whether to draw lines between particles.                                                                 |
 
 ---
 
@@ -273,13 +274,32 @@ instance.option.particles.ppm = 100
 instance.option.particles.max = 300
 ```
 
-The changes are only applied when one of the following methods is called.
+The changes are only applied when one of the following methods is called:
 
 ```js
 instance.newParticles() // Remove all particles and create the correct amount of new ones
 instance.matchParticleCount() // Add or remove some particles to match the count
 ```
 
+### Changing particle properties
+
+After updating the following options, the particles are **not automatically updated**:
+
+- `particles.relSize`
+- `particles.relSpeed`
+
+```js
+// Note: the backing field is called `option` not `options`!
+instance.option.particles.relSize = 2
+instance.option.particles.relSpeed = 3
+```
+
+The changes are only applied when the following method is called:
+
+```js
+instance.updateParticles() // Updates the particle.speed and particle.size properties without regenerating any particles
+```
+
 #### Modifying object properties
 
 **All** other options can be updated by only modifying the `option` internal field properties, with changes taking effect immediately.
@@ -297,12 +317,40 @@ instance.option.gravity.repulsive = 1
 
 To reinitialize all options, pass a new options object to the `options` setter.
 
+> Existing particles their properties will not be updated automatically. [Changing particle properties](#changing-particle-properties)
+
 ```js
 instance.options = { ... }
 ```
 
 ---
 
+## Manually creating particles
+
+```ts
+createParticle(posX?: number, posY?: number, dir?: number, speed?: number, size?: number)
+```
+
+By default `particles.ppm` and `particles.max` are used to auto-generate random particles. This might destroy manually created particles. To fix this, set `particles.generationType` to `MANUAL (0)`.
+
+```js
+const canvas = '#my-canvas'
+const options = {
+  particles: {
+    generationType: CanvasParticles.generationType.MANUAL, // = 0
+    rotationSpeed: 0,
+  },
+}
+const instance = new CanvasParticles(canvas, options).start()
+
+// Create a horizontal line of particles moving down
+for (let x = 100; x < 300; x += 4) {
+  instance.createParticle(x, 100, 0, 1, 5)
+}
+```
+
+---
+
 ## One Pager Example
 
 ```html

package/dist/index.cjs

@@ -21,14 +21,20 @@ function Mulberry32(seed) {
 // Spectral test: /demo/mulberry32.html
 const prng = Mulberry32(Math.random() * 2 ** 32).next;
 class CanvasParticles {
-    static version = "4.2.4";
+    static version = "4.3.1";
     static MAX_DT = 1000 / 50; // milliseconds between updates @ 50 FPS
     static BASE_DT = 1000 / 60; // milliseconds between updates @ 60 FPS
     /** Defines mouse interaction types with the particles */
     static interactionType = Object.freeze({
         NONE: 0, // No mouse interaction
         SHIFT: 1, // Visual displacement only
-        MOVE: 2, // Actual particle movement
+        MOVE: 2, // Actual particle movement (default)
+    });
+    /** Defines how the particles are auto-generated */
+    static generationType = Object.freeze({
+        MANUAL: 0, // Never auto-generate particles
+        NEW: 1, // Generate particles from scratch
+        MATCH: 2, // Add or remove particles to match new count (default)
     });
     /** Observes canvas elements entering or leaving the viewport to start/stop animation */
     static canvasIntersectionObserver = new IntersectionObserver((entries) => {
@@ -67,10 +73,10 @@ class CanvasParticles {
         if (value == undefined)
             return defaultValue;
         const { min = -Infinity, max = Infinity } = clamp ?? {};
-        if (isFinite(min) && value < min) {
+        if (value < min) {
             console.warn(new RangeError(`option.${name} was clamped to ${min} as ${value} is too low`));
         }
-        else if (isFinite(max) && value > max) {
+        else if (value > max) {
             console.warn(new RangeError(`option.${name} was clamped to ${max} as ${value} is too high`));
         }
         return CanvasParticles.defaultIfNaN(Math.min(Math.max(value ?? defaultValue, min), max), defaultValue);
@@ -81,7 +87,7 @@ class CanvasParticles {
     isAnimating = false;
     lastAnimationFrame = 0;
     particles = [];
-    particleCount = 0;
+    hasManualParticles = false; // set to true once @public createParticle() is used
     clientX = Infinity;
     clientY = Infinity;
     mouseX = Infinity;
@@ -168,41 +174,92 @@ class CanvasParticles {
         this.height = Math.max(height + this.option.particles.connectDist * 2, 1);
         this.offX = (width - this.width) / 2;
         this.offY = (height - this.height) / 2;
-        if (this.option.particles.regenerateOnResize || this.particles.length === 0)
-            this.newParticles();
-        else
-            this.matchParticleCount({ updateBounds: true });
+        const generationType = this.option.particles.generationType;
+        if (generationType !== CanvasParticles.generationType.MANUAL) {
+            if (generationType === CanvasParticles.generationType.NEW || this.particles.length === 0)
+                this.newParticles();
+            else if (generationType === CanvasParticles.generationType.MATCH)
+                this.matchParticleCount({ updateBounds: true });
+        }
         if (this.isAnimating)
             this.#render();
     }
     /** @private Update the target number of particles based on the current canvas size and `options.particles.ppm`, capped at `options.particles.max`. */
-    #updateParticleCount() {
+    #targetParticleCount() {
         // Amount of particles to be created
-        const particleCount = ((this.option.particles.ppm * this.width * this.height) / 1_000_000) | 0;
-        this.particleCount = Math.min(this.option.particles.max, particleCount);
-        if (!isFinite(this.particleCount))
+        let particleCount = Math.round((this.option.particles.ppm * this.width * this.height) / 1_000_000);
+        particleCount = Math.min(this.option.particles.max, particleCount);
+        if (!isFinite(particleCount))
             throw new RangeError('particleCount must be finite');
+        return particleCount | 0;
     }
     /** @public Remove existing particles and generate new ones */
     newParticles() {
-        this.#updateParticleCount();
-        this.particles = [];
-        for (let i = 0; i < this.particleCount; i++)
-            this.createParticle();
+        const particleCount = this.#targetParticleCount();
+        if (this.hasManualParticles) {
+            this.particles = this.particles.filter((particle) => particle.manual);
+            this.hasManualParticles = this.particles.length > 0;
+        }
+        else {
+            this.particles = [];
+        }
+        for (let i = 0; i < particleCount; i++)
+            this.#createParticle();
     }
     /** @public Adjust particle array length to match `options.particles.ppm` */
     matchParticleCount({ updateBounds = false } = {}) {
-        this.#updateParticleCount();
-        this.particles = this.particles.slice(0, this.particleCount);
-        if (updateBounds)
-            this.particles.forEach((particle) => this.#updateParticleBounds(particle));
-        while (this.particleCount > this.particles.length)
-            this.createParticle();
+        const particleCount = this.#targetParticleCount();
+        if (this.hasManualParticles) {
+            const pruned = [];
+            let autoCount = 0;
+            // Keep manual particles while pruning automatic particles that exceed `particleCount`
+            // Only count automatic particles towards `particledCount`
+            for (const particle of this.particles) {
+                if (autoCount >= particleCount)
+                    break;
+                if (particle.manual)
+                    autoCount++;
+                pruned.push(particle);
+            }
+            this.particles = pruned;
+        }
+        else {
+            this.particles = this.particles.slice(0, particleCount);
+        }
+        // Only necessary after resize
+        if (updateBounds) {
+            for (const particle of this.particles) {
+                this.#updateParticleBounds(particle);
+            }
+        }
+        for (let i = this.particles.length; i < particleCount; i++)
+            this.#createParticle();
+    }
+    /** @private Create a random new particle */
+    #createParticle() {
+        const posX = prng() * this.width;
+        const posY = prng() * this.height;
+        const particle = {
+            posX, // Logical position in pixels
+            posY, // Logical position in pixels
+            x: posX, // Visual position in pixels
+            y: posY, // Visual position in pixels
+            velX: 0, // Horizonal speed in pixels per update
+            velY: 0, // Vertical speed in pixels per update
+            offX: 0, // Horizontal distance from drawn to logical position in pixels
+            offY: 0, // Vertical distance from drawn to logical position in pixels
+            dir: prng() * TWO_PI, // Direction in radians
+            speed: (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
+            size: (0.5 + Math.pow(prng(), 5) * 2) * this.option.particles.relSize, // Ray in pixels of the particle
+            gridPos: { x: 1, y: 1 },
+            isVisible: false,
+            manual: false,
+        };
+        this.#updateParticleBounds(particle);
+        this.particles.push(particle);
     }
     /** @public Create a new particle with optional parameters */
     createParticle(posX, posY, dir, speed, size) {
-        posX = typeof posX === 'number' ? posX - this.offX : prng() * this.width;
-        posY = typeof posY === 'number' ? posY - this.offY : prng() * this.height;
         const particle = {
             posX, // Logical position in pixels
             posY, // Logical position in pixels
@@ -212,14 +269,16 @@ class CanvasParticles {
             velY: 0, // Vertical speed in pixels per update
             offX: 0, // Horizontal distance from drawn to logical position in pixels
             offY: 0, // Vertical distance from drawn to logical position in pixels
-            dir: dir || prng() * TWO_PI, // Direction in radians
-            speed: speed || (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
-            size: size || (0.5 + prng() ** 5 * 2) * this.option.particles.relSize, // Ray in pixels of the particle
+            dir: dir, // Direction in radians
+            speed: speed, // Velocity in pixels per update
+            size: size, // Ray in pixels of the particle
             gridPos: { x: 1, y: 1 },
             isVisible: false,
+            manual: true,
         };
         this.#updateParticleBounds(particle);
         this.particles.push(particle);
+        this.hasManualParticles = true;
     }
     /** @private Update the visible bounds of a particle */
     #updateParticleBounds(particle) {
@@ -231,14 +290,26 @@ class CanvasParticles {
             left: -particle.size,
         };
     }
+    /* @public Randomize speed and size of all particles based on current options */
+    updateParticles() {
+        const particles = this.particles;
+        const len = particles.length;
+        const relSpeed = this.option.particles.relSpeed;
+        const relSize = this.option.particles.relSize;
+        for (let i = 0; i < len; i++) {
+            const particle = particles[i];
+            particle.speed = (0.5 + prng() * 0.5) * relSpeed;
+            particle.size = (0.5 + Math.pow(prng(), 5) * 2) * relSize;
+        }
+    }
     /** @private Apply gravity forces between particles */
     #updateGravity(step) {
         const isRepulsiveEnabled = this.option.gravity.repulsive > 0;
         const isPullingEnabled = this.option.gravity.pulling > 0;
         if (!isRepulsiveEnabled && !isPullingEnabled)
             return;
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const connectDist = this.option.particles.connectDist;
         const gravRepulsiveMult = connectDist * this.option.gravity.repulsive * step;
         const gravPullingMult = connectDist * this.option.gravity.pulling * step;
@@ -285,8 +356,8 @@ class CanvasParticles {
     }
     /** @private Update positions, directions, and visibility of all particles */
     #updateParticles(step) {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const width = this.width;
         const height = this.height;
         const offX = this.offX;
@@ -380,8 +451,8 @@ class CanvasParticles {
     }
     /** @private Draw the particles on the canvas */
     #renderParticles() {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const ctx = this.ctx;
         for (let i = 0; i < len; i++) {
             const particle = particles[i];
@@ -403,8 +474,8 @@ class CanvasParticles {
     }
     /** @private Draw lines between particles if they are close enough */
     #renderConnections() {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const ctx = this.ctx;
         const maxDist = this.option.particles.connectDist;
         const maxDistSq = maxDist ** 2;
@@ -538,7 +609,7 @@ class CanvasParticles {
                 distRatio: pno('mouse.distRatio', options.mouse?.distRatio, 2 / 3, { min: 0 }),
             },
             particles: {
-                regenerateOnResize: !!options.particles?.regenerateOnResize,
+                generationType: ~~pno('particles.generationType', options.particles?.generationType, CanvasParticles.generationType.MATCH, { min: 0, max: 2 }),
                 drawLines: !!(options.particles?.drawLines ?? true),
                 color: options.particles?.color ?? 'black',
                 ppm: ~~pno('particles.ppm', options.particles?.ppm, 100),

package/dist/index.d.ts

@@ -11,6 +11,12 @@ export default class CanvasParticles {
         SHIFT: 1;
         MOVE: 2;
     }>;
+    /** Defines how the particles are auto-generated */
+    static readonly generationType: Readonly<{
+        MANUAL: 0;
+        NEW: 1;
+        MATCH: 2;
+    }>;
     /** Observes canvas elements entering or leaving the viewport to start/stop animation */
     static readonly canvasIntersectionObserver: IntersectionObserver;
     static readonly canvasResizeObserver: ResizeObserver;
@@ -23,7 +29,7 @@ export default class CanvasParticles {
     isAnimating: boolean;
     private lastAnimationFrame;
     particles: Particle[];
-    particleCount: number;
+    hasManualParticles: boolean;
     private clientX;
     private clientY;
     mouseX: number;
@@ -54,7 +60,8 @@ export default class CanvasParticles {
         updateBounds?: boolean;
     }): void;
     /** @public Create a new particle with optional parameters */
-    createParticle(posX?: number, posY?: number, dir?: number, speed?: number, size?: number): void;
+    createParticle(posX: number, posY: number, dir: number, speed: number, size: number): void;
+    updateParticles(): void;
     /** @public Start the particle animation if it was not running before */
     start({ auto }?: {
         auto?: boolean;

package/dist/index.mjs

@@ -19,14 +19,20 @@ function Mulberry32(seed) {
 // Spectral test: /demo/mulberry32.html
 const prng = Mulberry32(Math.random() * 2 ** 32).next;
 class CanvasParticles {
-    static version = "4.2.4";
+    static version = "4.3.1";
     static MAX_DT = 1000 / 50; // milliseconds between updates @ 50 FPS
     static BASE_DT = 1000 / 60; // milliseconds between updates @ 60 FPS
     /** Defines mouse interaction types with the particles */
     static interactionType = Object.freeze({
         NONE: 0, // No mouse interaction
         SHIFT: 1, // Visual displacement only
-        MOVE: 2, // Actual particle movement
+        MOVE: 2, // Actual particle movement (default)
+    });
+    /** Defines how the particles are auto-generated */
+    static generationType = Object.freeze({
+        MANUAL: 0, // Never auto-generate particles
+        NEW: 1, // Generate particles from scratch
+        MATCH: 2, // Add or remove particles to match new count (default)
     });
     /** Observes canvas elements entering or leaving the viewport to start/stop animation */
     static canvasIntersectionObserver = new IntersectionObserver((entries) => {
@@ -65,10 +71,10 @@ class CanvasParticles {
         if (value == undefined)
             return defaultValue;
         const { min = -Infinity, max = Infinity } = clamp ?? {};
-        if (isFinite(min) && value < min) {
+        if (value < min) {
             console.warn(new RangeError(`option.${name} was clamped to ${min} as ${value} is too low`));
         }
-        else if (isFinite(max) && value > max) {
+        else if (value > max) {
             console.warn(new RangeError(`option.${name} was clamped to ${max} as ${value} is too high`));
         }
         return CanvasParticles.defaultIfNaN(Math.min(Math.max(value ?? defaultValue, min), max), defaultValue);
@@ -79,7 +85,7 @@ class CanvasParticles {
     isAnimating = false;
     lastAnimationFrame = 0;
     particles = [];
-    particleCount = 0;
+    hasManualParticles = false; // set to true once @public createParticle() is used
     clientX = Infinity;
     clientY = Infinity;
     mouseX = Infinity;
@@ -166,41 +172,92 @@ class CanvasParticles {
         this.height = Math.max(height + this.option.particles.connectDist * 2, 1);
         this.offX = (width - this.width) / 2;
         this.offY = (height - this.height) / 2;
-        if (this.option.particles.regenerateOnResize || this.particles.length === 0)
-            this.newParticles();
-        else
-            this.matchParticleCount({ updateBounds: true });
+        const generationType = this.option.particles.generationType;
+        if (generationType !== CanvasParticles.generationType.MANUAL) {
+            if (generationType === CanvasParticles.generationType.NEW || this.particles.length === 0)
+                this.newParticles();
+            else if (generationType === CanvasParticles.generationType.MATCH)
+                this.matchParticleCount({ updateBounds: true });
+        }
         if (this.isAnimating)
             this.#render();
     }
     /** @private Update the target number of particles based on the current canvas size and `options.particles.ppm`, capped at `options.particles.max`. */
-    #updateParticleCount() {
+    #targetParticleCount() {
         // Amount of particles to be created
-        const particleCount = ((this.option.particles.ppm * this.width * this.height) / 1_000_000) | 0;
-        this.particleCount = Math.min(this.option.particles.max, particleCount);
-        if (!isFinite(this.particleCount))
+        let particleCount = Math.round((this.option.particles.ppm * this.width * this.height) / 1_000_000);
+        particleCount = Math.min(this.option.particles.max, particleCount);
+        if (!isFinite(particleCount))
             throw new RangeError('particleCount must be finite');
+        return particleCount | 0;
     }
     /** @public Remove existing particles and generate new ones */
     newParticles() {
-        this.#updateParticleCount();
-        this.particles = [];
-        for (let i = 0; i < this.particleCount; i++)
-            this.createParticle();
+        const particleCount = this.#targetParticleCount();
+        if (this.hasManualParticles) {
+            this.particles = this.particles.filter((particle) => particle.manual);
+            this.hasManualParticles = this.particles.length > 0;
+        }
+        else {
+            this.particles = [];
+        }
+        for (let i = 0; i < particleCount; i++)
+            this.#createParticle();
     }
     /** @public Adjust particle array length to match `options.particles.ppm` */
     matchParticleCount({ updateBounds = false } = {}) {
-        this.#updateParticleCount();
-        this.particles = this.particles.slice(0, this.particleCount);
-        if (updateBounds)
-            this.particles.forEach((particle) => this.#updateParticleBounds(particle));
-        while (this.particleCount > this.particles.length)
-            this.createParticle();
+        const particleCount = this.#targetParticleCount();
+        if (this.hasManualParticles) {
+            const pruned = [];
+            let autoCount = 0;
+            // Keep manual particles while pruning automatic particles that exceed `particleCount`
+            // Only count automatic particles towards `particledCount`
+            for (const particle of this.particles) {
+                if (autoCount >= particleCount)
+                    break;
+                if (particle.manual)
+                    autoCount++;
+                pruned.push(particle);
+            }
+            this.particles = pruned;
+        }
+        else {
+            this.particles = this.particles.slice(0, particleCount);
+        }
+        // Only necessary after resize
+        if (updateBounds) {
+            for (const particle of this.particles) {
+                this.#updateParticleBounds(particle);
+            }
+        }
+        for (let i = this.particles.length; i < particleCount; i++)
+            this.#createParticle();
+    }
+    /** @private Create a random new particle */
+    #createParticle() {
+        const posX = prng() * this.width;
+        const posY = prng() * this.height;
+        const particle = {
+            posX, // Logical position in pixels
+            posY, // Logical position in pixels
+            x: posX, // Visual position in pixels
+            y: posY, // Visual position in pixels
+            velX: 0, // Horizonal speed in pixels per update
+            velY: 0, // Vertical speed in pixels per update
+            offX: 0, // Horizontal distance from drawn to logical position in pixels
+            offY: 0, // Vertical distance from drawn to logical position in pixels
+            dir: prng() * TWO_PI, // Direction in radians
+            speed: (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
+            size: (0.5 + Math.pow(prng(), 5) * 2) * this.option.particles.relSize, // Ray in pixels of the particle
+            gridPos: { x: 1, y: 1 },
+            isVisible: false,
+            manual: false,
+        };
+        this.#updateParticleBounds(particle);
+        this.particles.push(particle);
     }
     /** @public Create a new particle with optional parameters */
     createParticle(posX, posY, dir, speed, size) {
-        posX = typeof posX === 'number' ? posX - this.offX : prng() * this.width;
-        posY = typeof posY === 'number' ? posY - this.offY : prng() * this.height;
         const particle = {
             posX, // Logical position in pixels
             posY, // Logical position in pixels
@@ -210,14 +267,16 @@ class CanvasParticles {
             velY: 0, // Vertical speed in pixels per update
             offX: 0, // Horizontal distance from drawn to logical position in pixels
             offY: 0, // Vertical distance from drawn to logical position in pixels
-            dir: dir || prng() * TWO_PI, // Direction in radians
-            speed: speed || (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
-            size: size || (0.5 + prng() ** 5 * 2) * this.option.particles.relSize, // Ray in pixels of the particle
+            dir: dir, // Direction in radians
+            speed: speed, // Velocity in pixels per update
+            size: size, // Ray in pixels of the particle
             gridPos: { x: 1, y: 1 },
             isVisible: false,
+            manual: true,
         };
         this.#updateParticleBounds(particle);
         this.particles.push(particle);
+        this.hasManualParticles = true;
     }
     /** @private Update the visible bounds of a particle */
     #updateParticleBounds(particle) {
@@ -229,14 +288,26 @@ class CanvasParticles {
             left: -particle.size,
         };
     }
+    /* @public Randomize speed and size of all particles based on current options */
+    updateParticles() {
+        const particles = this.particles;
+        const len = particles.length;
+        const relSpeed = this.option.particles.relSpeed;
+        const relSize = this.option.particles.relSize;
+        for (let i = 0; i < len; i++) {
+            const particle = particles[i];
+            particle.speed = (0.5 + prng() * 0.5) * relSpeed;
+            particle.size = (0.5 + Math.pow(prng(), 5) * 2) * relSize;
+        }
+    }
     /** @private Apply gravity forces between particles */
     #updateGravity(step) {
         const isRepulsiveEnabled = this.option.gravity.repulsive > 0;
         const isPullingEnabled = this.option.gravity.pulling > 0;
         if (!isRepulsiveEnabled && !isPullingEnabled)
             return;
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const connectDist = this.option.particles.connectDist;
         const gravRepulsiveMult = connectDist * this.option.gravity.repulsive * step;
         const gravPullingMult = connectDist * this.option.gravity.pulling * step;
@@ -283,8 +354,8 @@ class CanvasParticles {
     }
     /** @private Update positions, directions, and visibility of all particles */
     #updateParticles(step) {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const width = this.width;
         const height = this.height;
         const offX = this.offX;
@@ -378,8 +449,8 @@ class CanvasParticles {
     }
     /** @private Draw the particles on the canvas */
     #renderParticles() {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const ctx = this.ctx;
         for (let i = 0; i < len; i++) {
             const particle = particles[i];
@@ -401,8 +472,8 @@ class CanvasParticles {
     }
     /** @private Draw lines between particles if they are close enough */
     #renderConnections() {
-        const len = this.particleCount;
         const particles = this.particles;
+        const len = particles.length;
         const ctx = this.ctx;
         const maxDist = this.option.particles.connectDist;
         const maxDistSq = maxDist ** 2;
@@ -536,7 +607,7 @@ class CanvasParticles {
                 distRatio: pno('mouse.distRatio', options.mouse?.distRatio, 2 / 3, { min: 0 }),
             },
             particles: {
-                regenerateOnResize: !!options.particles?.regenerateOnResize,
+                generationType: ~~pno('particles.generationType', options.particles?.generationType, CanvasParticles.generationType.MATCH, { min: 0, max: 2 }),
                 drawLines: !!(options.particles?.drawLines ?? true),
                 color: options.particles?.color ?? 'black',
                 ppm: ~~pno('particles.ppm', options.particles?.ppm, 100),

package/dist/index.umd.js

@@ -1 +1 @@
-!function(t,i){"object"==typeof exports&&"undefined"!=typeof module?module.exports=i():"function"==typeof define&&define.amd?define(i):(t="undefined"!=typeof globalThis?globalThis:t||self).CanvasParticles=i()}(this,function(){"use strict";const t=2*Math.PI;const i=function(t){let i=t>>>0;return{next(){let t=i+1831565813|0;return i=t,t=Math.imul(t^t>>>15,1|t),t^=t+Math.imul(t^t>>>7,61|t),((t^t>>>14)>>>0)/4294967296}}}(Math.random()*2**32).next;class e{static version="4.2.4";static MAX_DT=20;static BASE_DT=1e3/60;static interactionType=Object.freeze({NONE:0,SHIFT:1,MOVE:2});static canvasIntersectionObserver=new IntersectionObserver(t=>{for(let i=0;i<t.length;i++){const e=t[i],s=e.target,n=s.instance;if(!n.options?.animation)return;(s.inViewbox=e.isIntersecting)?n.options.animation?.startOnEnter&&n.start({auto:!0}):n.options.animation?.stopOnLeave&&n.stop({auto:!0,clear:!1})}},{rootMargin:"-1px"});static canvasResizeObserver=new ResizeObserver(t=>{for(let i=0;i<t.length;i++){t[i].target.instance.updateCanvasRect()}for(let i=0;i<t.length;i++){t[i].target.instance.resizeCanvas()}});static defaultIfNaN=(t,i)=>isNaN(+t)?i:+t;static parseNumericOption=(t,i,s,n)=>{if(null==i)return s;const{min:o=-1/0,max:a=1/0}=n??{};return isFinite(o)&&i<o?console.warn(new RangeError(`option.${t} was clamped to ${o} as ${i} is too low`)):isFinite(a)&&i>a&&console.warn(new RangeError(`option.${t} was clamped to ${a} as ${i} is too high`)),e.defaultIfNaN(Math.min(Math.max(i??s,o),a),s)};canvas;ctx;enableAnimating=!1;isAnimating=!1;lastAnimationFrame=0;particles=[];particleCount=0;clientX=1/0;clientY=1/0;mouseX=1/0;mouseY=1/0;width;height;offX;offY;option;color;constructor(t,i={}){let s;if(t instanceof HTMLCanvasElement)s=t;else{if("string"!=typeof t)throw new TypeError("selector is not a string and neither a HTMLCanvasElement itself");if(s=document.querySelector(t),!(s instanceof HTMLCanvasElement))throw new Error("selector does not point to a canvas")}this.canvas=s,this.canvas.instance=this,this.canvas.inViewbox=!0;const n=this.canvas.getContext("2d");if(!n)throw new Error("failed to get 2D context from canvas");this.ctx=n,this.options=i,e.canvasIntersectionObserver.observe(this.canvas),e.canvasResizeObserver.observe(this.canvas),this.resizeCanvas=this.resizeCanvas.bind(this),this.handleMouseMove=this.handleMouseMove.bind(this),this.handleScroll=this.handleScroll.bind(this),this.updateCanvasRect(),this.resizeCanvas(),window.addEventListener("mousemove",this.handleMouseMove,{passive:!0}),window.addEventListener("scroll",this.handleScroll,{passive:!0})}updateCanvasRect(){const{top:t,left:i,width:e,height:s}=this.canvas.getBoundingClientRect();this.canvas.rect={top:t,left:i,width:e,height:s}}handleMouseMove(t){this.enableAnimating&&(this.clientX=t.clientX,this.clientY=t.clientY,this.isAnimating&&this.updateMousePos())}handleScroll(){this.enableAnimating&&(this.updateCanvasRect(),this.isAnimating&&this.updateMousePos())}updateMousePos(){const{top:t,left:i}=this.canvas.rect;this.mouseX=this.clientX-i,this.mouseY=this.clientY-t}resizeCanvas(){const t=this.canvas.width=this.canvas.rect.width,i=this.canvas.height=this.canvas.rect.height;this.mouseX=1/0,this.mouseY=1/0,this.width=Math.max(t+2*this.option.particles.connectDist,1),this.height=Math.max(i+2*this.option.particles.connectDist,1),this.offX=(t-this.width)/2,this.offY=(i-this.height)/2,this.option.particles.regenerateOnResize||0===this.particles.length?this.newParticles():this.matchParticleCount({updateBounds:!0}),this.isAnimating&&this.#t()}#i(){const t=this.option.particles.ppm*this.width*this.height/1e6|0;if(this.particleCount=Math.min(this.option.particles.max,t),!isFinite(this.particleCount))throw new RangeError("particleCount must be finite")}newParticles(){this.#i(),this.particles=[];for(let t=0;t<this.particleCount;t++)this.createParticle()}matchParticleCount({updateBounds:t=!1}={}){for(this.#i(),this.particles=this.particles.slice(0,this.particleCount),t&&this.particles.forEach(t=>this.#e(t));this.particleCount>this.particles.length;)this.createParticle()}createParticle(e,s,n,o,a){const r={posX:e="number"==typeof e?e-this.offX:i()*this.width,posY:s="number"==typeof s?s-this.offY:i()*this.height,x:e,y:s,velX:0,velY:0,offX:0,offY:0,dir:n||i()*t,speed:o||(.5+.5*i())*this.option.particles.relSpeed,size:a||(.5+i()**5*2)*this.option.particles.relSize,gridPos:{x:1,y:1},isVisible:!1};this.#e(r),this.particles.push(r)}#e(t){t.bounds={top:-t.size,right:this.canvas.width+t.size,bottom:this.canvas.height+t.size,left:-t.size}}#s(t){const i=this.option.gravity.repulsive>0,e=this.option.gravity.pulling>0;if(!i&&!e)return;const s=this.particleCount,n=this.particles,o=this.option.particles.connectDist,a=o*this.option.gravity.repulsive*t,r=o*this.option.gravity.pulling*t,c=(o/2)**2,h=o**2/256;for(let t=0;t<s;t++){const i=n[t];for(let o=t+1;o<s;o++){const t=n[o],s=i.posX-t.posX,l=i.posY-t.posY,p=s*s+l*l;if(p>=c&&!e)continue;let u,d,m;u=Math.atan2(-l,-s),d=1/(p+h);const f=Math.cos(u),v=Math.sin(u);if(p<c){m=d*a;const e=f*m,s=v*m;i.velX-=e,i.velY-=s,t.velX+=e,t.velY+=s}if(!e)continue;m=d*r;const g=f*m,y=v*m;i.velX+=g,i.velY+=y,t.velX-=g,t.velY-=y}}}#n(i){const s=this.particleCount,n=this.particles,o=this.width,a=this.height,r=this.offX,c=this.offY,h=this.mouseX,l=this.mouseY,p=this.option.particles.rotationSpeed*i,u=this.option.gravity.friction,d=this.option.mouse.connectDist,m=this.option.mouse.distRatio,f=this.option.mouse.interactionType===e.interactionType.NONE,v=this.option.mouse.interactionType===e.interactionType.MOVE,g=1-Math.pow(.75,i);for(let e=0;e<s;e++){const s=n[e];s.dir+=2*(Math.random()-.5)*p*i,s.dir%=t;const y=Math.sin(s.dir)*s.speed,x=Math.cos(s.dir)*s.speed;s.posX+=(y+s.velX)*i,s.posY+=(x+s.velY)*i,s.posX%=o,s.posX<0&&(s.posX+=o),s.posY%=a,s.posY<0&&(s.posY+=a),s.velX*=Math.pow(u,i),s.velY*=Math.pow(u,i);const b=s.posX+r-h,M=s.posY+c-l;if(!f){const t=d/Math.hypot(b,M);m<t?(s.offX+=(t*b-b-s.offX)*g,s.offY+=(t*M-M-s.offY)*g):(s.offX-=s.offX*g,s.offY-=s.offY*g)}s.x=s.posX+s.offX,s.y=s.posY+s.offY,v&&(s.posX=s.x,s.posY=s.y),s.x+=r,s.y+=c,this.#o(s),s.isVisible=1===s.gridPos.x&&1===s.gridPos.y}}#o(t){t.gridPos.x=+(t.x>=t.bounds.left)+ +(t.x>t.bounds.right),t.gridPos.y=+(t.y>=t.bounds.top)+ +(t.y>t.bounds.bottom)}#a(t,i){return!(!t.isVisible&&!i.isVisible)||!(t.gridPos.x===i.gridPos.x&&1!==t.gridPos.x||t.gridPos.y===i.gridPos.y&&1!==t.gridPos.y)}#r(){const i=this.particleCount,e=this.particles,s=this.ctx;for(let n=0;n<i;n++){const i=e[n];i.isVisible&&(i.size>1?(s.beginPath(),s.arc(i.x,i.y,i.size,0,t),s.fill(),s.closePath()):s.fillRect(i.x-i.size,i.y-i.size,2*i.size,2*i.size))}}#c(){const t=this.particleCount,i=this.particles,e=this.ctx,s=this.option.particles.connectDist,n=s**2,o=(s/2)**2,a=s>=Math.min(this.canvas.width,this.canvas.height),r=n*this.option.particles.maxWork,c=this.color.alpha,h=this.color.alpha*s,l=[];for(let s=0;s<t;s++){const p=i[s];let u=0;for(let d=s+1;d<t;d++){const t=i[d];if(!a&&!this.#a(p,t))continue;const s=p.x-t.x,m=p.y-t.y,f=s*s+m*m;if(!(f>n)&&(f>o?(e.globalAlpha=h/Math.sqrt(f)-c,e.beginPath(),e.moveTo(p.x,p.y),e.lineTo(t.x,t.y),e.stroke()):l.push([p.x,p.y,t.x,t.y]),(u+=f)>=r))break}}if(l.length){e.globalAlpha=c,e.beginPath();for(let t=0;t<l.length;t++){const i=l[t];e.moveTo(i[0],i[1]),e.lineTo(i[2],i[3])}e.stroke()}}#t(){this.ctx.clearRect(0,0,this.canvas.width,this.canvas.height),this.ctx.globalAlpha=this.color.alpha,this.ctx.fillStyle=this.color.hex,this.ctx.strokeStyle=this.color.hex,this.ctx.lineWidth=1,this.#r(),this.options.particles.drawLines&&this.#c()}#h(){if(!this.isAnimating)return;requestAnimationFrame(()=>this.#h());const t=performance.now(),i=Math.min(t-this.lastAnimationFrame,e.MAX_DT)/e.BASE_DT;this.#s(i),this.#n(i),this.#t(),this.lastAnimationFrame=t}start({auto:t=!1}={}){return this.isAnimating||t&&!this.enableAnimating||(this.enableAnimating=!0,this.isAnimating=!0,this.updateCanvasRect(),requestAnimationFrame(()=>this.#h())),!this.canvas.inViewbox&&this.option.animation.startOnEnter&&(this.isAnimating=!1),this}stop({auto:t=!1,clear:i=!0}={}){return t||(this.enableAnimating=!1),this.isAnimating=!1,!1!==i&&this.ctx.clearRect(0,0,this.canvas.width,this.canvas.height),!0}destroy(){this.stop(),e.canvasIntersectionObserver.unobserve(this.canvas),e.canvasResizeObserver.unobserve(this.canvas),window.removeEventListener("mousemove",this.handleMouseMove),window.removeEventListener("scroll",this.handleScroll),this.canvas?.remove(),Object.keys(this).forEach(t=>delete this[t])}set options(t){const i=e.parseNumericOption;this.option={background:t.background??!1,animation:{startOnEnter:!!(t.animation?.startOnEnter??1),stopOnLeave:!!(t.animation?.stopOnLeave??1)},mouse:{interactionType:~~i("mouse.interactionType",t.mouse?.interactionType,e.interactionType.MOVE,{min:0,max:2}),connectDistMult:i("mouse.connectDistMult",t.mouse?.connectDistMult,2/3,{min:0}),connectDist:1,distRatio:i("mouse.distRatio",t.mouse?.distRatio,2/3,{min:0})},particles:{regenerateOnResize:!!t.particles?.regenerateOnResize,drawLines:!!(t.particles?.drawLines??1),color:t.particles?.color??"black",ppm:~~i("particles.ppm",t.particles?.ppm,100),max:Math.round(i("particles.max",t.particles?.max,1/0,{min:0})),maxWork:Math.round(i("particles.maxWork",t.particles?.maxWork,1/0,{min:0})),connectDist:~~i("particles.connectDistance",t.particles?.connectDistance,150,{min:1}),relSpeed:i("particles.relSpeed",t.particles?.relSpeed,1,{min:0}),relSize:i("particles.relSize",t.particles?.relSize,1,{min:0}),rotationSpeed:i("particles.rotationSpeed",t.particles?.rotationSpeed,2,{min:0})/100},gravity:{repulsive:i("gravity.repulsive",t.gravity?.repulsive,0,{min:0}),pulling:i("gravity.pulling",t.gravity?.pulling,0,{min:0}),friction:i("gravity.friction",t.gravity?.friction,.8,{min:0,max:1})}},this.setBackground(this.option.background),this.setMouseConnectDistMult(this.option.mouse.connectDistMult),this.setParticleColor(this.option.particles.color)}get options(){return this.option}setBackground(t){if(t){if("string"!=typeof t)throw new TypeError("background is not a string");this.canvas.style.background=this.option.background=t}}setMouseConnectDistMult(t){const i=e.parseNumericOption("mouse.connectDistMult",t,2/3,{min:0});this.option.mouse.connectDist=this.option.particles.connectDist*i}setParticleColor(t){if(this.ctx.fillStyle=t,"#"===String(this.ctx.fillStyle)[0])this.color={hex:String(this.ctx.fillStyle),alpha:1};else{let t=String(this.ctx.fillStyle).split(",").at(-1);t=t?.slice(1,-1)??"1",this.ctx.fillStyle=String(this.ctx.fillStyle).split(",").slice(0,-1).join(",")+", 1)",this.color={hex:String(this.ctx.fillStyle),alpha:isNaN(+t)?1:+t}}}}return e});
+!function(t,i){"object"==typeof exports&&"undefined"!=typeof module?module.exports=i():"function"==typeof define&&define.amd?define(i):(t="undefined"!=typeof globalThis?globalThis:t||self).CanvasParticles=i()}(this,function(){"use strict";const t=2*Math.PI;const i=function(t){let i=t>>>0;return{next(){let t=i+1831565813|0;return i=t,t=Math.imul(t^t>>>15,1|t),t^=t+Math.imul(t^t>>>7,61|t),((t^t>>>14)>>>0)/4294967296}}}(Math.random()*2**32).next;class e{static version="4.3.1";static MAX_DT=20;static BASE_DT=1e3/60;static interactionType=Object.freeze({NONE:0,SHIFT:1,MOVE:2});static generationType=Object.freeze({MANUAL:0,NEW:1,MATCH:2});static canvasIntersectionObserver=new IntersectionObserver(t=>{for(let i=0;i<t.length;i++){const e=t[i],s=e.target,n=s.instance;if(!n.options?.animation)return;(s.inViewbox=e.isIntersecting)?n.options.animation?.startOnEnter&&n.start({auto:!0}):n.options.animation?.stopOnLeave&&n.stop({auto:!0,clear:!1})}},{rootMargin:"-1px"});static canvasResizeObserver=new ResizeObserver(t=>{for(let i=0;i<t.length;i++){t[i].target.instance.updateCanvasRect()}for(let i=0;i<t.length;i++){t[i].target.instance.resizeCanvas()}});static defaultIfNaN=(t,i)=>isNaN(+t)?i:+t;static parseNumericOption=(t,i,s,n)=>{if(null==i)return s;const{min:o=-1/0,max:a=1/0}=n??{};return i<o?console.warn(new RangeError(`option.${t} was clamped to ${o} as ${i} is too low`)):i>a&&console.warn(new RangeError(`option.${t} was clamped to ${a} as ${i} is too high`)),e.defaultIfNaN(Math.min(Math.max(i??s,o),a),s)};canvas;ctx;enableAnimating=!1;isAnimating=!1;lastAnimationFrame=0;particles=[];hasManualParticles=!1;clientX=1/0;clientY=1/0;mouseX=1/0;mouseY=1/0;width;height;offX;offY;option;color;constructor(t,i={}){let s;if(t instanceof HTMLCanvasElement)s=t;else{if("string"!=typeof t)throw new TypeError("selector is not a string and neither a HTMLCanvasElement itself");if(s=document.querySelector(t),!(s instanceof HTMLCanvasElement))throw new Error("selector does not point to a canvas")}this.canvas=s,this.canvas.instance=this,this.canvas.inViewbox=!0;const n=this.canvas.getContext("2d");if(!n)throw new Error("failed to get 2D context from canvas");this.ctx=n,this.options=i,e.canvasIntersectionObserver.observe(this.canvas),e.canvasResizeObserver.observe(this.canvas),this.resizeCanvas=this.resizeCanvas.bind(this),this.handleMouseMove=this.handleMouseMove.bind(this),this.handleScroll=this.handleScroll.bind(this),this.updateCanvasRect(),this.resizeCanvas(),window.addEventListener("mousemove",this.handleMouseMove,{passive:!0}),window.addEventListener("scroll",this.handleScroll,{passive:!0})}updateCanvasRect(){const{top:t,left:i,width:e,height:s}=this.canvas.getBoundingClientRect();this.canvas.rect={top:t,left:i,width:e,height:s}}handleMouseMove(t){this.enableAnimating&&(this.clientX=t.clientX,this.clientY=t.clientY,this.isAnimating&&this.updateMousePos())}handleScroll(){this.enableAnimating&&(this.updateCanvasRect(),this.isAnimating&&this.updateMousePos())}updateMousePos(){const{top:t,left:i}=this.canvas.rect;this.mouseX=this.clientX-i,this.mouseY=this.clientY-t}resizeCanvas(){const t=this.canvas.width=this.canvas.rect.width,i=this.canvas.height=this.canvas.rect.height;this.mouseX=1/0,this.mouseY=1/0,this.width=Math.max(t+2*this.option.particles.connectDist,1),this.height=Math.max(i+2*this.option.particles.connectDist,1),this.offX=(t-this.width)/2,this.offY=(i-this.height)/2;const s=this.option.particles.generationType;s!==e.generationType.MANUAL&&(s===e.generationType.NEW||0===this.particles.length?this.newParticles():s===e.generationType.MATCH&&this.matchParticleCount({updateBounds:!0})),this.isAnimating&&this.#t()}#i(){let t=Math.round(this.option.particles.ppm*this.width*this.height/1e6);if(t=Math.min(this.option.particles.max,t),!isFinite(t))throw new RangeError("particleCount must be finite");return 0|t}newParticles(){const t=this.#i();this.hasManualParticles?(this.particles=this.particles.filter(t=>t.manual),this.hasManualParticles=this.particles.length>0):this.particles=[];for(let i=0;i<t;i++)this.#e()}matchParticleCount({updateBounds:t=!1}={}){const i=this.#i();if(this.hasManualParticles){const t=[];let e=0;for(const s of this.particles){if(e>=i)break;s.manual&&e++,t.push(s)}this.particles=t}else this.particles=this.particles.slice(0,i);if(t)for(const t of this.particles)this.#s(t);for(let t=this.particles.length;t<i;t++)this.#e()}#e(){const e=i()*this.width,s=i()*this.height,n={posX:e,posY:s,x:e,y:s,velX:0,velY:0,offX:0,offY:0,dir:i()*t,speed:(.5+.5*i())*this.option.particles.relSpeed,size:(.5+2*Math.pow(i(),5))*this.option.particles.relSize,gridPos:{x:1,y:1},isVisible:!1,manual:!1};this.#s(n),this.particles.push(n)}createParticle(t,i,e,s,n){const o={posX:t,posY:i,x:t,y:i,velX:0,velY:0,offX:0,offY:0,dir:e,speed:s,size:n,gridPos:{x:1,y:1},isVisible:!1,manual:!0};this.#s(o),this.particles.push(o),this.hasManualParticles=!0}#s(t){t.bounds={top:-t.size,right:this.canvas.width+t.size,bottom:this.canvas.height+t.size,left:-t.size}}updateParticles(){const t=this.particles,e=t.length,s=this.option.particles.relSpeed,n=this.option.particles.relSize;for(let o=0;o<e;o++){const e=t[o];e.speed=(.5+.5*i())*s,e.size=(.5+2*Math.pow(i(),5))*n}}#n(t){const i=this.option.gravity.repulsive>0,e=this.option.gravity.pulling>0;if(!i&&!e)return;const s=this.particles,n=s.length,o=this.option.particles.connectDist,a=o*this.option.gravity.repulsive*t,r=o*this.option.gravity.pulling*t,c=(o/2)**2,l=o**2/256;for(let t=0;t<n;t++){const i=s[t];for(let o=t+1;o<n;o++){const t=s[o],n=i.posX-t.posX,h=i.posY-t.posY,p=n*n+h*h;if(p>=c&&!e)continue;let u,d,m;u=Math.atan2(-h,-n),d=1/(p+l);const f=Math.cos(u),g=Math.sin(u);if(p<c){m=d*a;const e=f*m,s=g*m;i.velX-=e,i.velY-=s,t.velX+=e,t.velY+=s}if(!e)continue;m=d*r;const v=f*m,y=g*m;i.velX+=v,i.velY+=y,t.velX-=v,t.velY-=y}}}#o(i){const s=this.particles,n=s.length,o=this.width,a=this.height,r=this.offX,c=this.offY,l=this.mouseX,h=this.mouseY,p=this.option.particles.rotationSpeed*i,u=this.option.gravity.friction,d=this.option.mouse.connectDist,m=this.option.mouse.distRatio,f=this.option.mouse.interactionType===e.interactionType.NONE,g=this.option.mouse.interactionType===e.interactionType.MOVE,v=1-Math.pow(.75,i);for(let e=0;e<n;e++){const n=s[e];n.dir+=2*(Math.random()-.5)*p*i,n.dir%=t;const y=Math.sin(n.dir)*n.speed,x=Math.cos(n.dir)*n.speed;n.posX+=(y+n.velX)*i,n.posY+=(x+n.velY)*i,n.posX%=o,n.posX<0&&(n.posX+=o),n.posY%=a,n.posY<0&&(n.posY+=a),n.velX*=Math.pow(u,i),n.velY*=Math.pow(u,i);const M=n.posX+r-l,b=n.posY+c-h;if(!f){const t=d/Math.hypot(M,b);m<t?(n.offX+=(t*M-M-n.offX)*v,n.offY+=(t*b-b-n.offY)*v):(n.offX-=n.offX*v,n.offY-=n.offY*v)}n.x=n.posX+n.offX,n.y=n.posY+n.offY,g&&(n.posX=n.x,n.posY=n.y),n.x+=r,n.y+=c,this.#a(n),n.isVisible=1===n.gridPos.x&&1===n.gridPos.y}}#a(t){t.gridPos.x=+(t.x>=t.bounds.left)+ +(t.x>t.bounds.right),t.gridPos.y=+(t.y>=t.bounds.top)+ +(t.y>t.bounds.bottom)}#r(t,i){return!(!t.isVisible&&!i.isVisible)||!(t.gridPos.x===i.gridPos.x&&1!==t.gridPos.x||t.gridPos.y===i.gridPos.y&&1!==t.gridPos.y)}#c(){const i=this.particles,e=i.length,s=this.ctx;for(let n=0;n<e;n++){const e=i[n];e.isVisible&&(e.size>1?(s.beginPath(),s.arc(e.x,e.y,e.size,0,t),s.fill(),s.closePath()):s.fillRect(e.x-e.size,e.y-e.size,2*e.size,2*e.size))}}#l(){const t=this.particles,i=t.length,e=this.ctx,s=this.option.particles.connectDist,n=s**2,o=(s/2)**2,a=s>=Math.min(this.canvas.width,this.canvas.height),r=n*this.option.particles.maxWork,c=this.color.alpha,l=this.color.alpha*s,h=[];for(let s=0;s<i;s++){const p=t[s];let u=0;for(let d=s+1;d<i;d++){const i=t[d];if(!a&&!this.#r(p,i))continue;const s=p.x-i.x,m=p.y-i.y,f=s*s+m*m;if(!(f>n)&&(f>o?(e.globalAlpha=l/Math.sqrt(f)-c,e.beginPath(),e.moveTo(p.x,p.y),e.lineTo(i.x,i.y),e.stroke()):h.push([p.x,p.y,i.x,i.y]),(u+=f)>=r))break}}if(h.length){e.globalAlpha=c,e.beginPath();for(let t=0;t<h.length;t++){const i=h[t];e.moveTo(i[0],i[1]),e.lineTo(i[2],i[3])}e.stroke()}}#t(){this.ctx.clearRect(0,0,this.canvas.width,this.canvas.height),this.ctx.globalAlpha=this.color.alpha,this.ctx.fillStyle=this.color.hex,this.ctx.strokeStyle=this.color.hex,this.ctx.lineWidth=1,this.#c(),this.options.particles.drawLines&&this.#l()}#h(){if(!this.isAnimating)return;requestAnimationFrame(()=>this.#h());const t=performance.now(),i=Math.min(t-this.lastAnimationFrame,e.MAX_DT)/e.BASE_DT;this.#n(i),this.#o(i),this.#t(),this.lastAnimationFrame=t}start({auto:t=!1}={}){return this.isAnimating||t&&!this.enableAnimating||(this.enableAnimating=!0,this.isAnimating=!0,this.updateCanvasRect(),requestAnimationFrame(()=>this.#h())),!this.canvas.inViewbox&&this.option.animation.startOnEnter&&(this.isAnimating=!1),this}stop({auto:t=!1,clear:i=!0}={}){return t||(this.enableAnimating=!1),this.isAnimating=!1,!1!==i&&this.ctx.clearRect(0,0,this.canvas.width,this.canvas.height),!0}destroy(){this.stop(),e.canvasIntersectionObserver.unobserve(this.canvas),e.canvasResizeObserver.unobserve(this.canvas),window.removeEventListener("mousemove",this.handleMouseMove),window.removeEventListener("scroll",this.handleScroll),this.canvas?.remove(),Object.keys(this).forEach(t=>delete this[t])}set options(t){const i=e.parseNumericOption;this.option={background:t.background??!1,animation:{startOnEnter:!!(t.animation?.startOnEnter??1),stopOnLeave:!!(t.animation?.stopOnLeave??1)},mouse:{interactionType:~~i("mouse.interactionType",t.mouse?.interactionType,e.interactionType.MOVE,{min:0,max:2}),connectDistMult:i("mouse.connectDistMult",t.mouse?.connectDistMult,2/3,{min:0}),connectDist:1,distRatio:i("mouse.distRatio",t.mouse?.distRatio,2/3,{min:0})},particles:{generationType:~~i("particles.generationType",t.particles?.generationType,e.generationType.MATCH,{min:0,max:2}),drawLines:!!(t.particles?.drawLines??1),color:t.particles?.color??"black",ppm:~~i("particles.ppm",t.particles?.ppm,100),max:Math.round(i("particles.max",t.particles?.max,1/0,{min:0})),maxWork:Math.round(i("particles.maxWork",t.particles?.maxWork,1/0,{min:0})),connectDist:~~i("particles.connectDistance",t.particles?.connectDistance,150,{min:1}),relSpeed:i("particles.relSpeed",t.particles?.relSpeed,1,{min:0}),relSize:i("particles.relSize",t.particles?.relSize,1,{min:0}),rotationSpeed:i("particles.rotationSpeed",t.particles?.rotationSpeed,2,{min:0})/100},gravity:{repulsive:i("gravity.repulsive",t.gravity?.repulsive,0,{min:0}),pulling:i("gravity.pulling",t.gravity?.pulling,0,{min:0}),friction:i("gravity.friction",t.gravity?.friction,.8,{min:0,max:1})}},this.setBackground(this.option.background),this.setMouseConnectDistMult(this.option.mouse.connectDistMult),this.setParticleColor(this.option.particles.color)}get options(){return this.option}setBackground(t){if(t){if("string"!=typeof t)throw new TypeError("background is not a string");this.canvas.style.background=this.option.background=t}}setMouseConnectDistMult(t){const i=e.parseNumericOption("mouse.connectDistMult",t,2/3,{min:0});this.option.mouse.connectDist=this.option.particles.connectDist*i}setParticleColor(t){if(this.ctx.fillStyle=t,"#"===String(this.ctx.fillStyle)[0])this.color={hex:String(this.ctx.fillStyle),alpha:1};else{let t=String(this.ctx.fillStyle).split(",").at(-1);t=t?.slice(1,-1)??"1",this.ctx.fillStyle=String(this.ctx.fillStyle).split(",").slice(0,-1).join(",")+", 1)",this.color={hex:String(this.ctx.fillStyle),alpha:isNaN(+t)?1:+t}}}}return e});

package/dist/types/index.d.ts

@@ -27,6 +27,7 @@ export interface Particle {
     bounds: ParticleBounds;
     gridPos: ParticleGridPos;
     isVisible: boolean;
+    manual: boolean;
 }
 export interface ParticleBounds {
     top: number;

package/dist/types/options.d.ts

@@ -5,13 +5,13 @@ export interface CanvasParticlesOptions {
         stopOnLeave: boolean;
     };
     mouse: {
-        interactionType: number;
+        interactionType: 0 | 1 | 2;
         connectDistMult: number;
         connectDist: number;
         distRatio: number;
     };
     particles: {
-        regenerateOnResize: boolean;
+        generationType: 0 | 1 | 2;
         drawLines: boolean;
         color: string | CanvasGradient | CanvasPattern;
         ppm: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvasparticles-js",
-  "version": "4.2.4",
+  "version": "4.3.1",
   "description": "In an HTML canvas, a bunch of interactive particles connected with lines when they approach each other.",
   "author": "Khoeckman",
   "license": "MIT",
@@ -29,10 +29,11 @@
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^24.9.2",
-    "prettier": "^3.6.2",
-    "rollup": "^4.52.5",
-    "rollup-plugin-delete": "^3.0.1",
+    "@types/node": "^24.10.4",
+    "pnpm": "^10.27.0",
+    "prettier": "^3.7.4",
+    "rollup": "^4.54.0",
+    "rollup-plugin-delete": "^3.0.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3"
   },

package/src/index.ts

@@ -38,7 +38,14 @@ export default class CanvasParticles {
   static readonly interactionType = Object.freeze({
     NONE: 0, // No mouse interaction
     SHIFT: 1, // Visual displacement only
-    MOVE: 2, // Actual particle movement
+    MOVE: 2, // Actual particle movement (default)
+  })
+
+  /** Defines how the particles are auto-generated */
+  static readonly generationType = Object.freeze({
+    MANUAL: 0, // Never auto-generate particles
+    NEW: 1, // Generate particles from scratch
+    MATCH: 2, // Add or remove particles to match new count (default)
   })
 
   /** Observes canvas elements entering or leaving the viewport to start/stop animation */
@@ -93,9 +100,9 @@ export default class CanvasParticles {
 
     const { min = -Infinity, max = Infinity } = clamp ?? {}
 
-    if (isFinite(min) && value < min) {
+    if (value < min) {
       console.warn(new RangeError(`option.${name} was clamped to ${min} as ${value} is too low`))
-    } else if (isFinite(max) && value > max) {
+    } else if (value > max) {
       console.warn(new RangeError(`option.${name} was clamped to ${max} as ${value} is too high`))
     }
 
@@ -110,8 +117,7 @@ export default class CanvasParticles {
   private lastAnimationFrame: number = 0
 
   particles: Particle[] = []
-  particleCount: number = 0
-
+  hasManualParticles = false // set to true once @public createParticle() is used
   private clientX: number = Infinity
   private clientY: number = Infinity
   mouseX: number = Infinity
@@ -210,42 +216,74 @@ export default class CanvasParticles {
     this.offX = (width - this.width) / 2
     this.offY = (height - this.height) / 2
 
-    if (this.option.particles.regenerateOnResize || this.particles.length === 0) this.newParticles()
-    else this.matchParticleCount({ updateBounds: true })
+    const generationType = this.option.particles.generationType
+
+    if (generationType !== CanvasParticles.generationType.MANUAL) {
+      if (generationType === CanvasParticles.generationType.NEW || this.particles.length === 0) this.newParticles()
+      else if (generationType === CanvasParticles.generationType.MATCH) this.matchParticleCount({ updateBounds: true })
+    }
 
     if (this.isAnimating) this.#render()
   }
 
   /** @private Update the target number of particles based on the current canvas size and `options.particles.ppm`, capped at `options.particles.max`. */
-  #updateParticleCount() {
+  #targetParticleCount(): number {
     // Amount of particles to be created
-    const particleCount = ((this.option.particles.ppm * this.width * this.height) / 1_000_000) | 0
-    this.particleCount = Math.min(this.option.particles.max, particleCount)
+    let particleCount = Math.round((this.option.particles.ppm * this.width * this.height) / 1_000_000)
+    particleCount = Math.min(this.option.particles.max, particleCount)
 
-    if (!isFinite(this.particleCount)) throw new RangeError('particleCount must be finite')
+    if (!isFinite(particleCount)) throw new RangeError('particleCount must be finite')
+    return particleCount | 0
   }
 
   /** @public Remove existing particles and generate new ones */
   newParticles() {
-    this.#updateParticleCount()
+    const particleCount = this.#targetParticleCount()
 
-    this.particles = []
-    for (let i = 0; i < this.particleCount; i++) this.createParticle()
+    if (this.hasManualParticles) {
+      this.particles = this.particles.filter((particle) => particle.manual)
+      this.hasManualParticles = this.particles.length > 0
+    } else {
+      this.particles = []
+    }
+
+    for (let i = 0; i < particleCount; i++) this.#createParticle()
   }
 
   /** @public Adjust particle array length to match `options.particles.ppm` */
   matchParticleCount({ updateBounds = false }: { updateBounds?: boolean } = {}) {
-    this.#updateParticleCount()
+    const particleCount = this.#targetParticleCount()
+
+    if (this.hasManualParticles) {
+      const pruned: Particle[] = []
+      let autoCount = 0
+
+      // Keep manual particles while pruning automatic particles that exceed `particleCount`
+      // Only count automatic particles towards `particledCount`
+      for (const particle of this.particles) {
+        if (autoCount >= particleCount) break
+        if (particle.manual) autoCount++
+        pruned.push(particle)
+      }
+      this.particles = pruned
+    } else {
+      this.particles = this.particles.slice(0, particleCount)
+    }
 
-    this.particles = this.particles.slice(0, this.particleCount)
-    if (updateBounds) this.particles.forEach((particle) => this.#updateParticleBounds(particle))
-    while (this.particleCount > this.particles.length) this.createParticle()
+    // Only necessary after resize
+    if (updateBounds) {
+      for (const particle of this.particles) {
+        this.#updateParticleBounds(particle)
+      }
+    }
+
+    for (let i = this.particles.length; i < particleCount; i++) this.#createParticle()
   }
 
-  /** @public Create a new particle with optional parameters */
-  createParticle(posX?: number, posY?: number, dir?: number, speed?: number, size?: number) {
-    posX = typeof posX === 'number' ? posX - this.offX : prng() * this.width
-    posY = typeof posY === 'number' ? posY - this.offY : prng() * this.height
+  /** @private Create a random new particle */
+  #createParticle() {
+    const posX = prng() * this.width
+    const posY = prng() * this.height
 
     const particle: Omit<Particle, 'bounds'> = {
       posX, // Logical position in pixels
@@ -256,18 +294,44 @@ export default class CanvasParticles {
       velY: 0, // Vertical speed in pixels per update
       offX: 0, // Horizontal distance from drawn to logical position in pixels
       offY: 0, // Vertical distance from drawn to logical position in pixels
-      dir: dir || prng() * TWO_PI, // Direction in radians
-      speed: speed || (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
-      size: size || (0.5 + prng() ** 5 * 2) * this.option.particles.relSize, // Ray in pixels of the particle
+      dir: prng() * TWO_PI, // Direction in radians
+      speed: (0.5 + prng() * 0.5) * this.option.particles.relSpeed, // Velocity in pixels per update
+      size: (0.5 + Math.pow(prng(), 5) * 2) * this.option.particles.relSize, // Ray in pixels of the particle
       gridPos: { x: 1, y: 1 },
       isVisible: false,
+      manual: false,
     }
     this.#updateParticleBounds(particle)
-    this.particles.push(particle as Particle)
+    this.particles.push(particle)
+  }
+
+  /** @public Create a new particle with optional parameters */
+  createParticle(posX: number, posY: number, dir: number, speed: number, size: number) {
+    const particle: Omit<Particle, 'bounds'> = {
+      posX, // Logical position in pixels
+      posY, // Logical position in pixels
+      x: posX, // Visual position in pixels
+      y: posY, // Visual position in pixels
+      velX: 0, // Horizonal speed in pixels per update
+      velY: 0, // Vertical speed in pixels per update
+      offX: 0, // Horizontal distance from drawn to logical position in pixels
+      offY: 0, // Vertical distance from drawn to logical position in pixels
+      dir: dir, // Direction in radians
+      speed: speed, // Velocity in pixels per update
+      size: size, // Ray in pixels of the particle
+      gridPos: { x: 1, y: 1 },
+      isVisible: false,
+      manual: true,
+    }
+    this.#updateParticleBounds(particle)
+    this.particles.push(particle)
+    this.hasManualParticles = true
   }
 
   /** @private Update the visible bounds of a particle */
-  #updateParticleBounds(particle: Omit<Particle, 'bounds'> & Partial<Pick<Particle, 'bounds'>>) {
+  #updateParticleBounds(
+    particle: Omit<Particle, 'bounds'> & Partial<Pick<Particle, 'bounds'>>
+  ): asserts particle is Particle {
     // The particle is considered visible within these bounds
     particle.bounds = {
       top: -particle.size,
@@ -277,6 +341,20 @@ export default class CanvasParticles {
     }
   }
 
+  /* @public Randomize speed and size of all particles based on current options */
+  updateParticles() {
+    const particles = this.particles
+    const len = particles.length
+    const relSpeed = this.option.particles.relSpeed
+    const relSize = this.option.particles.relSize
+
+    for (let i = 0; i < len; i++) {
+      const particle = particles[i]
+      particle.speed = (0.5 + prng() * 0.5) * relSpeed
+      particle.size = (0.5 + Math.pow(prng(), 5) * 2) * relSize
+    }
+  }
+
   /** @private Apply gravity forces between particles */
   #updateGravity(step: number) {
     const isRepulsiveEnabled = this.option.gravity.repulsive > 0
@@ -284,8 +362,8 @@ export default class CanvasParticles {
 
     if (!isRepulsiveEnabled && !isPullingEnabled) return
 
-    const len = this.particleCount
     const particles = this.particles
+    const len = particles.length
     const connectDist = this.option.particles.connectDist
     const gravRepulsiveMult = connectDist * this.option.gravity.repulsive * step
     const gravPullingMult = connectDist * this.option.gravity.pulling * step
@@ -340,8 +418,8 @@ export default class CanvasParticles {
 
   /** @private Update positions, directions, and visibility of all particles */
   #updateParticles(step: number) {
-    const len = this.particleCount
     const particles = this.particles
+    const len = particles.length
     const width = this.width
     const height = this.height
     const offX = this.offX
@@ -450,8 +528,8 @@ export default class CanvasParticles {
 
   /** @private Draw the particles on the canvas */
   #renderParticles() {
-    const len = this.particleCount
     const particles = this.particles
+    const len = particles.length
     const ctx = this.ctx
 
     for (let i = 0; i < len; i++) {
@@ -475,8 +553,8 @@ export default class CanvasParticles {
 
   /** @private Draw lines between particles if they are close enough */
   #renderConnections() {
-    const len = this.particleCount
     const particles = this.particles
+    const len = particles.length
     const ctx = this.ctx
     const maxDist = this.option.particles.connectDist
     const maxDistSq = maxDist ** 2
@@ -632,13 +710,18 @@ export default class CanvasParticles {
           options.mouse?.interactionType,
           CanvasParticles.interactionType.MOVE,
           { min: 0, max: 2 }
-        ),
+        ) as 0 | 1 | 2,
         connectDistMult: pno('mouse.connectDistMult', options.mouse?.connectDistMult, 2 / 3, { min: 0 }),
         connectDist: 1 /* post processed */,
         distRatio: pno('mouse.distRatio', options.mouse?.distRatio, 2 / 3, { min: 0 }),
       },
       particles: {
-        regenerateOnResize: !!options.particles?.regenerateOnResize,
+        generationType: ~~pno(
+          'particles.generationType',
+          options.particles?.generationType,
+          CanvasParticles.generationType.MATCH,
+          { min: 0, max: 2 }
+        ) as 0 | 1 | 2,
         drawLines: !!(options.particles?.drawLines ?? true),
         color: options.particles?.color ?? 'black',
         ppm: ~~pno('particles.ppm', options.particles?.ppm, 100),

package/src/types/index.ts

@@ -30,6 +30,7 @@ export interface Particle {
   bounds: ParticleBounds
   gridPos: ParticleGridPos
   isVisible: boolean
+  manual: boolean
 }
 
 export interface ParticleBounds {

package/src/types/options.ts

@@ -7,14 +7,14 @@ export interface CanvasParticlesOptions {
   }
 
   mouse: {
-    interactionType: number
+    interactionType: 0 | 1 | 2 /* see CanvasParticles.interactionType */
     connectDistMult: number
     connectDist: number /* post processed */
     distRatio: number
   }
 
   particles: {
-    regenerateOnResize: boolean
+    generationType: 0 | 1 | 2 /* see CanvasParticles.generationType */
     drawLines: boolean
     color: string | CanvasGradient | CanvasPattern
     ppm: number