geometry-instanced-mesh — Claude Code rule: what it does
geometry-instanced-mesh guides AI agents to use THREE.InstancedMesh instead of separate meshes for repeating 3D objects.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/geometry-instanced-mesh.mdWhat geometry-instanced-mesh does
This rule enforces Three.js rendering performance patterns. Instead of spawning thousands of individual THREE.Mesh instances that trigger separate draw calls, it instructs the assistant to bundle identical geometry into a single THREE.InstancedMesh. It details instance matrix management using a dummy THREE.Object3D, per-instance coloring via setColorAt, and picking with THREE.Raycaster through intersectObject.
Instancing adds unnecessary complexity when objects require distinct materials or geometries. The rule explicitly advises against this technique for complex individual animations or collections smaller than 100 items.
What it helps with
- cut draw calls down to a single call for thousands of duplicate objects
- apply distinct position, rotation, and scale matrices per instance
- detect clicks on individual instances using raycaster and instance IDs
Example prompts for the agent
- Convert this loop creating 10000 cubes into a THREE.InstancedMesh
- Show how to animate instances inside the render loop using dummy matrices
- Set up raycasting to change the color of an instanced mesh on click
How to install geometry-instanced-mesh
Manually: put the files in place
.claude/rules/geometry-instanced-mesh.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/geometry-instanced-mesh.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/geometry-instanced-mesh.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/geometry-instanced-mesh.mdManually: put the files in place
.clinerules/geometry-instanced-mesh.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about geometry-instanced-mesh
How to install geometry-instanced-mesh in Claude Code?
Save the rule content to .claude/rules/geometry-instanced-mesh.md in your repository root.
What does geometry-instanced-mesh do?
It guides code assistants to use THREE.InstancedMesh instead of standalone meshes when building scenes with numerous identical 3D elements.
When should InstancedMesh be avoided according to the rule?
Avoid it when rendering fewer than 100 objects, when meshes need different geometries or materials, or when items require complex per-object animations.
Source text
geometry-instanced-mesh.md · MIT
# geometry-instanced-mesh
**Use InstancedMesh for many identical objects.**
## Why It Matters
Each mesh = 1 draw call. 10,000 meshes = 10,000 draw calls = terrible performance. InstancedMesh renders multiple copies in a single draw call while allowing individual transforms and colors.
## Bad Example
```javascript
// BAD - 10000 draw calls
for (let i = 0; i < 10000; i++) {
const mesh = new THREE.Mesh(geometry, material);
mesh.position.random().multiplyScalar(100);
scene.add(mesh);
}
```
This creates 10,000 separate objects, each requiring its own draw call.
## Good Example
```javascript
// GOOD - Single draw call for 10000 instances
const instancedMesh = new THREE.InstancedMesh(geometry, material, 10000);
const dummy = new THREE.Object3D();
const color = new THREE.Color();
for (let i = 0; i < 10000; i++) {
// Set position
dummy.position.random().multiplyScalar(100);
dummy.rotation.random();
dummy.scale.setScalar(0.5 + Math.random() * 0.5);
dummy.updateMatrix();
instancedMesh.setMatrixAt(i, dummy.matrix);
// Set color (optional)
color.setHSL(Math.random(), 0.8, 0.5);
instancedMesh.setColorAt(i, color);
}
instancedMesh.instanceMatrix.needsUpdate = true;
if (instancedMesh.instanceColor) {
instancedMesh.instanceColor.needsUpdate = true;
}
scene.add(instancedMesh);
```
## Updating Instances
```javascript
// Update a single instance
function updateInstance(index, position, rotation, scale) {
dummy.position.copy(position);
dummy.rotation.copy(rotation);
dummy.scale.copy(scale);
dummy.updateMatrix();
instancedMesh.setMatrixAt(index, dummy.matrix);
instancedMesh.instanceMatrix.needsUpdate = true;
}
// Update in animation loop
function animate() {
for (let i = 0; i < 100; i++) {
instancedMesh.getMatrixAt(i, dummy.matrix);
dummy.matrix.decompose(dummy.position, dummy.quaternion, dummy.scale);
dummy.rotation.y += 0.01;
dummy.updateMatrix();
instancedMesh.setMatrixAt(i, dummy.matrix);
}
instancedMesh.instanceMatrix.needsUpdate = true;
renderer.render(scene, camera);
}
```
## Raycasting
```javascript
const raycaster = new THREE.Raycaster();
function onMouseClick(event) {
raycaster.setFromCamera(mouse, camera);
const intersects = raycaster.intersectObject(instancedMesh);
if (intersects.length > 0) {
const instanceId = intersects[0].instanceId;
console.log('Clicked instance:', instanceId);
// Change color of clicked instance
instancedMesh.setColorAt(instanceId, new THREE.Color(0xff0000));
instancedMesh.instanceColor.needsUpdate = true;
}
}
```
## Performance Comparison
| Method | Objects | Draw Calls | Performance |
|--------|---------|------------|-------------|
| Individual Meshes | 10,000 | 10,000 | ~5 FPS |
| InstancedMesh | 10,000 | 1 | ~60 FPS |
## When NOT to Use
- Different geometries needed
- Different materials needed
- Complex per-object animations
- < 100 objects (overhead not worth it)
## References
- [Three.js InstancedMesh](https://threejs.org/docs/#api/en/objects/InstancedMesh)
- [Instancing Example](https://threejs.org/examples/#webgl_instancing_performance)
© zebbern · MIT · zebbern/claude-code-guide