Introduction

InstancedMesh2 is an enhanced alternative to InstancedMesh, offering improved performance and usability with features such as:

• Per-instance frustum culling – Skips rendering for out-of-view instances.
• Sorting – Reduces overdraw and efficiently manages transparent objects.
• Spatial indexing (dynamic BVH) – Speeds up raycasting and frustum culling.
• Dynamic capacity – Seamlessly add or remove instances.
• Per-instance visibility and opacity – Individually toggle visibility and set opacity.
• Object3D-like instances – Instances behave like Object3D, supporting transforms and custom data.
• Per-instance uniforms – Assign unique shader data to individual instances.
• Level of Detail (LOD) – Dynamically adjust instance detail based on distance.
• Shadow LOD – Optimize shadow rendering by reducing detail for distant instances.
• Skinning – Apply skeletal animations for complex and dynamic movements.

Note

Currently, InstancedMesh2 only works with WebGLRenderer and requires three.js r159+.

Differences from InstancedMesh

InstancedMesh

• Uses an InstancedBufferAttribute to store instance matrices and data.
• Renders instances sequentially, meaning all instances are processed in the order they were added, without skipping or reordering. This can be inefficient when dealing with a large number of instances, especially if many are off-screen or require different sorting orders for transparency.

InstancedMesh2

• Uses SquareDataTexture (an extended version of DataTexture supporting partial updates) to store instance matrices and data.
• Uses an InstancedBufferAttribute to manage the indexes of instances to be rendered, allowing for selective rendering, efficient culling, and sorting before sending data to the GPU.

Note

Due to this additional indirection, rendering all instances is slightly slower.
However, the benefits of efficient culling and sorting often outweigh the minor overhead.
If none of the extra features are needed, using InstancedMesh is recommended.