Three.ez - InstancedMesh2

Simplify your three.js application development with three.ez!

three.ez/batched-mesh-extensions - BatchedMesh extension methods and enhancements for better performance and usability

![Discord](https://discord.gg/MVTwrdX3JM)
![npm](https://www.npmjs.com/package/@three.ez/instanced-mesh)
![Stars](https://github.com/three-ez/instanced-mesh)
![BundlePhobia](https://bundlephobia.com/package/@three.ez/instanced-mesh)
![Quality Gate Status](https://sonarcloud.io/summary/new_code?id=agargaro_instanced-mesh)
![DeepScan grade](https://deepscan.io/dashboard#view=project&tid=21196&pid=27990&bid=896898)

InstancedMesh2 is an alternative version of InstancedMesh with enhanced features for performance and usability.

``

ts

const myInstancedMesh = new InstancedMesh2(geometry, material);



myInstancedMesh.addInstances(count, (obj, index) => {

  obj.position.x = index;

});





- Dynamic capacity: add or remove instances seamlessly.

- Object3D-like instances: use instances like

Object3D with transforms and custom data.



- Per-instance frustum culling: skip rendering for out-of-view instances.

- Spatial indexing (dynamic BVH): speed up raycasting and frustum culling.

- Sorting: reduce overdraw and manage transparent objects efficiently.

- Per-instance visibility: toggle visibility for each instance individually.

- Per-instance opacity: set opacity for each instance individually.

- 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 with lower detail for distant instances.

- Skinning: apply skeletal animations to instances for more complex and dynamic movements.



🧑‍💻 Live Examples



Vanilla

-  Dynamic adding with BVH (thanks to Saumac)



Using three.ez/main

-  1kk static trees

-  Instances array dynamic

-  Sorting

-  Uniforms per instance

-  Dynamic BVH (no vite)

-  Fast raycasting

-  LOD

-  Shadow LOD

-  Skinning 3k instances

-  Dynamic adding with BVH

-  Skinning



Using other libraries

- Threlte

-  Tres.js (thanks to JaimeTorrealba)

-  React-three-fiber (thanks to Saumac)

-  React-three-fiber (thanks to Lunakepio)



❔ Need help?



Join us on Discord or open an issue on GitHub.



⭐ Like it?



If you like this project, please leave a star. Thank you! ❤️



📚 Documentation



The documentation is available here.



⬇️ Installation



You can install it via npm using the following command:

bash

npm install @three.ez/instanced-mesh





Or you can import it from CDN:

html





🚀 Features



$3



Manage a dynamic number of instances, automatically expanding the data buffers as needed to accommodate additional instances. 




If not specified,

capacity is 1000

ts

const myInstancedMesh = new InstancedMesh2(geometry, material, { capacity: count }); 



myInstancedMesh.addInstances(count, (obj, index) => { ... }); // add instances and expand buffer if necessary



myInstancedMesh.removeInstances(id0, id1, ...);



myInstancedMesh.clearInstances(); // remove all instances





$3



It's possible to create an array of

InstancedEntity

 (Object3D-like) in order to easily manipulate instances, using more memory.

ts

const myInstancedMesh = new InstancedMesh2(geometry, material, { createEntities: true });



myInstancedMesh.instances[0].customData = {};

myInstancedMesh.instances[0].position.random();

myInstancedMesh.instances[0].rotateX(Math.PI);

myInstancedMesh.instances[0].updateMatrix(); // necessary after transformations

  



$3



Avoiding rendering objects outside the camera frustum can drastically improve performance (especially for complex geometries). 


Frustum culling by default is performed by iterating all instances, but it is possible to speed up this process by creating a spatial indexing data structure (BVH). 




By default

perObjectFrustumCulled is true

.



$3



To speed up raycasting and frustum culling, a spatial indexing data structure can be created to contain the boundingBoxes of all instances. 


This works very well if the instances are mostly static (updating a BVH can be expensive) and scattered in world space. 




Setting a margin makes BVH updating faster, but may make raycasting and frustum culling slightly slower.

ts

myInstancedMesh.computeBVH({ margin: 0 }); // margin is optional





$3



Sorting can be used to decrease overdraw and render transparent objects. 




It's possible to improve sort performance adding a

customSort, like built-in createRadixSort

.



By default

sortObjects is false

ts

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



myInstancedMesh.sortObjects = true;

myInstancedMesh.customSort = createRadixSort(myInstancedMesh);





$3



Set the visibility status of each instance.

ts

myInstancedMesh.setVisibilityAt(index, false);

myInstancedMesh.instances[0].visible = false; // if instances array is created





$3



Set the opacity of each instance. It's recommended to enable instances sorting and disable the

depthWriting

 of the material.

ts

myInstancedMesh.setOpacityAt(index, 0.5);

myInstancedMesh.instances[0].opacity = 0.5; // if instances array is created

   



$3



Assign unique shader uniforms to each instance, working with every materials.

ts

myInstancedMesh.initUniformsPerInstance({ fragment: { metalness: 'float', roughness: 'float', emissive: 'vec3' } });



myInstancedMesh.setUniformAt(index, 'metalness', 0.5);

myInstancedMesh.instances[0].setUniform('emissive', new Color('white')); // if instances array is created





$3



Improve rendering performance by dynamically adjusting the detail level of instances based on their distance from the camera. 


Use simplified geometries for distant objects to optimize resources.

ts

myInstancedMesh.addLOD(geometryMid, material, 50);

myInstancedMesh.addLOD(geometryLow, material, 200);

     



$3



Optimize shadow rendering by reducing the detail level of instances casting shadows based on their distance from the camera.

ts

myInstancedMesh.addShadowLOD(geometryMid);

myInstancedMesh.addShadowLOD(geometryLow, 100);

    



$3



Apply skeletal animations to instances for more complex and dynamic movements.

ts

myInstancedMesh.initSkeleton(skeleton);



mixer.update(time);

myInstancedMesh.setBonesAt(index);

   



$3



If you are not using a BVH, you can set the

raycastOnlyFrustum` property to true to avoid iterating over all instances.

It's recommended to use three-mesh-bvh to create a geometry BVH.

🤝 Special thanks to

- gkjohnson
- manthrax
- jungle_hacker

📖 References

- three-mesh-bvh
- ErinCatto_DynamicBVH