references/instancing.md
# Native instancing
Use for large sets where per-instance components or updates are too expensive. Mount below Canvas with lighting. This small example shows buffer initialization; profile at the real instance count.
```tsx
import { useLayoutEffect, useRef } from 'react'
import { InstancedMesh, Object3D } from 'three'
export default function NativeInstances() {
const mesh = useRef<InstancedMesh>(null)
useLayoutEffect(() => {
if (!mesh.current) return
const transform = new Object3D()
for (let i = 0; i < 100; i++) {
transform.position.set((i % 10) - 4.5, Math.floor(i / 10) - 4.5, 0)
transform.updateMatrix()
mesh.current.setMatrixAt(i, transform.matrix)
}
mesh.current.instanceMatrix.needsUpdate = true
mesh.current.computeBoundingBox()
mesh.current.computeBoundingSphere()
}, [])
return (
<instancedMesh ref={mesh} args={[undefined, undefined, 100]}>
<boxGeometry args={[0.5, 0.5, 0.5]} />
<meshStandardMaterial color="coral" />
</instancedMesh>
)
}
```
- `args` sets capacity; `mesh.count` controls how many initialized instances draw. Growing beyond allocated capacity requires recreation.
- Set `instanceMatrix.needsUpdate` after matrix writes and `instanceColor.needsUpdate` after color writes. Recompute bounds when transforms change their extent.
- Use a stable scratch Object3D/Matrix4 for repeated frame updates. Set DynamicDrawUsage before the first upload for frequently changing buffers.
- Picking returns `instanceId`; map it to application data. Negative instance scales are unsupported; avoid using them for mirroring.
- Instancing reduces rendering overhead, not CPU simulation or raycasting cost. Custom vertex shaders still need to apply `instanceMatrix`.
Source: [InstancedMesh](https://threejs.org/docs/#InstancedMesh), [Drei Instances tradeoffs](https://drei.docs.pmnd.rs/performances/instances).
SKILL.md
---
name: r3f-geometry
description: Build React Three Fiber geometry, custom buffers, instanced meshes, points, and lines. Use for shape construction and geometry draw-call optimization, rather than material appearance.
---
# React Three Fiber geometry
Inspect installed Three.js, Fiber, and Drei versions before copying constructor arguments or helper props. Examples target Fiber 9 / React 19 and Three.js r185.
## Choose the representation
- Use native JSX geometry for ordinary shapes. `args` match the Three.js constructor; changing them reconstructs geometry, so animate transforms rather than constructor inputs.
- Use `BufferGeometry` for custom topology and buffer-based `points` for large particle sets. Keep generated arrays stable and use deterministic generation when results must be reproducible.
- Use Drei `Instances` for convenient declarative instances with events. For large or frequently updated sets, read [native instancing](references/instancing.md) to avoid per-instance React overhead.
- Instancing shares geometry/material and reduces draw calls. Merely sharing a geometry among separate meshes does not batch their draws.
- Drei `Merged` creates instancing abstractions from **meshes**, not BufferGeometry objects; it does not concatenate arbitrary static geometry. For actual merging, inspect `mergeGeometries` from `three/addons/utils/BufferGeometryUtils.js` and ensure compatible attributes/indexing.
## Declarative instances
Mount below Canvas with lighting. Each Instance belongs to its nearest Instances provider.
```tsx
import { Instance, Instances } from '@react-three/drei'
export default function Example() {
return (
<Instances limit={3} range={3}>
<boxGeometry args={[0.7, 0.7, 0.7]} />
<meshStandardMaterial />
<Instance position={[-1.2, 0, 0]} color="coral" />
<Instance position={[0, 0, 0]} color="skyblue" />
<Instance position={[1.2, 0, 0]} color="gold" />
</Instances>
)
}
```
## Custom buffers and updates
- `position` and `normal` attributes usually have item size 3; UVs have item size 2. Construct JSX buffer attributes with `args={[typedArray, itemSize]}` and the correct `attach`, not just `array`/`count` props with no constructor arguments.
- Indices refer to vertices; winding determines the front face. Duplicate vertices at hard normals or UV seams. Indexed vertices share all attributes, not just positions.
- Lit geometry needs normals. Use `computeVertexNormals()` when appropriate; do not recompute every frame if a shader or analytic normals can express the deformation more cheaply.
- After CPU buffer writes, set `attribute.needsUpdate = true`. Choose dynamic usage before the first GPU upload when buffers will change often.
- Recompute bounding boxes/spheres after geometry changes that affect them. GPU vertex displacement does not update CPU bounds or raycasting automatically.
- UV selection is explicit on modern Three.js: `texture.channel` selects `uv`, `uv1`, `uv2`, or `uv3`. Do not unconditionally copy `uv` into `uv2` for AO.
- Avoid rebuilding buffers for pointer movement. If topology is fixed, change attribute contents or uniforms instead.
## Helpers and tradeoffs
- Drei `Line` supports useful line widths; native WebGL line width is limited by the platform. Check `worldUnits` when choosing screen-space versus world-space thickness.
- Use Drei `Text` for flat text and `Text3D` for extruded geometry. Current TextGeometry uses `depth`, not the historical `height`; verify the helper's installed types and font format.
- Use `Edges` for sharp-edge outlines, not as a replacement for screen-space selection effects.
- `Bounds` and `Center` change framing/transforms; decide whether they should update after asset loading, resizing, or interaction.
- Segment count should follow silhouette, deformation, and viewing distance. A “high quality” fixed count is not universally better.
- Declaratively created geometry can be owned by R3F. Shared or cached geometry needs a shared lifetime; do not dispose it from one instance while others remain mounted.
## Verify
Check bounds/culling after updates, raycast hit positions, resource cleanup, and draw calls. Test at the intended object count; three instances do not establish performance at ten thousand.
## Sources
- [BufferGeometry](https://threejs.org/docs/#BufferGeometry), [BufferAttribute](https://threejs.org/docs/#BufferAttribute), [InstancedMesh](https://threejs.org/docs/#InstancedMesh).
- [Drei Instances](https://drei.docs.pmnd.rs/performances/instances), [Merged](https://drei.docs.pmnd.rs/performances/merged), [Text3D](https://drei.docs.pmnd.rs/abstractions/text3d).