@markuslerner/particular

0.8.0 • Public • Published

Particular

NPM Package

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

or

npm install @markuslerner/particular
  1. Include classes from this package:
import {
  SimplePhysics,
  Particle,
  Collision,
  Seek,
} from '@markuslerner/particular';
  1. Create physics:
const physics = new GPUPhysics();
  1. Create particle(s) and add to physics:
const particle = new Particle(x, y, z);
physics.addParticle(particle);
  1. Add behavior(s):
particle.addBehavior(new Collision());
particle.addBehavior(new Seek());
  1. 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

or

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

Available Behaviors:

  • Align: align movement with neighbors
  • Avoid: avoid single target
  • Bounce: bounce off world box
  • Cohesion: keep close to neighbors
  • Collision: avoid collision with neighbors
  • Constrain: keep within world box
  • Seek: seek single target
  • SeekRandom: seek single random target
  • Separate: separate from neighbors
  • Wander: random wander movment
  • Wrap: wrap around word box

Editing source

In order to edit the source code, run:

yarn start

And open http://127.0.0.1:8000/ in your browers.

The files in the build folder will automatically be rebuilt when modified.

To Do

  • Add gpu acceleration for Align, Cohesion and Separate behaviors as well
  • Create 3D flocking example
  • Add missing behaviors and params to all behaviors example
  • Consider writing behaviors as a plugin for matter.js
  • Create other shapes (box, polygon)

License

MIT licensed

Created by Markus Lerner

Package Sidebar

Install

npm i @markuslerner/particular

Weekly Downloads

1

Version

0.8.0

License

MIT

Unpacked Size

1.72 MB

Total Files

36

Last publish

Collaborators

  • markuslerner