A lightweight, fun particle system written in Javascript.
This library aims to port the bubbles
particle format to Javascript for use in the browser.
It is intended to be used for fun and experimentation - expect bugs and breaking changes.
Here are some examples of simple particle effects with bubbles.
bubbles.json | fireball.json | explosion.json | hearts.json | confetti.json | tornado.json |
You can find the .json for these in the examples folder at jaynewey/bubbles. Note that currently images are not supported by bubblesjs
so effects such as hearts
will not work.
See the live demo at CodePen.
The pen adds functionality for the effect to move to the mouse position - this doesn't come with bubbles
but rather, shows how one might interact with it.
The api for bubblesjs
has been streamlined from the Python library to make it easier to intergrate into web pages.
Include bubblesjs
via a script
tag:
<script src="dist/bubbles.min.js"></script>
In your html, add a canvas
element with a distinct id
attrbute:
<canvas id="confetti"></canvas>
In your javascript, create a Bubbles
instance, passing in the id
of the canvas
to render on:
const bubbles = new Bubbles("#confetti");
You may now register Particle Effects in bubbles
Particle Effect format (parameter details below):
bubbles.registerEffect(
{
"x": 50,
"y": 50,
"loops": -1,
"emitters": [
{
"width": 8,
"height": 8,
"frames": 10,
"spawn_amount": 10,
"spawns": 10,
"particle_settings": {
"lifetime": 120,
"x_speed": [0, 0],
"y_speed": -4,
"y_acceleration": 0.05,
"scale": [0.4, 0],
"shape": "square",
"rotation": [0, 90],
"colourise": true,
"red": 150,
"green": 150,
"blue": 150
},
"particle_variation": {
"lifetime": 30,
"x_speed": [1, 1],
"x_acceleration": 0.2,
"y_speed": 0.5,
"scale": [0.2, 0],
"rotation": [180, 90],
"red": 100,
"green": 100,
"blue": 100
}
}
]
}
);
bubbles
(should) start drawing onto the canvas at the x, y location relative to the canvas.
Note: You may use unquoted attribute identifiers and camelCase
instead of snake_case
, but this is not supported in the Python implementation.
Particles are the small, individual parts that make up a collective effect. Emitter
instances are used to spawn them. Particles have the following default attributes:
{
// How many frames the particle lives for
"lifetime": 30,
// The interpolation function between points
"interpolation": "linear", // (linear/cosine)
// The x position of the particle relative to the effect
"x": 0,
"x_speed": 0,
"x_acceleration": 0,
// The y position of the particle relative to the effect
"y": 0,
"y_speed": 0,
"y_acceleration": 0,
// A multiplier of the size of the particle's shape. Generally <= 1, >= 0
"scale": 1,
// How opaque the particle is
"opacity": 1,
// Rotation of the particle in degrees
"rotation": 0,
// The shape of the particle
"shape": "square", // The name of the shape (only "square", "circle" supported currently).
"red": 255,
"green": 255,
"blue": 255
}
Often, you might want parameters to change over the lifetime of a Particle. You can do this by setting the parameter as an array of arbitrary length (we'll go with a humble 3).
{
"scale": [0, 1, 0]
}
The particle will go from 0, to 1, to 0 in scale over its lifetime. You can apply this technique to the following parameters:
[
"x_speed",
"x_acceleration",
"y_speed",
"y_acceleration",
"scale",
"opacity",
"rotation",
"red",
"green",
"blue"
]
You can choose between "linear"
and "cosine"
interpolation between these points by changing the "interpolation"
parameter.
To illustrate the difference between these types of interpolation, consider the following particle example:
{
"lifetime": 60,
"opacity": [0.25, 0.8, 0, 0.5, 0.1]
}
The following graphs show how the opacity will change over the particle's lifetime:
Linear | Cosine | Both |
Note, that if you use a list for a parameter, that you must similarly use a list of the same length if you want to specify variation for that parameter.
You would want some form of variation between these particles, and to actually spawn them. Use emitters for this. You can have multiple emitters per effect and place wherever you like relative to the effect. The following values are set by default.
{
// Position relative to the effect
"x": 0,
"y": 0,
// The area in which particles can spawn, by default is a single point
"width": 0,
"height": 0,
// How many spawn bursts the emitter performs, by default is infinite
"spawns": -1,
// How many particles are spawned with each spawn burst
"spawn_amount": 10,
// How many frames between each spawn burst
"frames": 30,
// The maximum number of particles spawned with this emitter that can live at once
"max_particles": 1000,
// What kind of particles to spawn
"particle_settings": {},
"particle_variation": {
// Only these parameters can be varied:
"lifetime": 0,
"x_speed": 0,
"y_speed": 0,
"x_acceleration": 0,
"y_acceleration": 0,
"scale": 0,
"opacity": 0,
"rotation": 0,
"red": 0,
"green": 0,
"blue": 0
}
}
You want to tell the Emitter what kind of particles to spawn. You can set particle_settings
as an object with the desired particle attributes. Think of it as a base particle of the emitter before any variation is applied.
Particle variation specifies how varied you'd like the particles to be on a +- basis. For example, setting the lifetime
in settings to 60 and the lifetime
variation to 30 means that the lifetime of particles spawned by the emitter is between 30 and 90.
Particle effects handle Emitters and Particles. You can specify an effect's emitters and the following attributes, the default being:
{
// Position of the entire effect relative to where it is drawn
"x": 0,
"y": 0,
// Global speed of the effect, applies to particles and position of effect
"x_speed": 0,
"y_speed": 0,
// How many loops of the effect until this effect is finished, by default is infinite
"loops": -1,
// The emitters that belong to the effect
"emitters": []
}
This effect does nothing since there are no emitters and hence no particles to draw. The emitters
array is here is a an array of emitter settings objects (not Emitter instances!).
Use the GitHub issue tracker to report issues.