Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/geometry-instanced-mesh.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set86

The whole set →
object-pooling object-pooling — a rule that pushes the agent to reuse bullets, particles and NPCs from a pool instead of building and discarding meshes every frame. CX Codex +1 ★ 4,719repo stars shader-mobile The shader-mobile rule for Claude Code provides guidelines for optimizing GLSL and Three.js shaders for mobile GPUs to prevent framerate drops on mobile devices. CX Codex +1 ★ 4,719repo stars drei-use-gltf The drei-use-gltf rule guides GLTF loading through useGLTF, including caching and preloading. It fits React Three Fiber scenes that need model assets. CX Codex +1 ★ 4,719repo stars perf-zustand-selectors perf-zustand-selectors — a rule file that pushes the agent to subscribe components to individual Zustand slices instead of the whole store, so a component repaints only when the data it reads changes. CX Codex +1 ★ 4,719repo stars webgpu-renderer The webgpu-renderer rule guides Three.js WebGPU setup with a WebGL 2 fallback. Use it when a 3D scene needs compute work, GPU particles, or indirect rendering. CX Codex +1 ★ 4,719repo stars tsl-material-slots tsl-material-slots is a Claude Code rule with a reference to Three.js TSL material slots. It helps write node-based shader logic without mistyping slot names or property types. CX Codex +1 ★ 4,719repo stars core-web-vitals core-web-vitals is a Claude Code rule for loading Three.js models and textures without letting heavy 3D delay first paint or degrade LCP, FID and CLS. CX Codex +1 ★ 4,719repo stars postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open