Three.ez - BatchedMesh extensions

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

three.ez/instanced-mesh - Enhanced InstancedMesh with features for performance and usability

This library adds and overrides some BatchedMesh methods to improve performance and add new features.

// Extends batchedMesh prototype with new methods
extendBatchedMeshPrototype();

// Calculate the number of vertices and indices for a batchedMesh and create it
const { vertexCount, indexCount } = getBatchedMeshCount(geometries);
const batchedMesh = new BatchedMesh(instanceCount, vertexCount, indexCount, material);

// Add geometries
const geoId = batchedMesh.addGeometry(geometries[geometryIndex]);

// Add instances
const instanceId = batchedMesh.addInstance(geoId);

// Compute the BVH to accelerate raycasting and frustum culling after adding all instances
batchedMesh.computeBVH();

Spatial indexing (dynamic BVH): speed up raycasting and frustum culling.
Per-instance uniforms: assign unique shader data to individual instances. (WebGLRenderer only)
Level of Detail (LOD): dynamically adjust instance detail based on distance.

Live Examples

Using three.js vanilla

Will be added in the future. Or you consider to contribute with a PR.

Using three.ez/main (WebGLRenderer)

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:

npm install @three.ez/batched-mesh-extensions

Or you can import it from CDN:

WebGLRenderer

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

WebGPURenderer

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

Extend BatchedMesh prototype

To extend the BatchedMesh prototype with the new methods, you need to call the extendBatchedMeshPrototype() method at the top of your application.

import { extendBatchedMeshPrototype } from '@three.ez/batched-mesh-extensions';

extendBatchedMeshPrototype();

For more advanced use, it's also possible to manually update the BatchedMesh prototype because the new methods are all exported.

Features

Spatial indexing (dynamic BVH)

To speed up raycasting and frustum culling, a spatial indexing data structure can be created to contain the bounding boxes 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.

myBatchedMesh.computeBVH(renderer.coordinateSystem, { margin: 0 }); // margin is optional

It's necessary to manually update the BVH after its creation with the following methods:

myBatchedMesh.bvh.insert(instanceId);
myBatchedMesh.bvh.insertRange(instanceIdsArray);
myBatchedMesh.bvh.move(instanceId);
myBatchedMesh.bvh.delete(instanceId);
myBatchedMesh.bvh.clear();

Per-instance uniforms (WebGLRenderer only)

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

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

myBatchedMesh.setUniformAt(index, 'noise', 0.5);
myBatchedMesh.setUniformAt(index, 'emissive', new Color('red'));

Level of Detail (LOD)

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.

Currently, only LODs that share the same geometry vertex array can be added. This will improve in the future.

const geometryId = batchedMesh.addGeometry(geometry, -1, reservedIndexCount);
batchedMesh.addGeometryLOD(geometryId, geometryLOD1, distanceLOD1);
batchedMesh.addGeometryLOD(geometryId, geometryLOD2, distanceLOD2);
batchedMesh.addGeometryLOD(geometryId, geometryLOD3, distanceLOD3);