r3f-loaders

What this skill does

# React Three Fiber Loaders

## Quick Start

```tsx
import { Canvas } from '@react-three/fiber'
import { useGLTF, OrbitControls } from '@react-three/drei'
import { Suspense } from 'react'

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

export default function App() {
  return (
    <Canvas>
      <ambientLight />
      <Suspense fallback={null}>
        <Model />
      </Suspense>
      <OrbitControls />
    </Canvas>
  )
}
```

## useGLTF (Drei)

The recommended way to load GLTF/GLB models.

### Basic Usage

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

function Model() {
  const gltf = useGLTF('/models/robot.glb')

  // gltf contains:
  // - scene: THREE.Group (the main scene)
  // - nodes: Object of named meshes
  // - materials: Object of named materials
  // - animations: Array of AnimationClip

  return <primitive object={gltf.scene} />
}
```

### Using Nodes and Materials

```tsx
function Model() {
  const { nodes, materials } = useGLTF('/models/robot.glb')

  return (
    <group>
      {/* Use specific meshes */}
      <mesh
        geometry={nodes.Body.geometry}
        material={materials.Metal}
        position={[0, 0, 0]}
      />
      <mesh
        geometry={nodes.Head.geometry}
        material={materials.Plastic}
        position={[0, 1, 0]}
      />
    </group>
  )
}
```

### With TypeScript (gltfjsx)

Generate typed components using gltfjsx:

```bash
npx gltfjsx model.glb --types
```

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

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

export function Model(props: JSX.IntrinsicElements['group']) {
  const { nodes, materials } = useGLTF('/model.glb') as GLTFResult

  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} />
      <mesh geometry={nodes.Head.geometry} material={materials.Plastic} />
    </group>
  )
}

useGLTF.preload('/model.glb')
```

### Draco Compression

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

function Model() {
  // Drei automatically handles Draco if the file is Draco-compressed
  const { scene } = useGLTF('/models/compressed.glb')
  return <primitive object={scene} />
}

// Or specify Draco decoder path
useGLTF.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/')
```

### Preloading

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

// Preload at module level
useGLTF.preload('/models/robot.glb')
useGLTF.preload(['/model1.glb', '/model2.glb'])

function Model() {
  // Will be instant if preloaded
  const { scene } = useGLTF('/models/robot.glb')
  return <primitive object={scene} />
}
```

### Processing Loaded Model

```tsx
function Model() {
  const { scene } = useGLTF('/models/robot.glb')

  useEffect(() => {
    // Enable shadows on all meshes
    scene.traverse((child) => {
      if (child.isMesh) {
        child.castShadow = true
        child.receiveShadow = true
      }
    })
  }, [scene])

  return <primitive object={scene} />
}
```

## useLoader (Core R3F)

For loading any Three.js asset.

### Basic Texture Loading

```tsx
import { useLoader } from '@react-three/fiber'
import { TextureLoader } from 'three'

function TexturedMesh() {
  const texture = useLoader(TextureLoader, '/textures/color.jpg')

  return (
    <mesh>
      <boxGeometry />
      <meshStandardMaterial map={texture} />
    </mesh>
  )
}
```

### Multiple Assets

```tsx
function MultiTexture() {
  const [colorMap, normalMap, roughnessMap] = useLoader(TextureLoader, [
    '/textures/color.jpg',
    '/textures/normal.jpg',
    '/textures/roughness.jpg',
  ])

  return (
    <mesh>
      <sphereGeometry args={[1, 64, 64]} />
      <meshStandardMaterial
        map={colorMap}
        normalMap={normalMap}
        roughnessMap={roughnessMap}
      />
    </mesh>
  )
}
```

### With Extensions (Draco)

```tsx
import { useLoader } from '@react-three/fiber'
import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader'

function Model() {
  const gltf = useLoader(GLTFLoader, '/model.glb', (loader) => {
    const dracoLoader = new DRACOLoader()
    dracoLoader.setDecoderPath('https://www.gstatic.com/draco/v1/decoders/')
    loader.setDRACOLoader(dracoLoader)
  })

  return <primitive object={gltf.scene} />
}
```

### Progress Callback

```tsx
function Model() {
  const gltf = useLoader(
    GLTFLoader,
    '/model.glb',
    undefined,  // extensions
    (progress) => {
      console.log(`Loading: ${(progress.loaded / progress.total) * 100}%`)
    }
  )

  return <primitive object={gltf.scene} />
}
```

### Preloading

```tsx
import { useLoader } from '@react-three/fiber'
import { TextureLoader } from 'three'

// Preload
useLoader.preload(TextureLoader, '/textures/color.jpg')
useLoader.preload(TextureLoader, ['/tex1.jpg', '/tex2.jpg'])

// Clear cache
useLoader.clear(TextureLoader, '/textures/color.jpg')
```

## Drei Loader Hooks

### useTexture

```tsx
import { useTexture } from '@react-three/drei'

// Single
const texture = useTexture('/texture.jpg')

// Array
const [color, normal] = useTexture(['/color.jpg', '/normal.jpg'])

// Named object (spreads directly to material)
const textures = useTexture({
  map: '/color.jpg',
  normalMap: '/normal.jpg',
  roughnessMap: '/roughness.jpg',
})
<meshStandardMaterial {...textures} />

// With callback for configuration
const texture = useTexture('/texture.jpg', (tex) => {
  tex.wrapS = tex.wrapT = THREE.RepeatWrapping
  tex.repeat.set(4, 4)
})

// Preload
useTexture.preload('/texture.jpg')
```

### useCubeTexture

```tsx
import { useCubeTexture } from '@react-three/drei'

function EnvMap() {
  const envMap = useCubeTexture(
    ['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg'],
    { path: '/textures/cube/' }
  )

  return (
    <mesh>
      <sphereGeometry />
      <meshStandardMaterial envMap={envMap} metalness={1} roughness={0} />
    </mesh>
  )
}
```

### useEnvironment

```tsx
import { useEnvironment } from '@react-three/drei'

// Preset
const envMap = useEnvironment({ preset: 'sunset' })
// Presets: apartment, city, dawn, forest, lobby, night, park, studio, sunset, warehouse

// Custom HDR file
const envMap = useEnvironment({ files: '/hdri/studio.hdr' })

// Cube map
const envMap = useEnvironment({
  files: ['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg'],
  path: '/textures/',
})
```

### useVideoTexture

```tsx
import { useVideoTexture } from '@react-three/drei'

function VideoPlane() {
  const texture = useVideoTexture('/video.mp4', {
    start: true,
    loop: true,
    muted: true,
    crossOrigin: 'anonymous',
  })

  return (
    <mesh>
      <planeGeometry args={[16/9 * 2, 2]} />
      <meshBasicMaterial map={texture} toneMapped={false} />
    </mesh>
  )
}
```

### useFont

```tsx
import { useFont, Text3D } from '@react-three/drei'

// Preload font
useFont.preload('/fonts/helvetiker.json')

function Text() {
  return (
    <Text3D font="/fonts/helvetiker.json" size={1} height={0.2}>
      Hello
      <meshStandardMaterial color="gold" />
    </Text3D>
  )
}
```

## Suspense Patterns

### Basic Suspense

```tsx
import { Suspense } from 'react'

function Scene() {
  return (
    <Canvas>
      <Suspense fallback={<Loader />}>
        <Model />
      </Suspense>
    </Canvas>
  )
}

function Loader() {
  return (
    <mesh>
      <boxGeometry />
      <meshBasicMaterial color="gray" wireframe />
    </mesh>
  )
}
```

### Loading Progress UI

```tsx
import { useProgress, Html } from '@react-three/drei'

function Loader() {
  const { active, progress, errors, item, loaded, total } = useProgress()

  return (
    <Html center>
      <div className="loader">
        <div className="progress-bar">