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



    Add textures to an atlas and set UV mapping on geometries. Used for texturing in voxel.js.

    View the demo.

    ATTENTION! v0.5.0 has changed dramatically. This library is no longer is materials API but just loads textures onto an atlas and sets UV mappings.


    // create a material engine
    var textureEngine = require('voxel-texture')({
      // a copy of your voxel.js game
      game: game,
      // path to your textures
      texturePath: 'textures/'
    // load textures and it returns textures just loaded
    textureEngine.load(['grass', 'dirt', 'grass_dirt'], function(textures) {
      // create a new mesh
      var cube = new game.THREE.Mesh(
        new game.THREE.CubeGeometry(game.cubeSize, game.cubeSize, game.cubeSize),
        // use the texture engine atlas material
      // paint the cube with grass on top, dirt on bottom and grass_dirt on sides
      textureEngine.paint(cube, ['grass', 'dirt', 'grass_dirt']);



    Returns a new texture engine instance. Must pass a copy of your voxel.js game. options defaults to:

      texturePath: '/textures/',
      materialParams: { ambient: 0xbbbbbb },
      materialType: THREE.MeshLambertMaterial,
      applyTextureParams: function(map) {
        map.magFilter = this.THREE.NearestFilter;
        map.minFilter = this.THREE.LinearMipMapLinearFilter;

    textureEngine.load(textures, callback)

    Loads textures onto the atlas by expanding the texture names:

    textureEngine.load('grass', function(textures) {
      // textures = [grass, grass, grass, grass, grass, grass]
    textureEngine.load(['grass', 'dirt', 'grass_dirt'], function(textures) {
      // textures = [grass_dirt, grass_dirt, grass, dirt, grass_dirt, grass_dirt]
      ['back', 'front', 'top', 'bottom', 'left', 'right'],
    ], function(textures) {
      textures = [
        obsidian, obsidian, obsidian, obsidian, obsidian, obsidian,
        back, front, top, bottom, left, right,
        brick, brick, brick, brick, brick, brick


    Finds the type of block by texture name:

    // Find and change the center block to grass
    game.setBlock([0, 0, 0], textureEngine.find('grass'));

    Although this is built into the voxel engine so you could just do:

    game.setBlock([0, 0, 0], 'grass');

    textureEngine.paint(mesh, textures)

    Modifies the UV mapping of given mesh to the textures names supplied:

    // create a custom mesh and load all materials
    var mesh = new game.THREE.Mesh(
      new game.THREE.Geometry(),
    // paint the geometry
    textureEngine.paint(mesh, ['grass', 'dirt', 'grass_dirt']);

    Or if you have the face.color set on the faces of your geometry (such as how voxel-mesh does it) then omit the textures argument. It will select the texture based on color from all the previously loaded textures:


    textureEngine.sprite(name, w, h, callback)

    Create textures from a sprite map. If you have a single image with a bunch of textures do:

    // load terrain.png, it is 512x512
    // each texture is 32x32
    textureEngine.sprite('terrain', 32, function(textures) {
      // each texture will be named: terrain_x_y

    The width and height default to 16x16.

    textureEngine.animate(mesh, textures, delay)

    Create an animated material. A material that after each delay will paint the mesh by iterating through textures. Must run textureEngine.tick() to actually animate.

    var mesh = new game.THREE.Mesh(
      new game.THREE.Geometry(),
      new game.THREE.MeshFaceMaterial()
    mesh.material = textureEngine.animate(mesh, ['one', 'two', 'three'], 1000);


    Run the animations for any animated materials.

    game.on('tick', function(dt) {


    With npm do:

    npm install voxel-texture

    release history

    • 0.5.8 - Add missing opaque module dependency. Thanks @deathcap!
    • 0.5.7 - Separately load transparent textures. Fill atlas bg in black. Replace AO with voxel-fakeao. Dynamically set amount of sides with texturing, thanks @morganrallen!
    • 0.5.6 - Add materialFlatColor option for using simple flat colors instead of textures.
    • 0.5.5 - Only call document.createElement if available.
    • 0.5.4 - Allow null placeholder materials.
    • 0.5.3 - Force texture to dimensions that are power of 2 for mipmaps.
    • 0.5.2 - Use atlaspack tilepad to avoid mipmap texture bleed.
    • 0.5.1 - Fix CORS support.
    • 0.5.0 - No longer a materials API. Loads textures onto an atlas and sets UV mappings.
    • 0.4.0 - Add findIndex for finding block type index.
    • 0.3.3 - Move three to peerDependencies. thanks @niftylettuce!
    • 0.3.2 - Use face.color instead of face.vertexColors[0]
    • 0.3.1 - Support for animated materials.
    • 0.3.0 - refactored entire module. removed rotate. added load, get, paint, sprite methods. auto detect transparent.
    • 0.2.2 - ability to set material type and params. thanks @hughsk!
    • 0.2.1 - fix rotation of front and left textures when loading mesh
    • 0.2.0 - ability to set multiple textures on voxel meshes
    • 0.1.1 - fix texture sharpness
    • 0.1.0 - initial release


    Copyright (c) 2013 Kyle Robinson Young
    Licensed under the MIT license.




    npm i voxel-texture

    Downloadsweekly downloads








    last publish


    • avatar