Customizing Instanced Mesh Attributes in Three.js

Instanced meshes in Three.js allow you to efficiently render multiple copies of a geometry with shared material properties, reducing draw calls and improving performance. However, real-world applications often require each instance to have unique attributes, such as different colors or material properties. This article will guide you through customizing instanced meshes with per-instance attributes.

1. Setting Up the Instanced Mesh

Start by creating an InstancedMesh object with a shared geometry and material. For example:

let instMesh = new THREE.InstancedMesh(geometry, material, instanceCount);

the mesh being instanced can be an imported GLTF/GLB model or a primitive made by the use of THREE.Mesh().

2. Defining Per-Instance Attributes

Attributes like color, metalness, or roughness can be stored in InstancedBufferAttributes, which are arrays containing data for each instance:

let colors = new Float32Array(instanceCount * 3); // RGB values
let metalness = new Float32Array(instanceCount); // Metalness values
let roughness = new Float32Array(instanceCount); // Roughness values

You can assign values to these attributes for each instance. For example:

for (let i = 0; i < instanceCount; i++) {
  colors.set([Math.random(), Math.random(), Math.random()], i * 3); // Random color
  metalness[i] = Math.random(); // Random metalness
  roughness[i] = Math.random(); // Random roughness
}

Attach these attributes to the geometry:

instMesh.geometry.setAttribute(
  "instanceColor",
  new THREE.InstancedBufferAttribute(colors, 3)
);
instMesh.geometry.setAttribute(
  "instanceMetalness",
  new THREE.InstancedBufferAttribute(metalness, 1)
);
instMesh.geometry.setAttribute(
  "instanceRoughness",
  new THREE.InstancedBufferAttribute(roughness, 1)
);

3. Modifying the Shader

To use these custom attributes, modify the vertex and fragment shaders. Access the per-instance attributes using attribute keywords in the vertex shader and pass them to the fragment shader via varying variables.

Add Custom Attributes

In the vertex shader:

attribute vec3 instanceColor;
attribute float instanceMetalness;
attribute float instanceRoughness;

varying vec3 vInstanceColor;
varying float vInstanceMetalness;
varying float vInstanceRoughness;

void main() {
  vInstanceColor = instanceColor;
  vInstanceMetalness = instanceMetalness;
  vInstanceRoughness = instanceRoughness;
  
  // Existing transformations
  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}

In the fragment shader:

varying vec3 vInstanceColor;
varying float vInstanceMetalness;
varying float vInstanceRoughness;

void main() {
  vec3 color = vInstanceColor;
  float metalness = vInstanceMetalness;
  float roughness = vInstanceRoughness;

  // Combine with lighting calculations (example)
  gl_FragColor = vec4(color * metalness, 1.0);
}

4. Applying the Custom Shader

Override the material’s default shader to include these modifications:

instMesh.material.onBeforeCompile = (shader) => {
  shader.vertexShader = `
    attribute vec3 instanceColor;
    attribute float instanceMetalness;
    attribute float instanceRoughness;
    varying vec3 vInstanceColor;
    varying float vInstanceMetalness;
    varying float vInstanceRoughness;
  ` + shader.vertexShader;

  shader.fragmentShader = `
    varying vec3 vInstanceColor;
    varying float vInstanceMetalness;
    varying float vInstanceRoughness;
  ` + shader.fragmentShader;

  shader.vertexShader = shader.vertexShader.replace(
    "#include <begin_vertex>",
    `
    #include <begin_vertex>
    vInstanceColor = instanceColor;
    vInstanceMetalness = instanceMetalness;
    vInstanceRoughness = instanceRoughness;
    `
  );

  shader.fragmentShader = shader.fragmentShader.replace(
    "vec3 diffuseColor = diffuse.rgb;",
    "vec3 diffuseColor = vInstanceColor;"
  );

  shader.fragmentShader = shader.fragmentShader.replace(
    "#include <roughnessmap_fragment>",
    "roughnessFactor = vInstanceRoughness;"
  );

  shader.fragmentShader = shader.fragmentShader.replace(
    "#include <metalnessmap_fragment>",
    "metalnessFactor = vInstanceMetalness;"
  );
};

5. Rendering the Instanced Mesh

Finally, add the instanced mesh to the scene and render it as usual:

scene.add(instMesh);
renderer.render(scene, camera);

Conclusion

By leveraging InstancedBufferAttributes and customizing shaders, you can achieve highly dynamic and visually diverse scenes while maintaining optimal performance. This approach is especially beneficial for games and simulations that involve rendering large numbers of objects with distinct properties.