Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


0.9.1 • Public • Published


An abstracted physics engine for voxel game engines.

This implements reasonably realistic physics for voxel games. It was made to work with noa or voxel.js, but it just takes references to an abstracted getBlock(x,y,z) function and plain vectors, so it can be used with other engines.

This replaces voxel-physical, though it works quite differently and behaves more physically.

The engine can be seen in action in noa or projects using it (such as this talk on voxels.


  1. Create engine and supply a getBlock(x,y,z)-like function (which should return true when block xyz is solid)
  2. Register rigid bodies with var body = addBody(..)
  3. Control them with body.addImpulse[0,1,0] and so on
  4. Call tick(dt)

and the engine will manage all the physics and collisions.


var makePhysics = require('voxel-physics-engine')
var opts = { gravity: [0,-10,0] }
var getter = function(x,y,z) { /* your logic here */ }
var phys = makePhysics( opts, getter )
var body = phys.addBody( aabb, mass, friction, restitution, gravityMult, onCollide, autoStep )
phys.tick( dt_in_miliseconds )
phys.removeBody( body )


  • Reasonably physical, supports standard properties (friction, restitution, etc.)
  • Query the body's resting[axis] property (-1,0,1 on each axis) to tell if it's currently touching a solid voxel. E.g. body.resting[1] is 1 when the body is colliding with the ceiling.
  • Collisions with terrain trigger each body's onCollide(impacts) callback. The argument is a vec3 of the change in velocity on each axis, so multiply by mass if you want the impulse. (A body resting on the ground will produce a small impact each tick due to gravity.)
  • If you set a body's autoStep property, the engine will cause it to automatically "step" up hills (i.e. 1-block obstructions).

Changes in latest version:

  • 0.9.0
    • Air and fluid friction properties renamed to airDrag and fluidDrag, and now work equivalently (no drag at 0, large drag at 1)
    • Per body airDrag and fluidDrag override global settings if >= 0
  • 0.8.0
    • Friction now uses regular coefficients, and works in all directions, not just downwards
    • Bodies have an .airFriction that overrides the global value (if nonzero)
    • Air and regular friction should now scale correctly with frame rate


npm i voxel-physics-engine

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability