This GitHub repository introduces Enhanced InstancedMesh2, an advanced version of Three.js's InstancedMesh that streamlines application development with improved performance and functionality. It offers per-instance frustum culling, fast BVH-based raycasting, sorting, individual visibility management, and even LOD support, all while treating each instance like a lightweight Object3D for simplified manipulation.

Explore the repository on GitHub:
github.com

GitHub Repository Overview

This project provides an alternative InstancedMesh solution with the following advantages:

• Per-instance frustum culling
• Efficient BVH-accelerated raycasting
• Instance sorting for reduced overdraw
• Individual visibility controls
• Easy-to-use Object3D-like instance management
• Spatial indexing via BVH for rapid culling and raycasting

Below is an example of how to initialize and update instances using InstancedMesh2:

TYPESCRIPTCopied
import { InstancedMesh2 } from '@three.ez/instanced-mesh';

const myInstancedMesh = new InstancedMesh2(renderer, count, geometry, material);

myInstancedMesh.updateInstances((obj, index) => {
  obj.position.z = index;
  obj.rotateY(Math.PI);
});

myInstancedMesh.computeBVH();

This library depends solely on three.js (r159+).

Live Examples

The following live examples (using vite) demonstrate various features. Note that mobile devices may run out of memory with some examples:

• 1kk static trees
• Instances array dynamic
• Sorting
• Custom material
• Dynamic BVH (no vite)
• Fast raycasting

More examples will be added soon…

Frustum Culling

Avoid rendering objects outside the camera’s frustum to dramatically boost performance, especially with complex geometries. By default, frustum culling iterates over all instances, but you can optimize this with a spatial indexing BVH.

Note: The default for perObjectFrustumCulled is true.

Sorting

Sort instances to reduce overdraw and correctly render transparent objects. By default, sortObjects is set to false.

TYPESCRIPTCopied
import { createRadixSort } from '@three.ez/instanced-mesh';

myInstancedMesh.sortObjects = true;
myInstancedMesh.customSort = createRadixSort(myInstancedMesh);

Visibility Management

You can manage each instance’s visibility individually:

TYPESCRIPTCopied
myInstancedMesh.setVisibilityAt(false, 0);
myInstancedMesh.instances[0].visible = false; // if instances array is created

Using an Instances Array

An array of InstancedEntity (similar to Object3D) can be created for easier manipulation, at the cost of higher memory usage:

TYPESCRIPTCopied
myInstancedMesh.createInstances((obj, index) => {
  obj.position.random();
});

myInstancedMesh.instances[0].visible = false;

myInstancedMesh.instances[1].userData = {};

myInstancedMesh.instances[2].position.random();
myInstancedMesh.instances[2].quaternion.random();
myInstancedMesh.instances[2].scale.random();
myInstancedMesh.instances[2].updateMatrix(); // necessary after transformations

myInstancedMesh.instances[3].rotateX(Math.PI);
myInstancedMesh.instances[3].updateMatrix(); // necessary after transformations

Spatial Indexing (Dynamic BVH)

Create a spatial indexing structure to store bounding boxes for fast raycasting and frustum culling. This is especially useful when instances are mostly static. After setting instance values, compute the BVH as follows:

TYPESCRIPTCopied
// call this function after all instances have been valued
myInstancedMesh.computeBVH({ margin: 0, highPrecision: false });

For static instances, set the margin to 0. A non-zero margin speeds up BVH updates, although it might slightly slow down raycasting and culling.

Raycasting Tips

If not using BVH, set the raycastOnlyFrustum property to true to skip iterating over every instance. It’s also recommended to use three-mesh-bvh for creating a geometry BVH.

API Documentation

Detailed API information is available in the repository. This includes the definitions for InstancedMesh2, InstancedEntity, and various utility functions (patchShader, createRadixSort, and texture creation helpers).

How It Works

Internally, InstancedMesh2 stores matrices, colors, and other data in textures rather than InstancedBufferAttributes. The only attribute stored is the instance index, making it efficient yet flexible. When using custom materials, use the provided utility methods to work with textures instead of attributes.

Installation Instructions

You can install the package via npm:

BASHCopied
npm install @three.ez/instanced-mesh

Or import it from a CDN:

HTMLCopied
<script type="importmap">{
  "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.167.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.167.0/examples/jsm/",
    "@three.ez/instanced-mesh": "https://cdn.jsdelivr.net/npm/@three.ez/instanced-mesh/index.js",
    "bvh.js": "https://cdn.jsdelivr.net/npm/bvh.js/index.js"
  }
}</script>

Questions & Future Work

If you have any questions, feel free to ask on our Discord server. Planned improvements include a LOD system and removing the renderer parameter from the constructor.

Appreciation & Special Thanks

If you find the project helpful, please star the repository to show your support. Special thanks to contributors like gkjohnson, manthrax, and jungle_hacker.

References

• three-mesh-bvh
• ErinCatto_DynamicBVH
• BatchedMesh