@markuslerner/particular NPM

Particular

Particle system written in JavaScript. Heavily inspired by Punktiert Java library.

Why yet another physics/particle system libary? I simply didn't find a JavaScript physics/particle system libary that is GPU-accelerated, behavior-based (eg. flocking/swarm, seek/arrive) and works they way I was used to from earlier days in Java/Processing.

Collaborations and improvements welcome.

Highlights

GPU-accelerated (currently only Collision behavior) using gpu.js
Simple API
Behavior-based
Vector3 API fully compatible with THREE.js Vector3

Usage

yarn add @markuslerner/particular

npm install @markuslerner/particular

Include classes from this package:

import {
  SimplePhysics,
  Particle,
  Collision,
  Seek,
} from '@markuslerner/particular';

Create physics:

const physics = new GPUPhysics();

Create particle(s) and add to physics:

const particle = new Particle(x, y, z);
physics.addParticle(particle);

Add behavior(s):

particle.addBehavior(new Collision());
particle.addBehavior(new Seek());

Update physics every frame:

physics.update();

Done.

Collaborations and improvements are welcome.

Examples

Editing source code and examples

To edit the source code and the examples, run:

yarn start

npm start

A development server will be launched under http://localhost:8000/

The files from the src folder will we re-built automatically into a virtual build/particular.js upon reloading the page.

API Docs

SimplePhysics class

Constructor

new SimplePhysics({ friction = 0.95, springIterationsCount = 50 } = {});

Members:

Member	Type	Default	Description
`behaviors`	Set	new Set()	Behaviors for all particles
`constraints`	Set	new Set()	Constraints for all particles
`groups`	Set	new Set()	Groups of particles (not implemented yet)
`particles`	Set	new Set()	All particles
`springs`	Set	new Set()	All springs (not implemented yet)
`friction`	number	0.95;
`springIterationsCount`	number	50;

Public Methods:

Method	Return value	Description
`addBehavior(behavior: Object)`		Add behavior to all particles
`addParticle(particle: Particle)`		Add particle
`addSpring(spring: Spring)`		Not implmemented yet
`addGroup(group: Group)`		Not implmemented yet
`clear()`		Clear particles, groups and springs
`getSpring(a: Particle, b: Particle)`	Spring	Attempts to find the spring element between the 2 particles supplied
`getnumConnected(spring: Spring)`	number	Get the count of how many springs are connected to A
`hasBehavior(behavior: Behavior)`	Behavior	Check, if physics has this behavior
`hasGroup(group: Group)`	Group	Check, if physics has this group
`hasParticle(particle: Particle)`	Particle	Check, if physics has this particle
`hasSpring(spring: Spring)`	Spring	Check, if physics has this spring
`removeBehavior(behavior: Behavior)`	boolean	Remove behavior
`removeParticle(particle: Particle)`	boolean	Remove particle
`removeSpring(spring: Spring)`	boolean	Remove spring
`removeSpringElements(spring: Spring)`	boolean	Removes a spring connector and its both end point particles
`removeGroup(group: Group)`	boolean	Remove group
`update(deltaTime: number = 1)`		Update simulation

Particle class

Extends Vector3 class

Vector3 API is fully compatible with THREE.js Vector3.

Constructor

new Particle(x: number = 0.0, y: number = 0.0, z: number = 0.0, mass: number = 1.0, radius: number = 1.0);

Members:

Member	Type	Default	Description
`x`	number	0.0
`y`	number	0.0
`z`	number	0.0
`locked`	boolean	false	Particle lock status
`behaviors`	Set	null	Particle behaviors
`neighbors`	Set	null	Particle neighbors
`mass`	number	1.0
`radius`	number	1.0
`friction`	number	0.0
`maxSpeed`	number	3.0
`force`	Vector3	new Vector3()
`velocity`	Vector3	new Vector3()
`velocitySmooth`	Vector3	new Vector3()
`followers`	Set	new Set()	Follower which will copy this particle’s position

Public Methods:

Method	Return value	Description
`addBehavior(behavior: Object, addEvenIfExists: boolean = false)`	this	Add behavior to this particle only
`getBehavior(behaviorClass: Class)`	Instance of Behavior	Get behavior by behavior class
`addFollower(vector: Vector3)`		Will copy this particle’s position
`addForce(force: Vector3)`	this	Add force to this particle, used by behaviors
`clearForce()`	this	Clear force
`clearVelocity()`	this	Clear velocity
`getVelocity()`	Vector3	Get velocity
`lock()`	this	Lock this particle’s position
`removeBehavior(behavior: Object)`	boolean	Remove behavior, returns true, if behavior was found
`removeFollower(follower: Object)`	boolean	Remove follower, returns true, if follower was found
`unlock()`	this	Unlock this particle’s position
`constrainX(min: number, max: number)`		Constrain x
`constrainY(min: number, max: number)`		Constrain y
`constrainZ(min: number, max: number)`		Constrain z