Particulate.js
Particulate.js is a JavaScript particle physics micro library designed to be simple, extensible, fast, and stable;
it is capable of running a simulation with tens of thousands of particles and tens of thousands of constraints in real time.
The core system is derived from that described in Advanced Character Physics by Thomas Jakobsen.
Website –
Examples –
Docs –
Tests
Usage
The library provides an interface for defining a particle system with many inter-particle constraints
and globally acting forces. Internal management of particle positions and state is designed to be easily integrated
with a WebGL rendering pipeline, although no specific rendering scheme is required.
Install
Install with npm or bower or download the built package.
npm install particulate --save
bower install particulate --save
Then include the library as an ES6, AMD, or commonJS module, or browser global.
import { ParticleSystem, DistanceConstraint } from 'particulate'
define(['particulate'], function (Particulate) { /* ... */ });
var Particulate = require('particulate');
var Particulate = window.Particulate;
Integrate Renderer
The following is a simplified version of the chain example,
rendered with Three.js:
// ..................................................
// Define particle chain system
//
var particleCount = 5;
var relaxIterations = 2;
var system = Particulate.ParticleSystem.create(particleCount, relaxIterations);
var dist = Particulate.DistanceConstraint.create(10, [0, 1, 1, 2, 2, 3, 3, 4]);
var pin = Particulate.PointConstraint.create([0, 0, 0], 0);
var gravity = Particulate.DirectionalForce.create([0, -0.05, 0]);
system.addConstraint(dist);
system.addPinConstraint(pin);
system.addForce(gravity);
// ..................................................
// Integrate with Three.js
//
var scene = new THREE.Scene();
// Use system positions buffer
var vertices = new THREE.BufferAttribute(system.positions, 3);
// Use distance constraint indices
var indices = new THREE.BufferAttribute(new Uint16Array(dist.indices));
// Particles
var dotsGeom = new THREE.BufferGeometry();
dotsGeom.addAttribute('position', vertices);
var dots = new THREE.PointCloud(dotsGeom,
new THREE.PointCloudMaterial({ size : 2 }));
// Connections
var linesGeom = new THREE.BufferGeometry();
linesGeom.addAttribute('position', vertices);
linesGeom.addAttribute('index', indices);
var lines = new THREE.Line(linesGeom,
new THREE.LineBasicMaterial());
scene.add(dots);
scene.add(lines);
function animate() {
system.tick(1);
dotsGeom.attributes.position.needsUpdate = true; // Flag to update WebGL buffer
render();
}
Development
Grunt is used for building and testing the library.
You should have one path for each dependency:
which node npm grunt
After resolving development dependencies, run:
npm install
Test
Run a development server with grunt server.
Visit localhost:8000/examples/ to view examples or localhost:8000/test/ to run tests.
The development version of the library will be automatically rebuilt when any file matching /src/**/* changes.
Tests can also be run from the command line with grunt test.
Build
Running grunt build will generate a fully commented development version of the library as well as
a minified production version in /dist.
Document
Source code is documented in-line using YUIDoc syntax
and compiled by running grunt yuidoc.
Contribute
There is not a formal style guide, but please maintain the existing coding style.
Any new or changed functionality should be documented and covered by unit tests.