@three.ez/instanced-mesh Documentation

InstancedMesh2 is an enhanced implementation of Three.js InstancedMesh designed to provide advanced features for managing large numbers of instances efficiently. Key capabilities include:

• Frustum Culling: Per-instance frustum culling to improve rendering performance.
• Fast Raycasting: High-performance raycasting using a Bounding Volume Hierarchy (BVH).
• Dynamic Capacity: Ability to manage instance counts dynamically.
• Object3D-like Instances: Provides an interface for instances that behaves similarly to standard Object3D objects.
• Spatial Indexing: Uses a dynamic BVH for spatial queries.
• Advanced Rendering Controls: Supports sorting, per-instance visibility, Level of Detail (LOD), and skinning.

By setting createEntities: true in the constructor, you can access an array of InstancedEntity objects. These entities behave like Object3D, allowing you to manipulate transforms (position, rotation, scale) and custom data directly.

Important: You must call .updateMatrix() after performing transformations to apply changes to the instance.

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

The library uses two different methods for performing frustum culling every frame:

1. Linear (default): Iterates through every instance and checks if its boundingSphere is inside the camera's frustum. This is best for dynamic scenarios. Note that linear culling works more efficiently if the geometry is centered.
2. BVH: If a Bounding Volume Hierarchy (BVH) has been built, the algorithm recursively iterates through the nodes. If a node is outside the frustum, the entire node and its children are discarded. This is best for mostly static scenarios.

To update a specific instance, access it via the instances array of your InstancedMesh. After modifying properties like position, scale, or quaternion, you must call .updateMatrix() to apply the changes to the instance's transformation.

Performance Tip: If you are only modifying the position property, use .updateMatrixPosition() instead of .updateMatrix() to improve performance.

iMesh.instances[index].position.random();
iMesh.instances[index].rotateX(Math.PI);
iMesh.instances[index].updateMatrix(); // Required after transformations

By default, InstancedEntity handles rotation using quaternion to avoid the computational overhead of synchronizing quaternion and rotation (Euler angles).

If your workflow requires using Euler angles, you can enable the rotation property by setting the allowsEuler flag to true in the InstancedMesh2 constructor options. Note that enabling this introduces a minor performance trade-off because the library must perform additional synchronization to keep both representations consistent.

const iMesh = new InstancedMesh2(geo, mat, { createEntities: true, allowsEuler: true });

To create a new InstancedMesh2, instantiate it by passing a geometry and a material. This object will manage the rendering of multiple instances using the provided geometry and material.

const iMesh = new InstancedMesh2(geometry, material);

You can add instances to an InstancedMesh2 without pre-specifying a length; the underlying buffers will automatically expand as needed. To optimize performance by setting a specific initial buffer capacity, provide the capacity option in the constructor parameters.

When calling addInstances, you provide the number of instances to add and a callback function. The callback receives the instance object (which behaves like an Object3D) and its index, allowing you to initialize its properties (like position or rotation) immediately.

// Set initial capacity
const iMesh = new InstancedMesh2(geo, mat, { capacity: 10000 });

// Add instances with initialization logic
iMesh.addInstances(count, (obj, index) => {
  obj.position.x = index;
  obj.quaternion.random();
});

By default, InstancedMesh2 does not create individual entity objects for each instance. To enable a simple API for accessing and modifying instance properties (similar to Three.js Object3D), you must set the createEntities flag to true in the constructor parameters.

Once enabled, you can access an instance via iMesh.instances[index] and perform transformations like setting position or rotation. Note: You must call .updateMatrix() after performing transformations to apply the changes to the mesh.

// 1. Enable entity creation in the constructor
const iMesh = new InstancedMesh2(geo, mat, { createEntities: true });

// 2. Access and transform an instance
iMesh.instances[index].position.random();
iMesh.instances[index].rotateX(Math.PI);

// 3. Apply the changes
iMesh.instances[index].updateMatrix();