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/particularor
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 startor
npm startA 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 startAnd 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