Skip to main content
rule CX Codex

drei-use-gltf — Claude Code rule: what it does, how to install

The drei-use-gltf rule guides GLTF loading through useGLTF, including caching and preloading. It fits React Three Fiber scenes that need model assets.

MIT ★ 4,719 updated 2026-10-24

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

What drei-use-gltf does

The rule directs the agent to use useGLTF from @react-three/drei for GLTF assets. The hook exposes the scene, nodes, and materials, works with React Suspense, reuses cached loads, and supports Draco decoding.

It shows how to call useGLTF.preload() at module scope, including for several model paths. Repeated objects should use scene.clone() so separate instances do not share state. The examples also cover typed GLTF results in TypeScript and dispose={null} when a model is shared.

The rule depends on @react-three/drei. A compressed asset also needs a Draco decoder path such as '/draco/'; R3F disposes objects automatically by default.

What it helps with

  • load a GLTF asset with useGLTF
  • start model loading before a component renders
  • wrap model rendering in Suspense
  • read meshes and materials from a GLTF result
  • render separate copies of one scene

Example prompts for the agent

  • Load model.glb with useGLTF and render its scene in the component.
  • Add module-level preloading for model1.glb, model2.glb, and model3.glb.
  • Render several tree.glb instances with scene.clone() and different positions.

How to install drei-use-gltf

Manually: put the files in place

.claude/rules/drei-use-gltf.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 drei-use-gltf

How do I install drei-use-gltf in Claude Code?

Place the rule file at .claude/rules/drei-use-gltf.md.

What does drei-use-gltf do?

It tells the agent to load GLTF files with useGLTF from @react-three/drei. The guidance covers caching, Suspense, preloading, Draco support, node and material access, scene cloning, and disposal behavior.

How does drei-use-gltf handle Draco-compressed models?

Pass the decoder directory as the second argument: useGLTF('/model.glb', '/draco/'). Use the same decoder path when calling useGLTF.preload('/model.glb', '/draco/').

Source text

drei-use-gltf.md · MIT
# drei-use-gltf

**Use useGLTF for model loading with preloading.**

## Why It Matters

`useGLTF` from Drei provides:
- Suspense integration (automatic loading states)
- Caching (same model loaded once)
- Preloading capability
- Draco decompression support

## Basic Example

```jsx
import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene, nodes, materials } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}
```

## Preloading (Critical for UX)

```jsx
import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

// Preload at module level - starts loading immediately
useGLTF.preload('/model.glb');

// Or preload multiple models
useGLTF.preload(['/model1.glb', '/model2.glb', '/model3.glb']);
```

## With Draco Compression

```jsx
function DracoModel() {
  // Second argument is the Draco decoder path
  const { scene } = useGLTF('/model.glb', '/draco/');
  return <primitive object={scene} />;
}

useGLTF.preload('/model.glb', '/draco/');
```

## Accessing Nodes and Materials

```jsx
function Character() {
  const { nodes, materials } = useGLTF('/character.glb');

  return (
    <group>
      <mesh
        geometry={nodes.Body.geometry}
        material={materials.Skin}
      />
      <mesh
        geometry={nodes.Clothes.geometry}
        material={materials.Fabric}
      />
    </group>
  );
}
```

## Clone for Multiple Instances

```jsx
function Tree({ position }) {
  const { scene } = useGLTF('/tree.glb');

  // Clone to avoid sharing state between instances
  return <primitive object={scene.clone()} position={position} />;
}

function Forest() {
  return (
    <>
      <Tree position={[0, 0, 0]} />
      <Tree position={[5, 0, 0]} />
      <Tree position={[10, 0, 0]} />
    </>
  );
}
```

## With Suspense

```jsx
import { Suspense } from 'react';
import { useGLTF } from '@react-three/drei';

function Model() {
  const { scene } = useGLTF('/model.glb');
  return <primitive object={scene} />;
}

function Scene() {
  return (
    <Suspense fallback={<LoadingBox />}>
      <Model />
    </Suspense>
  );
}

function LoadingBox() {
  return (
    <mesh>
      <boxGeometry />
      <meshBasicMaterial wireframe color="white" />
    </mesh>
  );
}
```

## TypeScript Types

```tsx
import { useGLTF } from '@react-three/drei';
import { GLTF } from 'three-stdlib';

type GLTFResult = GLTF & {
  nodes: {
    Body: THREE.Mesh;
    Head: THREE.Mesh;
  };
  materials: {
    Skin: THREE.MeshStandardMaterial;
  };
};

function Model() {
  const { nodes, materials } = useGLTF('/model.glb') as GLTFResult;
  // Now nodes.Body and materials.Skin are typed
}
```

## Dispose Handling

R3F auto-disposes by default. To prevent disposal (for shared models):

```jsx
function SharedModel({ model }) {
  return <primitive object={model} dispose={null} />;
}
```

## References

- [Drei useGLTF](https://github.com/pmndrs/drei#usegltf)
- [gltfjsx](https://github.com/pmndrs/gltfjsx) - Generate JSX from GLTF

© zebbern · MIT · zebbern/claude-code-guide

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
frame-delta-time frame-delta-time — a rule that makes every animated movement multiply by delta, so speed stops depending on the display's refresh rate. CX Codex +1 ★ 4,719repo stars draw-call-optimization The draw-call-optimization rule for Claude Code guides Three.js optimization, reducing draw calls to below 100 per frame through instancing, batching, and geometry merging. CX Codex +1 ★ 4,719repo stars 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 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 geometry-instanced-mesh geometry-instanced-mesh guides AI agents to use THREE.InstancedMesh instead of separate meshes for repeating 3D objects. 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

Project sponsors

Companies that keep this analytics open