@three.ez/instanced-mesh v0.1.3

three.ez - InstancedMesh2

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+.

🔑 Key Features

🛠️ Meshes Instances

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

🎥 Frustum Culling

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);

⬇️ Installation

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>

🧑‍💻 Live Examples

These examples use vite, and some mobile devices may run out of memory.

• CullingStatic 1kk Forest
• CullingDynamic 150k
• CullingStatic Custom Attribute

📚 Documentation

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'.

🤝 Contributing

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.

❔ Questions?

If you have questions or need assistance, you can ask on our discord server.

👀 Future Work

• BVH customization
• Dynamic BVH
• Sorting support
• Improve raycasting if CullingStatic

⭐ Like it?

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.