Skip to content
wrapper around THREE.InstancedBufferGeometry
JavaScript HTML
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.
monkey-patch update readme Dec 27, 2017
.gitignore update readme Dec 27, 2017
LICENSE add license Jan 11, 2018
example.js update readme Dec 27, 2017
package-lock.json 0.96.2 Dec 18, 2018
package.json 0.96.2 Dec 18, 2018


Higher level abstraction of THREE.InstancedBufferGeometry for three.js. For a webgl level overview check out TojiCode. For a more in depth overview on how this works, i've written an article more or less on how to build this from scratch.


The signature for THREE.InstancedBufferAttribute changed with version R96. 0.96.0 of this package should work with >= R96, the previous one with the older. 0.96.1 should work with all versions of three.



.setPositionAt( index: Int , position: THREE.Vector3 )

Updates the position attribute at given index.

.setQuaternionAt( index: Int , quaternion: THREE.Quaternion )

Updates the quaternion attribute at given index.

.setScaleAt( index: Int , scale: THREE.Vector3 )

Updates the scale attribute at given index.

.setColorAt( index: Int , color: THREE.Color )

Updates the color attribute at given index if instance colors are enabled.

.getPositionAt( index: Int , target: THREE.Vector3)

Write value from position attribute at index into target THREE.Vector3.

.getQuaternionAt( index: Int , target: THREE.Quaternion)

Write value from quaternion attribute at index into target THREE.Quaternion.

.getScaleAt( index: Int , target: THREE.Vector3)

Write value from scale attribute at index into target THREE.Vector3.

.getColorAt( index: Int , target: THREE.Color)

Write value from color attribute at index into target THREE.Color if instance colors are enabled.

.needsUpdate( attributeName: String )

Set appropriate attribute needsUpdate flags. If attributeName is omitted all of the attributes will be marked for updates. Valid names are position, quaternion, scale, colors.


All of these have some side effects. This should probably be revisited but here are some notes:

.material: THREE.Material

Whenever you set myInstanceMesh.material = material the material will be cloned and decorated with the instancing flags. This is supposed to make it simple to use, but is quite a side effect.

.numInstances: Int

Number of instances, when this changes the attributes need to be reinstantiated.

.geometry: THREE.BufferGeometry

If regular BufferGeometry is passed, this will create an instance of InstancedBufferGeometry and copy the attributes into it.

what it should do

Provide an abstraction for relatively low level THREE.InstancedBufferGeometry, allows for the instancing attributes to be setup by a "placement function" and converts a regular buffer geometry to instanced. This is a modified example running 30k objects instead of 5. All of the objects should be drawn with one draw call, thus speeding things up. It does a simple transformation of normals to view space if the instances are known to be uniformly scaled. If not, it does a mat3 inversion on the gpu (yikes!) but it works.

So for example, if you have static world assets that need to be scattered, you can group them with this thus saving a bit of memory (over merging) and a bit of overhead ( less draw calls ). You should still probably take care of how the assets are grouped so they could be culled. The class computes no bounding information. Swithing to different geometries should be really fast since only one is uploaded to the gpu, it shouldn't stutter much when initializing new geometry (when you first change the box to a sphere in the example).

In order to pull this off with three.js you need some 400 lines of code as per this example.

how it works

  • Including the module will allow the usage of THREE.InstancedMesh constructor. This will also patch different shader chunks to attach the instancing logic to THREE.ShaderChunks{} (overrides certain chunks).
  • A THREE.InstancedBufferGeometry is instantiated and the provided THREE.BufferGeometry argument copied into it (instancing only works on InstancedBufferGeometry).
  • Three optimization flags - dynamic, uniformScale and colors are set. These should only be provided upon construction. color would instantiate another buffer which is wasteful if not used, uniform would require a shader recompilation (when false it uses a branch in glsl to do a heavy matrix computation), dynamic sets a buffer of a different type and is a property of THREE.BufferGeometry.
  • Instancing attributes are set taking these flags into consideration (instancePosition,instanceQuaternion and instanceScale are always created, instanceColor depends on the flag). Their arrays are not instantiated. The idea behind this is noble, why do any work you are going to make reduntant right away. Scale on the other hand can likely be just 1,1,1, maybe an optional method to "init" the mesh should be provided? Please give feedback
  • The provided material is cloned. It needs to be decorated with defines, customDistanceMaterial and customDepthMaterial in order to allow for instancing to interact with the rest of three's rendering logic that relies on depth (shadows, AO...). Three manages the default materials under the hood of THREE.WebGLRenderer. Internally it holds a cache of shader programs which are created based on the properties of a Material (and other stuff like lights). In order to not alter the renderer. This is all done here through a fancy .material setter, which is not the most elegant solution. Please provide feedback and use cases.
  • Methods are used to fill buffers.



//var InstancedMesh = require('three-instanced-mesh')( THREE ); //should replace shaders on first call

//or just patch three
require( 'three-instanced-mesh' )(THREE);

//geometry to be instanced
var boxGeometry = new THREE.BoxBufferGeometry(2,2,2,1,1,1);

//material that the geometry will use
var material = new THREE.MeshPhongMaterial();

//the instance group
var cluster = new THREE.InstancedMesh( 
  boxGeometry,                 //this is the same 
  10000,                       //instance count
  false,                       //is it dynamic
  false                        //does it have color
  true,                        //uniform scale, if you know that the placement function will not do a non-uniform scale, this will optimize the shader

var _v3 = new THREE.Vector3();
var _q = new THREE.Quaternion();

for ( var i = 0 ; i < 10000 ; i ++ ) {
  cluster.setQuaternionAt( i , _q );
  cluster.setPositionAt( i , _v3.set( Math.random() , Math.random(), Math.random() ) );
  cluster.setScaleAt( i , _v3.set(1,1,1) );


scene.add( cluster );

please provide feedback or examples use cases:)

A man once stopped me in the street down in the TenderLoin and asked me "What's the best nation?" and I said "Giants!" thinking he said "Who's the best in the nation?". The answer was "Donation". If you find this useful you can totally support it by donating to my pizza budget :)

You can’t perform that action at this time.