Instanced Mesh

Step 1 -- Declare the InstancedMesh

Tell R3F what shape to stamp, what material to use, and how many copies you need. Pass undefined for geometry and material since you provide them as children.

<instancedMesh ref={meshRef} args={[undefined, undefined, 1000]}>
  <boxGeometry args={[0.5, 0.5, 0.5]} />
  <meshStandardMaterial color="#6c5ce7" />
</instancedMesh>

The third value in args is the instance count. This tells the GPU how much buffer space to allocate up front.

Step 2 -- Position each instance with a dummy Object3D

You cannot set position directly on each instance. Instead, use a temporary Object3D as a stamp -- set its position, bake its matrix, and hand that matrix to the InstancedMesh.

const dummy = useMemo(() => new THREE.Object3D(), [])

useEffect(() => {
  for (let i = 0; i < 1000; i++) {
    dummy.position.set(
      (Math.random() - 0.5) * 20,
      (Math.random() - 0.5) * 20,
      (Math.random() - 0.5) * 20
    )
    dummy.updateMatrix()
    meshRef.current.setMatrixAt(i, dummy.matrix)
  }
  meshRef.current.instanceMatrix.needsUpdate = true
}, [dummy])

Notice the two critical lines at the end: dummy.updateMatrix() bakes position/rotation/scale into a 4x4 matrix, and needsUpdate = true ships that data to the GPU.

Step 3 -- Give each instance its own color

Optionally, you can assign a unique color to every instance using setColorAt(). Just remember to flip the color buffer's needsUpdate flag too.

const color = useMemo(() => new THREE.Color(), [])

useEffect(() => {
  for (let i = 0; i < 1000; i++) {
    color.setHSL(i / 1000, 0.8, 0.5)
    meshRef.current.setColorAt(i, color)
  }
  meshRef.current.instanceColor.needsUpdate = true
}, [color])

One gotcha: the base material color multiplies with instance colors. If your material is black, everything stays black. Use white or omit the color prop on the material.