Agent skill
dev-performance-instancing
Instanced rendering for repeated objects in R3F. Use when rendering many identical objects.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/dev-performance-instancing
SKILL.md
Instanced Rendering
Render thousands of identical objects with a single draw call.
When to Use
Use when:
- Rendering many identical objects (trees, grass, particles)
- Draw calls exceed 100
- Objects share same geometry and material
Quick Start
tsx
import { Instances, Instance } from '@react-three/drei';
// Instead of 1000 separate meshes
function OptimizedTrees({ positions }) {
return (
<Instances limit={positions.length}>
<cylinderGeometry args={[0.1, 0.3, 2]} />
<meshStandardMaterial color="brown" />
{positions.map((pos, i) => (
<Instance key={i} position={pos} />
))}
</Instances>
);
}
Performance Impact
| Approach | Objects | Draw Calls | FPS |
|---|---|---|---|
| Individual meshes | 1000 | 1000 | 15 |
| Instanced | 1000 | 1 | 60 |
Dynamic Instancing
tsx
import { Instances, Instance } from '@react-three/drei';
function DynamicParticles({ count = 100 }) {
const particles = useRef<Array<{ x: number; y: number; z: number }>>([]);
// Initialize particles
useMemo(() => {
for (let i = 0; i < count; i++) {
particles.current.push({
x: (Math.random() - 0.5) * 10,
y: (Math.random() - 0.5) * 10,
z: (Math.random() - 0.5) * 10,
});
}
}, [count]);
return (
<Instances limit={count}>
<sphereGeometry args={[0.1, 8, 8]} />
<meshBasicMaterial color="orange" />
{particles.current.map((pos, i) => (
<Instance key={i} position={[pos.x, pos.y, pos.z]} />
))}
</Instances>
);
}
Instancing with Colors
tsx
function ColoredInstances() {
const colors = useMemo(() =>
Array.from({ length: 100 }, () => ({
color: new THREE.Color(Math.random(), Math.random(), Math.random()),
}))
, []);
return (
<Instances limit={100}>
<boxGeometry args={[1, 1, 1]} />
<meshStandardMaterial />
{colors.map((props, i) => (
<Instance
key={i}
position={[(i % 10) * 1.2, Math.floor(i / 10) * 1.2, 0]}
color={props.color}
/>
))}
</Instances>
);
}
Limitations
| ❌ Can't | ✅ Alternative |
|---|---|
| Different geometries per instance | Use separate Instances groups |
| Different materials per instance | Use vertex colors or textures |
| Complex animations per instance | Use shader-based animation |
Common Mistakes
| ❌ Wrong | ✅ Right |
|---|---|
| Using individual meshes for repeated objects | Use Instances |
| Not setting limit prop | Always set limit higher than max count |
| Creating new Instance objects every frame | Use stable key, update position prop |
When NOT to Use
- Objects have different geometries
- Objects have different materials
- Less than ~50 identical objects
- Objects need individual complex animations
Reference
- performance-basics.md - Core optimization
- lod-systems.md - LOD techniques
Didn't find tool you were looking for?