decentralized-particles

An unbelievably small and lightweight particles animation engine.

Runs in both node and the browser!

Installation

npm

The easiest way to use this package is with npm + your favorite javascript bundler:

npm i decentralized-particles

CDN or direct download

If you prefer the old-school method, you can use the CDN (https://unpkg.com/decentralized-particles/dist/build.iife.js), or you can directly download the latest iife build.

<script src="cdn/or/path/to/package/"></script>

Both old-school methods expose a DParticles object to the window that is equivalent to this:

import * as DParticles from 'decentralized-particles';

Usage

import { createParticlesOnCanvas } from 'decentralized-particles';

createParticlesOnCanvas(canvasElement, { nextFrameCaller: fn => requestAnimationFrame(fn) });

The unique thing about this package is that the particles do not have to be drawn on canvas. They can be anything, anywhere! Particles are completly abstract, 100% decentralized. Check out the DecentralizedParticles example, or the official canvas implementation for more information.

API

createParticlesOnCanvas

(element: HTMLCanvasElement, configOptions:ConfigOptions, particleOptions:ParticleOptionssegmentOptions:SegmentOptions](#segment-options)) =>[DecentralizedParticles`

Implements the particle animation engine on canvas.

Both configOptions and particleOptions are passed directly into DecentralizedParticles

DecentralizedParticles

This has no link to the GUI. That is for you to do (note the createParticle function).

Example:

const parent = document.getElementById('particles');

// The last two arguments are optional
const particles = new DecentralizedParticles(configOptions, particlesOptions, segmentOptions);

particles.createParticle(particle => {
	const element = document.createElement('particle');
	parent.appendChild(element);

	setPos();
	particle.onUpdate(setPos);

	function setPos() {
		element.style.left = particle.positionX;
		element.style.top = particle.positionY;
	}

	particle.onDestroy(() => element.remove());
});

particles.start();

particleOptions should be of type ParticleOptions, as it is passed directly into Particle. segmentOptions should be of type SegmentOptions, as it is passed directly into Segment.

configOptions must be of type ConfigOptions.

createParticle(fn)

fn will be called every time a new particle is created. An instance of Particle will be passed in as the first and only argument.

createSegment(fn)

If segments is true in the config options, fn will be called every time a new segment is created. An instance of Segment will be passed in as the first and only argument.

beforeUpdate(fn)

Calls fn before each update.

afterUpdate(fn)

Calls fn after each update.

start()

This starts the animation.

pause()

Pauses the animation.

Returns a function that will play the animation when called.

ConfigOptions

• particlesCount (optional): An object containing the min and max values. Default is max: 200, min: 150
• nextFrameCaller (optional): A function that calls a callback when ready to go to the next frame. Default:

  fn => setTimeout(fn, 16);

  Note: When in the browser, you will want to set this to:

  fn => requestAnimationFrame(fn);

• segments (optional): A boolean indicating wether or not to link the particles together with segments. Defaults to true
• segmentStrength (optional): A large number here results in particles further apart being linked with a segment. Default is 0.11

options

The options passed into Particle.

size: number

A randomly selected number between options.size.min and options.size.max.

background: string

A chosen background based off of options.background.

lifespan: number

A randomly selected number between options.lifespan.min and options.lifespan.max.

speed: number

A randomly selected number between options.speed.min and options.speed.max.

The actual speed of the particle will vary though, and this number is just used as a starting point.

id: string

A random 20 character string used behind the scenes.

age: number

The amount of updates this particle has had. It will automaticly self-destruct when age >= lifespan.

positionX: number

A number between 1 and 0. The current positionX of the particle.

positionY: number

A number between 1 and 0. The current positionY of the particle.

initialPositionX: number

A number between 1 and 0. The positionX that the particle had when it was created.

initialPositionY: number

A number between 1 and 0. The positionY that the particle had when it was created.

finalPositionX: number

A number between 1 and 0. The planned positionX that the particle is to reach when age === lifespan.

finalPositionY: number

A number between 1 and 0. The planned positionY that the particle is to reach when age === lifespan.

triggerUpdate()

This will trigger a new update in the particle's lifecycle. Used behind the scenes.

onUpdate(fn)

fn is called each time a new update is triggered.

destroy()

Destroys the particle. This method is called when age === lifespan or when positionX or positionY becomes less than 0 or greater than 1.

onDestroy(fn)

fn is called when the particle is destroyed.

Particle

See the source for details.

Segment

See the source for details.

ParticleOptions

• size (optional): An object containing the min and max keys. Default is max: 7, min: 3.
• background (optional): A string that represents the background, or an array of strings. Default is #ddd.
• lifespan (optional): The amount of updates until the particle self-destructs: An object containing the min and max keys. Default is max: 400, min: 300.
• speed (optional): The amount to move each particle per update. Default is max: 0.0005, min: 0.0009.
• keepAround (optional): If the particle should choose a new direction and set age back to 0 when it would otherwise self-destruct.

Segment Options

• stroke (optional): A string that represents the segment stroke, or an array of strings. Default is #bbb.
• width (optional): An object containing the min and max keys. Default is max: 0.5, min: 0.5.

Contributing?

Sure!

# fork repo
git clone https://github.com/[your_username]/decentralized-particles
cd decentralized-particles
npm i
npm run dev

Pull Requests are always welcome!

PS: Don't forget to npm run lint! :wink:

License

MIT