three-instance-batch

InstancedMesh management layer for Three.js. Handles dirty tracking, group batching, and dynamic add/remove — so you don't have to.

Installation

npm install three-instance-batch

Quick Start

import * as THREE from 'three'
import { Instance, InstanceBatcher } from 'three-instance-batch'

const batcher = new InstanceBatcher()
scene.add(batcher)

const geo = new THREE.BoxGeometry(1, 1, 1)
const mat = new THREE.MeshStandardMaterial({ color: '#ff6b6b' })

const inst = new Instance(geo, mat)
inst.position.set(3, 0, 0)
inst.color.set('#00ffcc')
inst.castShadow = true

batcher.addInstance(inst)

function animate() {
  inst.position.setX(Math.sin(Date.now() * 0.001) * 5)
  batcher.update(camera)
  renderer.render(scene, camera)
  requestAnimationFrame(animate)
}

No setMatrixAt. No needsUpdate. Just change properties and call update().

Multiple Instances

const count = 500
const instances: Instance[] = []

for (let i = 0; i < count; i++) {
  const inst = new Instance(geo, mat)
  const angle = (i / count) * Math.PI * 2
  inst.position.set(Math.cos(angle) * 10, 0, Math.sin(angle) * 10)
  inst.color.setHSL(i / count, 0.8, 0.5)
  instances.push(inst)
}
batcher.addInstance(instances)

function animate() {
  for (let i = 0; i < instances.length; i++) {
    instances[i].rotation.set(0, Date.now() * 0.001 + i * 0.1, 0)
    instances[i].color.setHSL((Date.now() * 0.0001 + i * 0.002) % 1, 0.8, 0.5)
  }
  batcher.update(camera)
  renderer.render(scene, camera)
  requestAnimationFrame(animate)
}

How It Works

Instance wraps Vector3, Euler, Quaternion, and Color setter methods at construction time. Any mutation via setter — position.set(), rotation.set(), quaternion.setFromEuler(), color.setHSL(), etc. — automatically marks that instance dirty. Note that direct property assignment (position.x = 5) is not tracked; use setX() or set() instead.

Instances are grouped into InstancedMesh objects by a group key derived from geometry UUID, material properties, and shadow flags. Instances sharing the same key share one draw call.

Multiple Geometries and Materials

The batcher handles mixed types automatically:

const meshes = [
  new Instance(boxGeo, redMat),
  new Instance(sphereGeo, blueMat),
  new Instance(boxGeo, redMat),   // same key as first → same InstancedMesh
]
batcher.addInstance(meshes)

Reusing the same geometry and material object is enough to share a batch.

Shadow Changes Trigger Remigration

castShadow and receiveShadow are part of the group key. Changing them at runtime causes the instance to be moved to the correct group automatically on the next update().

inst.castShadow = true  // migrates to the shadow-casting group on next update()

Parent-Child Hierarchy

Instances support parent-child nesting. A child's world matrix is computed from its parent's transform chain.

const parent = new Instance(geo, mat)
const child = new Instance(geo, mat)
child.parent = parent  // child follows parent's transform

parent.position.set(0, 5, 0)
batcher.update()  // child world matrix recalculated automatically

Circular references are detected and rejected at runtime. Disposing a parent detaches all children but does not dispose them.

Raycasting

const raycaster = new THREE.Raycaster()
raycaster.setFromCamera(mouse, camera)
const hits = raycaster.intersectObjects(batcher.children)

for (const hit of hits) {
  const inst = batcher.getInstanceFromIntersect(hit)
  if (inst) console.log('hit', inst.id)
}

API

Instance

new Instance(geometry: BufferGeometry, material: Material)

| Member | Type | Notes | |---|---|---| | id | number | Auto-incremented, readonly | | geometry | BufferGeometry | Readonly | | material | Material | Readonly | | position | Vector3 | Auto-tracked | | scale | Vector3 | Default (1,1,1), auto-tracked | | rotation | Euler | Auto-tracked; syncs to quaternion on change | | quaternion | Quaternion | Auto-tracked | | color | Color | Default white, auto-tracked | | visible | boolean | Hidden instances write a zero matrix | | castShadow | boolean | Change triggers group remigration | | receiveShadow | boolean | Change triggers group remigration | | parent | Instance \| null | Setter validates against cycles | | children | Instance[] | Readonly array | | disposed | boolean | Readonly | | groupKey | string | Derived from geometry, material, shadow flags | | localMatrix | Matrix4 | Readonly, computed from transform components | | worldMatrix | Matrix4 | Readonly, local × ancestor chain | | isAncestorOf(other) | boolean | | | dispose() | void | Detaches from parent, detaches children, unsubscribes from all batchers |

Note: Only method calls (.set(), .setX(), .copy(), etc.) are tracked. Property assignment (position.x = 5) bypasses the wrapper. Use setX() / setY() / setZ() for single-component updates.

InstanceBatcher

Extends THREE.Group. Add it to the scene and call update() every frame.

new InstanceBatcher(options?: BatcherOptions)

| Member | Type | Notes | |---|---|---| | count | number | Total managed instances | | groupCount | number | Number of internal InstancedMesh groups | | hasDirty | boolean | Whether any data needs flushing to GPU | | addInstance(inst \| inst[]) | this | Duplicates are ignored | | removeInstance(inst \| inst[]) | this | Missing instances are ignored | | has(inst) | boolean | | | getMatrixAt(inst, target) | Matrix4 | Reads back from GPU buffer | | getColorAt(inst, target) | Color | Reads back from GPU buffer | | getInstanceFromIntersect(hit) | Instance \| null | Resolves a raycaster hit to an instance | | update(camera?) | void | Flushes dirty matrices and colors; pass camera to enable frustum culling | | disposeBatcher() | void | Disposes all internal meshes and clears all subscriptions |

BatcherOptions

| Option | Type | Default | Description | |---|---|---|---| | initialCapacity | number | 16 | Initial slot count per InstancedMesh group | | overAllocation | number | 0.2 | Extra capacity fraction when a group grows (0.2 = 20%) | | frustumCulling | boolean | false | Skip instances outside the camera frustum | | customDepthMaterial | Material | — | Custom depth material for shadow passes | | customDistanceMaterial | Material | — | Custom distance material for shadow passes |

Memory Overhead

| Overhead | Per 1,000 instances | |---|---| | 35 wrapped setter closures | ~1.1 MB | | Three.js transform objects | ~0.8 MB | | GPU buffer (matrix 64B + color 12B) | ~76 KB | | Total | ~2.0 MB / 1k |

The real bottleneck at scale is GPU draw calls and vertex throughput, not JS-side dirty tracking.

Known Limitations

• Frustum culling collects per-instance visibility but does not yet skip culled instances in the render pass.

Development

git clone https://github.com/qiao-coding/three-instance-batch.git
cd three-instance-batch
npm install
npm run test:run    # 56 tests
npm run dev         # start demo at localhost:5173
npm run build       # build to dist/

PRs welcome. Open an issue before starting on anything substantial.

License

MIT