Heegs
A simple 2D physics engine written in typescript, optimized for creating webgl particle effects. Demo here
Installation
Install with NPM:
$ npm install heegs
or use the standalone UMD build
$ <script src="https://unpkg.com/heegs"></script>
Usage
When you include Heegs
in your project it outputs an Engine
and a bunch of behaviors.
Engine
is the core part of Heegs
. It creates and glues everything together.
Create a new Heegs
instance by instantiating Engine
class and provide it with the number of particles present in the simulation. In order to do the calculations use start
and update
methods on the instance of Engine
and provide them with the current time. The method start
should be called once, when you want to begin the simulation, and the method update
should be called in every frame.
Behaviors are classes that modify the forces present in the simulation. You can add/remove them using addBehavior
and removeBehavior
methods on the Engine
's instance. If the behavior you're looking for is not provided with Heegs
you can easily create your own. A class can be used as a behavior if it has an update
method. A simple example is as follows:
class DummyBehavior {
update: (dt: number, x: number, y: number, data: Float32Array, offset: number) => void {
/**
* dt is the time difference between the current frame and the last one
* x is the x-axis position of the particle
* y is the y-axis position of the particle
* data contains information about the velocity, force and mass of all the particles
* offset gives the first index inside the data array where current particle's information is stored
*/
// You can access particle's params as follows:
const v_x = data[offset]
const v_y = data[offset + 1]
const mass = data[offset + 4]
// Calculate the forces that should be acting on the particle in result of existence of DummyBehavior
const f_x = Math.random() * v_x * mass
const f_y = Math.random() * v_y * mass
// [Required]
// In order for the DummyBehavior's forces to be effective on the particle you should add the calculated values to the current forces acting on it
data[offset + 2] += f_x
data[offset + 3] += f_y
}
}
Code Example
import {Engine, Sink, Drag} from 'heegs'
// Create a new instance
const numberOfParticles = 10
const h = new Engine(numberOfParticles)
/**
* [Optional]
* Set particles initial mass, position and velocity
* default values are:
* mass = 1
* position = [0, 0]
* velocity = [0, 0]
*/
h.setParticlesParams((index, {setMass, setPosition, setVelocity}) => {
const mass = 1 + index
const x = Math.random()
const y = Math.random()
const v_x = Math.random()
const v_y = Math.random()
setMass(mass)
setPosition(x, y)
setVelocity(v_x, v_y)
})
// Add a new behavior to the engine
const s = h.addBehavior(Sink)
// Customize behavior's parameters
s.setIntensity(10)
s.setCenter(1, 1)
// Behaviors can be added/removed while engine is running
setTimeout(() => {
h.removeBehavior(s)
const d = h.addBehavior(Drag)
const fixedCoeff = 1
const randomCoeff = 1
d.setIntensity(fixedCoeff, randomCoeff)
}, 2000)
// Start calculation
h.start(performance.now())
play()
function play() {
// Update particles
h.update(performance.now())
// position of particles is accessible via h.positionData
// h.positionData is a Float32Array
// so we can put it in a webGL buffer directly
webGL.replacePositionBuffer(h.positionData)
requestAnimationFrame(play)
}
Note
I've intentionally avoided running the physics as a compute shader to see how much perf I can squeeze out of normal javascript. I managed to get 75K particles animating at 60fps on my machine, a mid 2014 mbp with integrated gpu.