# Threejs Impl Drei

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-three-js-claude-skill-package-threejs-impl-drei`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Three.js-Claude-Skill-Package/tree/master/skills/source/threejs-impl/threejs-impl-drei
- **Website:** https://threejs.org/

## Install

```sh
agentstack add skill-impertio-studio-three-js-claude-skill-package-threejs-impl-drei
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# threejs-impl-drei

## Quick Reference

### Installation

```bash
npm install @react-three/drei @react-three/fiber three
```

### Critical Warnings

**ALWAYS** wrap components that use loader hooks (`useGLTF`, `useTexture`, `useFBX`, `useKTX2`, `useFont`) in ``. Omitting Suspense causes the entire React tree to crash.

**ALWAYS** add `makeDefault` to your primary camera controls (``). Without `makeDefault`, Drei controls do NOT integrate with R3F's event system and pointer events break.

**NEVER** use an invalid `Environment` preset name. The ONLY valid presets are: `apartment`, `city`, `dawn`, `forest`, `lobby`, `night`, `park`, `studio`, `sunset`, `warehouse`.

**NEVER** forget to call `.preload()` for critical assets. Use `useGLTF.preload('/model.glb')` at module scope to start loading before component mount.

**ALWAYS** use `` for rendering more than 100 identical meshes. Individual meshes cause one draw call each; instances batch them into one.

---

## Controls

### OrbitControls

The most common camera control. Orbit, zoom, and pan around a target.

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

```

### Other Controls

| Component | Use Case |
|-----------|----------|
| `CameraControls` | Full-featured camera (recommended for complex scenes) |
| `MapControls` | Top-down map navigation (orbit restricted to vertical axis) |
| `PresentationControls` | Drag-to-rotate with spring physics (product viewers) |
| `ScrollControls` | Scroll-driven animation (`pages` prop sets scroll length) |
| `TransformControls` | Translate/rotate/scale gizmo on selected objects |
| `DragControls` | Drag objects in 3D space |
| `KeyboardControls` | Keyboard input as React context |
| `FaceControls` | Face-tracking camera movement |

### ScrollControls Pattern

```jsx
import { ScrollControls, useScroll } from '@react-three/drei'

  

function ScrollScene() {
  const scroll = useScroll()
  useFrame(() => {
    const offset = scroll.offset // 0 to 1
  })
  return 
}
```

---

## Environment and Staging

### Environment

Loads HDR environment maps for realistic reflections and lighting.

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

// Preset (downloads from polyhaven CDN)

// Custom HDR file

// Custom environment with Lightformers

  

```

**Valid presets:** `apartment`, `city`, `dawn`, `forest`, `lobby`, `night`, `park`, `studio`, `sunset`, `warehouse`.

### Stage

Complete lighting and shadow setup in one component. Ideal for product viewers.

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

  

```

### Shadow Components

| Component | Use Case | Key Props |
|-----------|----------|-----------|
| `ContactShadows` | Soft ground shadows (no light needed) | `opacity`, `scale`, `blur`, `far`, `resolution`, `color` |
| `AccumulativeShadows` | High-quality baked soft shadows | `frames`, `alphaTest`, `scale`, `opacity` |
| `RandomizedLight` | Child of AccumulativeShadows | `amount`, `radius`, `intensity`, `position` |
| `BakeShadows` | Bake shadow maps once, stop updating | — |
| `SoftShadows` | PCSS soft shadows for real-time lights | — |

### AccumulativeShadows Pattern

```jsx

  

```

### Atmosphere

| Component | Purpose | Key Props |
|-----------|---------|-----------|
| `Sky` | Procedural sky dome | `sunPosition`, `turbidity`, `rayleigh` |
| `Stars` | Particle starfield | `radius`, `count`, `factor`, `fade` |
| `Sparkles` | Floating particles | `count`, `size`, `speed`, `color` |
| `Cloud` | Volumetric clouds | `opacity`, `speed`, `segments`, `bounds` |

---

## Text and HTML

### Text (SDF)

High-quality 2D text rendered with signed distance fields via troika-three-text.

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

  Hello World

```

### Text3D

Extruded 3D geometry text. Requires a JSON font file (use `facetype.js` to convert).

```jsx
import { Text3D, Center } from '@react-three/drei'

  
    Hello
    
  

```

### Html

Renders DOM elements positioned in 3D space.

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

  
    Annotation
  

```

### Billboard

ALWAYS faces the camera. Use for labels and sprites.

```jsx
import { Billboard, Text } from '@react-three/drei'

  Always Visible

```

### Hud

Renders a heads-up display in a separate orthographic scene.

```jsx
import { Hud, OrthographicCamera } from '@react-three/drei'

  
  HUD Text

```

---

## Materials

| Component | Purpose |
|-----------|---------|
| `MeshReflectorMaterial` | Reflective floors with blur, distortion, resolution |
| `MeshTransmissionMaterial` | Glass with chromatic aberration, distortion, thickness |
| `MeshRefractionMaterial` | Refraction using environment cube map |
| `MeshWobbleMaterial` | Animated wobble on MeshStandardMaterial |
| `MeshDistortMaterial` | Perlin noise distortion on MeshStandardMaterial |
| `MeshDiscardMaterial` | Renders nothing (shadow-only objects) |
| `shaderMaterial` | Helper to create custom ShaderMaterial as JSX |

### MeshReflectorMaterial Example

```jsx

  
  

```

### shaderMaterial Helper

```jsx
import { shaderMaterial } from '@react-three/drei'
import { extend } from '@react-three/fiber'

const WaveMaterial = shaderMaterial(
  { uTime: 0, uColor: new THREE.Color(0.2, 0.0, 0.1) },
  /* vertex */ `varying vec2 vUv; void main() { vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
  /* fragment */ `uniform float uTime; uniform vec3 uColor; varying vec2 vUv; void main() { gl_FragColor = vec4(vUv * uColor, 1.0); }`
)
extend({ WaveMaterial })
// Usage: 
```

---

## Loaders

**ALWAYS** wrap loader-consuming components in ``.

| Hook | Returns | Preload |
|------|---------|---------|
| `useGLTF(url)` | `{ nodes, materials, scene, animations }` | `useGLTF.preload(url)` |
| `useTexture(url)` | `THREE.Texture` or map object | `useTexture.preload(url)` |
| `useFBX(url)` | `THREE.Group` | `useFBX.preload(url)` |
| `useKTX2(url)` | Compressed texture | `useKTX2.preload(url)` |
| `useFont(url)` | Font data for Text3D | `useFont.preload(url)` |
| `useAnimations(clips, ref)` | `{ actions, names, mixer, ref }` | — |
| `useVideoTexture(url)` | `THREE.VideoTexture` | — |

### useGLTF Pattern

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

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    
      
    
  )
}
useGLTF.preload('/model.glb')
```

### useTexture with Multiple Maps

```jsx
const textures = useTexture({
  map: '/color.jpg',
  normalMap: '/normal.jpg',
  roughnessMap: '/roughness.jpg',
  aoMap: '/ao.jpg',
})
// Spread directly onto material

```

### useAnimations Pattern

```jsx
function AnimatedModel() {
  const group = useRef()
  const { nodes, animations } = useGLTF('/character.glb')
  const { actions } = useAnimations(animations, group)

  useEffect(() => {
    actions['Walk']?.play()
    return () => actions['Walk']?.stop()
  }, [actions])

  return 
}
```

---

## Performance

### Instances

ALWAYS use for large numbers of identical meshes (>100). Reduces draw calls from N to 1.

```jsx
import { Instances, Instance } from '@react-three/drei'

  
  
  {positions.map((pos, i) => (
    
  ))}

```

### Merged

Merges different geometries into a single draw call.

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

function Furniture({ nodes }) {
  return (
    
      {(Chair, Table, Lamp) => (
        <>
          
          
          
        
      )}
    
  )
}
```

### Performance Helpers

| Component | Purpose |
|-----------|---------|
| `Detailed` | LOD — switches geometry based on camera distance |
| `BakeShadows` | Bakes shadows once, stops updating |
| `AdaptiveDpr` | Lowers device pixel ratio during performance drops |
| `AdaptiveEvents` | Reduces event frequency during performance drops |
| `PerformanceMonitor` | Monitors FPS, triggers regression callbacks |
| `Bvh` | BVH-accelerated raycasting for complex meshes |
| `meshBounds` | Fast bounding-box raycasting (replaces per-triangle) |

### PerformanceMonitor Pattern

```jsx
 setDpr(2)}
  onDecline={() => setDpr(1)}
  flipflops={3}
  onFallback={() => setDpr(0.5)}
/>
```

---

## Staging and Layout

| Component | Purpose | Key Props |
|-----------|---------|-----------|
| `Center` | Centers children at origin | `top`, `right`, `bottom`, `left`, `front`, `back` |
| `Float` | Floating hover animation | `speed`, `rotationIntensity`, `floatIntensity` |
| `Bounds` | Auto-fit camera to content | `fit`, `clip`, `observe`, `margin` |
| `Resize` | Normalizes children to unit size | `width`, `height`, `depth` |

---

## Abstractions and Effects

| Component | Purpose |
|-----------|---------|
| `Edges` | Renders wireframe edges |
| `Outlines` | Screen-space outlines |
| `Trail` | Motion trail behind objects |
| `Decal` | Project texture onto mesh surface |
| `Splat` | Gaussian splatting renderer |
| `Clone` | Deep clone with shared geometry/materials |
| `Image` | Texture-mapped plane with shader effects |
| `MeshPortalMaterial` | Portal — renders scene inside mesh surface |
| `GradientTexture` | Procedural gradient texture |

---

## Gizmos

| Component | Purpose |
|-----------|---------|
| `GizmoHelper` | Viewport orientation widget |
| `PivotControls` | Interactive pivot gizmo (translate/rotate/scale) |
| `TransformControls` | Three.js TransformControls wrapper |
| `Grid` | Infinite configurable grid plane |
| `Helper / useHelper` | Visualize light/camera helpers |

---

## Component Selection Guide

| Scenario | Component |
|----------|-----------|
| Product viewer | `Stage` + `OrbitControls` + `Environment` |
| Architectural walkthrough | `CameraControls` + `Environment` + `ContactShadows` |
| Scrolling experience | `ScrollControls` + `useScroll` |
| Data visualization | `Instances` + `Html` + `Billboard` |
| Text labels in 3D | `Text` (2D) or `Text3D` (extruded) + `Billboard` |
| Glass/transparent objects | `MeshTransmissionMaterial` + `Environment` |
| Reflective floors | `MeshReflectorMaterial` |
| Large identical meshes | `Instances` (>100) or `Merged` (mixed geometries) |
| Model loading | `useGLTF` + `Suspense` + `.preload()` |
| HUD / overlay | `Hud` or `Html` with `fullscreen` |

---

## Reference Links

- [references/methods.md](references/methods.md) -- Key component props and hook signatures
- [references/examples.md](references/examples.md) -- Complete working examples
- [references/anti-patterns.md](references/anti-patterns.md) -- Common mistakes and fixes

### Official Sources

- https://drei.docs.pmnd.rs/
- https://github.com/pmndrs/drei
- https://r3f.docs.pmnd.rs/

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Three.js-Claude-Skill-Package](https://github.com/Impertio-Studio/Three.js-Claude-Skill-Package)
- **License:** MIT
- **Homepage:** https://threejs.org/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-three-js-claude-skill-package-threejs-impl-drei
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.