Simplify your three.js application development with three.ez!
InstancedMesh2
extends the functionality of InstancedMesh
, providing streamlined control over instance transformations
and visibility
, while also integrating frustum culling
for each instance to improve performance.
import { CullingDynamic, InstancedMesh2 } from '@three.ez/instanced-mesh';
const myInstancedMesh = new InstancedMesh2(geometry, material, count, {
behaviour: CullingDynamic,
onInstanceCreation: (obj, index) => {
obj.position.random();
obj.scale.setScalar(2);
obj.quaternion.random();
}
});
myInstancedMesh.instances[0].visible = false;
myInstancedMesh.instances[1].rotateX(Math.PI);
myInstancedMesh.instances[1].updateMatrix(); // necessary after transformations
This library has only one dependency: three.js r159+
.
Each mesh has its own instance accessible through the instances
property.
You can easily modify visibility, apply transformations, and add custom data to each mesh instance.
myInstancedMesh.instances[0].visible = false;
myInstancedMesh.instances[1].customData = {};
myInstancedMesh.instances[2].position.random();
myInstancedMesh.instances[2].quaternion.random();
myInstancedMesh.instances[2].scale.random();
myInstancedMesh.instances[2].updateMatrix(); // necessary after transformations
InstancedMesh2 offers three different behaviors for frustum culling:
- CullingNone: Frustum culling is disabled, suitable if all instances are always visible in the camera's frustum.
-
CullingStatic: Fast frustum culling using a BVH, ideal for static objects (you can only modify instances in
onInstanceCreation
callback). - CullingDynamic: Individual frustum culling for each instance, necessary for animated meshes.
const myInstancedMesh = new InstancedMesh2(geometry, material, count, {
behaviour: CullingStatic, // specify behavior here
onInstanceCreation
});
If you use CullingStatic or CullingDynamic, remember to call updateCulling
function before rendering.
camera.updateMatrixWorld(true);
myInstancedMesh.updateCulling(camera);
You can install it via npm using the following command:
npm install @three.ez/instanced-mesh
Or you can import it from CDN:
<script type="importmap">
{
"imports": {
"three": "https://unpkg.com/three@0.162.0/build/three.module.js",
"three/examples/jsm": "https://unpkg.com/three@0.162.0/examples/jsm/",
"@three.ez/instanced-mesh": "https://unpkg.com/@three.ez/instanced-mesh@0.1.2/bundle.js"
}
}
</script>
These examples use vite
, and some mobile devices may run out of memory.
The API documentation is available here. Automatic documentation also included patched properties and methods from other libraries in the repository. Please ignore properties and methods not defined within 'InstancedMesh2.ts'.
Any help is highly appreciated. If you would like to contribute to this package or report problems, feel free to open a bug or pull request.
If you have questions or need assistance, you can ask on our discord server.
- BVH customization
- Dynamic BVH
- Sorting support
- Improve raycasting if CullingStatic
If you find this project helpful, I would greatly appreciate it if you could leave a star on this repository!
This helps me know that you appreciate my work and encourages me to continue improving it.
Thank you so much for your support! 🌟
Special thanks to three-mesh-bvh.