Plugin WebGL Particles

Plugin: WebGL Particles

dopaminejs-plugin-webgl-particles 1.1.2.

npm install dopaminejs-plugin-webgl-particles

A particle system that draws points with WebGL. Use it when the canvas ParticleSystem and its 5000 particle cap are not enough.

import { Game } from 'dopaminejs';
import { WebGLParticlePlugin } from 'dopaminejs-plugin-webgl-particles';

const game = new Game();
game.kernel.plugins.use(WebGLParticlePlugin);
game.start();

const particles = game.kernel.systems.get('particles');
particles?.confetti(400, 300, 500);

The plugin registers a system named particles with room for 10,000 particles.

Particles only move while the kernel loop runs. Call game.start().

No WebGL

When the browser has no WebGL, the plugin logs an error and registers nothing. systems.get('particles') is then undefined, unless a particles system was already registered, which is left in place. There is no canvas fallback. (1.1.1 and older logged that one was used. 1.1.2 does not.) Check for the system and fall back yourself:

const particles = game.kernel.systems.get('particles') ?? new ParticleSystem();

The two systems take different emit options, so only confetti(x, y, count) and sparkle(x, y, count) are safe to call on either.

API

Method	Notes
emit(config)	See below
confetti(x, y, count = 50)	Five colours, random size and lifetime
sparkle(x, y, count = 20, color = [1, 1, 1, 1])	Small short-lived points
registerEffect(name, callback)	callback(x, y, ...args), called with the system as this
play(name, x, y, ...args)	Runs a registered effect. An unknown name does nothing.
clear()	Drops every particle

emit

particles.emit({
    x: 400,
    y: 300,
    count: 200,
    color: [1, 0.8, 0.2, 1],
    size: 6,
    lifetime: 1.5,
    velocity: { x: 0, y: -200 },
    spread: 40
});

Option	Default	Meaning
x, y	0	Origin in pixels on the overlay canvas
count	10	Particles to add
color	[1, 1, 1, 1]	RGBA, each 0 to 1
size	5	Point size in pixels
lifetime	1	Seconds
velocity	{ x: 0, y: -100 }	Pixels per second, added to a random burst of 100 to 300 in any direction
spread	50	Random offset of the starting position, in pixels

Gravity is fixed at 500 pixels per second squared.

Differences from the canvas ParticleSystem

	Canvas ParticleSystem	WebGL system
Colour	CSS string or array of strings	[r, g, b, a]
Speed	speed, per 60 Hz frame	velocity, per second
Life	life and decay per frame	lifetime in seconds
spread	arc in radians	position jitter in pixels
Sprites	yes	registerSprite warns and does nothing
fire, starBurst, coinShower	yes	no
Runs without the kernel loop	yes	no

It has no fire or starBurst, so it cannot be passed to GameUI.

Using the class directly

import { WebGLParticleSystem } from 'dopaminejs-plugin-webgl-particles';

game.kernel.systems.register('particles', new WebGLParticleSystem({
    maxParticles: 50000,
    container: '#game'
}), { priority: 50 });

• maxParticles defaults to 10,000 and is capped at 1,000,000.
• container is an element or a selector. The overlay canvas is appended to it and sized to it. Default is document.body.
• A lost WebGL context is restored when the browser gives it back.

Removing it

game.kernel.plugins.remove('webgl-particles');

With dopaminejs 2.4.0 or newer this also unregisters the particles system. The plugin's destroy is empty, so on an older core call game.kernel.systems.unregister('particles') too.