Skip to content
The next generation of Voxel JS
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


The next generation of Voxel JS.

This project updates the original voxeljs with modern Javascript (classes, ES6 modules, arrow functions, etc), and brings it in line with the latest ThreeJS, with support for the latest WebGL features, and also adds VR/AR support.

Because of these improvements, voxeljs-next is not compatible with the original VoxelJS modules. All old modules a features will need to be ported to the new code.


VoxelJS is built on ThreeJS and the WebGL & WebXR standards. With the right options enabled it will run on desktop in embedded mode, full screen with pointer lock, on a touch screen (phone, tablet), and in any VR headsets with a browser.

How to use VoxelJS

Start by copying and modifying the main example application.

Add new textures

Textures are loaded by the TextureManager. Add new images to the examples/textures directory then add their file names (minus the .png extension) to the load call like this:


create a custom world with code

VoxelJS does not specify any on disk format for maps. It is up to you to provide that, though you can look at the PersistenceManager example to see how it could work. The only thing you need to provide is to provide a function to the ChunkManager which accepts a low and high dimension and coordinates. This function should generate a new info bject with the data for that chunk.

If you already have a function which returns the block number at a particular spot in the chunk then you can use the utils.generateChunkInfoFromFunction to build the chunk info. Here's a simple example that creates a completely flat world 10 blocks thick.

const flat = (i,j,k) => {
    //the floor is brick, from depth 0 to -10
    if(j < 1 && j > -10) return 2
    //nothing else in the world
    return 0

app.chunkManager = new ChunkManager({
    generateVoxelChunk: (low, high, cx,cy,cz) => {
        const id = [cx,cy,cz].join('|')
        if(app.CHUNK_CACHE[id]) return app.CHUNK_CACHE[id]
        return generateChunkInfoFromFunction(low, high, flat)


Voxel only tracks movementt of the player. To add other autonomus entityes like enemies and friendlies create a new ThreeJS group for tthem in your scene then add the ThreeJS objects. To make the entity interact with blocks and other objects you'll need to use a PhysHandler. See the pig example for details


VoxelJS does not provide voice chat or networked play out of the box, but you can look at the example code for an example of using WebRTC for voice chat and PubNub for tracking player movement and terrain changes.

Help and Contributing

The general algorithm for rendering voxel data and how this engine works is documented in this blog.

For help try asking in the #voxel channel in the ThreeJS slack.

If you'd like to contribute take a look at the issues. There are a ton of features that need implementing including

  • make cheap ambient occulsion work when the greedy mesh is turned on
  • an api to set multiple chunks at once
  • better example of networked play
  • more demos
  • alternative rending. smaller cubes, cool textures, weird effects
  • Fix full screen in iOS and Mac safari
  • Touch screen dragging
  • Can’t choose block type in iPad
  • implement water: How Water Works In DwarfCorp
  • API to set multiple blocks at once. Batches help network as well.
  • other modules should Never know about chunks. Just get and set blocks.
  • level of detail: A level of detail method for blocky voxels | 0 FPS
  • fix AO for greedy mesher. Explain the problem.

These particular issues are newbie friendly.


  • explain how meshing and chunking works. the core algorithm
  • explain how rendering works. esp texture mapping.
You can’t perform that action at this time.