Applying Unique Textures to Instances in Three.js

I need to stay on topic and address your question about applying different textures to instances in Three.js.

There are several approaches you can take to assign unique textures to instances while still benefiting from instanced rendering:

1. Texture Atlas

The most common and efficient approach is to use a texture atlas - a single large texture containing all your individual textures arranged in a grid. Then use UV coordinates to select which part of the atlas each instance should display.

JAVASCRIPTCopied
// Create a shader material that can work with instancing
const material = new THREE.ShaderMaterial({
  uniforms: {
    textureAtlas: { value: atlasTexture },
    textureSize: { value: new THREE.Vector2(atlasWidth, atlasHeight) },
    textureTileCount: { value: new THREE.Vector2(tilesX, tilesY) }
  },
  vertexShader: `
    attribute vec2 textureIndex; // Which texture in the atlas to use
    varying vec2 vUv;
    varying vec2 vTextureIndex;
    
    void main() {
      vUv = uv;
      vTextureIndex = textureIndex;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform sampler2D textureAtlas;
    uniform vec2 textureSize;
    uniform vec2 textureTileCount;
    varying vec2 vUv;
    varying vec2 vTextureIndex;
    
    void main() {
      // Calculate the offset in the atlas
      vec2 tileSize = 1.0 / textureTileCount;
      vec2 offset = tileSize * vTextureIndex;
      
      // Adjust UVs to sample from the correct tile
      vec2 adjustedUv = offset + vUv * tileSize;
      
      gl_FragColor = texture2D(textureAtlas, adjustedUv);
    }
  `
});

// Set up the instanced mesh
const geometry = new THREE.PlaneGeometry(1, 1);
// Add the texture index attribute
const textureIndices = new Float32Array(instanceCount * 2);
for (let i = 0; i < instanceCount; i++) {
  // Set which texture this instance should use (x, y coordinates in the atlas)
  textureIndices[i * 2] = i % tilesX;
  textureIndices[i * 2 + 1] = Math.floor(i / tilesX) % tilesY;
}

geometry.setAttribute('textureIndex', new THREE.InstancedBufferAttribute(textureIndices, 2));

const instancedMesh = new THREE.InstancedMesh(geometry, material, instanceCount);

2. Array Texture

If your platform supports it, you can use a DataArrayTexture which is specifically designed for this purpose:

JAVASCRIPTCopied
// Create an array texture with all your textures
const arrayTexture = new THREE.DataArrayTexture(
  pixelData,  // Combined pixel data from all textures
  width,      // Width of each texture
  height,     // Height of each texture
  textureCount // Number of textures
);
arrayTexture.needsUpdate = true;

// Create a shader material that uses the array texture
const material = new THREE.ShaderMaterial({
  uniforms: {
    textureArray: { value: arrayTexture }
  },
  vertexShader: `
    attribute float textureIndex;
    varying float vTextureIndex;
    varying vec2 vUv;
    
    void main() {
      vTextureIndex = textureIndex;
      vUv = uv;
      gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
    }
  `,
  fragmentShader: `
    uniform sampler2DArray textureArray;
    varying float vTextureIndex;
    varying vec2 vUv;
    
    void main() {
      gl_FragColor = texture(textureArray, vec3(vUv, vTextureIndex));
    }
  `
});

// Add the texture index attribute to your geometry
const textureIndices = new Float32Array(instanceCount);
for (let i = 0; i < instanceCount; i++) {
  textureIndices[i] = i % textureCount; // Which texture to use
}

geometry.setAttribute('textureIndex', new THREE.InstancedBufferAttribute(textureIndices, 1));

3. Multiple Draw Calls

If you have a smaller number of unique textures, you can group instances by texture and render each group with a separate draw call:

JAVASCRIPTCopied
// Group your instances by texture
const textureGroups = {};

for (let i = 0; i < instanceCount; i++) {
  const textureId = /* determine which texture this instance uses */;
  if (!textureGroups[textureId]) {
    textureGroups[textureId] = [];
  }
  textureGroups[textureId].push(i);
}

// Create an instanced mesh for each texture
Object.entries(textureGroups).forEach(([textureId, instances]) => {
  const material = new THREE.MeshBasicMaterial({
    map: textures[textureId]
  });
  
  const instancedMesh = new THREE.InstancedMesh(
    geometry, 
    material, 
    instances.length
  );
  
  // Set instance matrices
  instances.forEach((originalIndex, newIndex) => {
    const matrix = new THREE.Matrix4();
    // Set position, rotation, scale for this instance
    instancedMesh.setMatrixAt(newIndex, matrix);
  });
  
  instancedMesh.instanceMatrix.needsUpdate = true;
  scene.add(instancedMesh);
});

The texture atlas approach is generally the most efficient for a large number of instances with different textures, as it maintains the performance benefits of instancing while allowing texture variation.