threejs-r3f

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 7196f765fc11 · 31 Oct 2026Report an issue or request a re-scan

• Publisherathevon GitHub userOwner of the repository this skill is read from
• Source folderathevon/genjutsu/skills/_jutsu/threejs-r3fThe exact folder we audited
• LicenceNOASSERTIONAs the repository states it
• Commit pinned for this verdict7196f765fc11A new audit runs when the source changes
• Repository statusNot archivedLast push 25 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Three.js and React Three Fiber sub-skill - 3D scenes, shaders, postprocessing.

---
name: threejs-r3f
description: "Three.js and React Three Fiber sub-skill - 3D scenes, shaders, postprocessing."
metadata:
  internal: true
---

> **Version-sensitive.** Every API name, SDK gate and browser-support claim below was
> verified on **2026-09-08** against primary sources. What against, and when, is in
> `_jutsu/VERSIONS.md`. If that date is old, re-verify before acting on a version number.

# Three.js & React Three Fiber

> 3D on the web. Three.js is the engine, R3F is the React renderer.
> Concise rules here. Deep-dive in `references/`.
>
> **Versions:** `three` r185 (`0.185.x`) · `@react-three/fiber` 9.x · `@react-three/drei` 10.x · `@react-three/postprocessing` 3.x.
> **R3F 9 is React 19 only** - its declared peer range is `react` / `react-dom` `>=19 <19.3` (drei 10 asks `^19`). React 18 projects must stay on R3F 8 + drei 9. Check the installed React major before scaffolding.
> **Renderers:** `WebGLRenderer` is still R3F's default. `WebGPURenderer` + TSL is shipped (not flagged) and self-falls-back to WebGL 2, but three's docs call it "the new alternative of `WebGLRenderer`", not the default. Opt in with an async `gl` callback:
> ```tsx
> import * as THREE from 'three/webgpu'
> <Canvas gl={async (props) => { const r = new THREE.WebGPURenderer(props as any); await r.init(); return r }} />
> ```

---

## When to Use What

| Need | Tool | Why |
|---|---|---|
| Full 3D scene (models, lights, physics) | R3F + drei | Declarative, React-friendly, ecosystem |
| Vanilla 3D (no React) | Three.js direct | Lighter, no React overhead |
| Simple 3D transforms on UI | CSS `transform3d` | GPU-composited, no WebGL context |
| 2D particles / generative | Canvas 2D | Simpler API, less GPU overhead |
| Shader-only visuals (no scene graph) | Raw WebGL / ShaderMaterial | Maximum control, minimal abstraction |

---

## Scene Setup Patterns

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

<Canvas camera={{ position: [0, 2, 5], fov: 45 }} dpr={[1, 2]} gl={{ antialias: true }}>
  <Suspense fallback={null}>
    <Environment preset="studio" />
    <OrbitControls makeDefault />
    <Scene />
  </Suspense>
</Canvas>
```

**Rules:**
- Always wrap scene content in `<Suspense>` -- loaders (GLTF, textures, HDRI) need it
- Set `dpr={[1, 2]}` to clamp pixel ratio (Retina without melting GPUs)
- Keep the Canvas parent component minimal -- re-renders propagate into the scene

---

## R3F Hooks

| Hook | Purpose | Gotcha |
|---|---|---|
| `useFrame((state, delta) => {})` | Per-frame logic (animation, physics) | Never setState inside |
| `useThree()` | Access gl, scene, camera, size, viewport, pointer | Destructure only what you need |
| `useLoader(TextureLoader, url)` | Load any Three.js resource | Wrap parent in Suspense |
| `useGraph(scene)` | Extract nodes/materials from loaded scene | Useful after useGLTF |

### useFrame Tips

```tsx
useFrame((state, delta) => {
  // Use delta for framerate-independent animation
  meshRef.current.rotation.y += delta * 0.5
  // Access clock for time-based effects
  material.uniforms.uTime.value = state.clock.elapsedTime
})
```

---

## Drei Essentials

| Component | Use Case |
|---|---|
| `Environment` | HDRI lighting (presets: studio, sunset, city, forest, dawn) |
| `Float` | Idle floating animation (speed, rotationIntensity, floatIntensity) |
| `Text3D` | Extruded 3D text (needs JSON font from Facetype.js) |
| `useGLTF` | Load .glb/.gltf models (returns { nodes, materials, scene }) |
| `useGLTF.preload(url)` | Preload model before component mounts |
| `MeshTransmissionMaterial` | Glass/crystal/liquid refraction effects |
| `PresentationControls` | Drag-to-rotate for product showcases |
| `Center` | Auto-center any group of meshes |
| `Detailed` | LOD -- swap geometry by camera distance |
| `useTexture` | Load textures with Suspense support |
| `Instances` | Declarative instancing for repeated meshes |

---

## Postprocessing

```tsx
import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing'
import { BlendFunction } from 'postprocessing'

<EffectComposer>
  <Bloom
    luminanceThreshold={1}
    luminanceSmoothing={0.4}
    intensity={0.6}
  />
  <ChromaticAberration
    blendFunction={BlendFunction.NORMAL}
    offset={[0.002, 0.002]}
  />
</EffectComposer>
```

**Rules:**
- Bloom is selective by default -- lift material color/emissive above 1.0 to make it glow
- `luminanceThreshold={1}` = nothing glows unless explicitly emissive
- Order matters inside EffectComposer
- Effects are merged into a single pass (performant by design)

---

## Performance Patterns

| Pattern | When |
|---|---|
| `<Instances>` / `InstancedMesh` | 100+ identical meshes (particles, trees, crowds) |
| `<Detailed distances={[0, 50, 100]}>` | LOD: swap hi/lo models by distance |
| `dispose={null}` on `<primitive>` | Prevent auto-dispose when reusing shared geometry |
| `useGLTF` + Draco | Compress .glb models (70-90% size reduction) |
| `useTexture` + KTX2 | Compressed GPU textures (1/4 VRAM) |
| `frameloop="demand"` on Canvas | Only render when something changes (static scenes) |
| `invalidate()` from useThree | Trigger a render in demand mode |
| `<AdaptiveDpr pixelated />` + `<AdaptiveEvents />` (drei) | Drop resolution and raycasting while the camera moves, restore when idle |
| `<Bvh>` (drei) | Heavy scenes that need fast raycasting / hover picking |

**Target metrics:** < 100 draw calls, < 1M triangles, 60fps on mid-range GPU.
Use `stats-gl` or `r3f-perf` to monitor.

---

## Do Not

### 1. Never setState in useFrame

Causes full React re-render 60x/second. Mutate refs directly.

```tsx
// BAD
useFrame(() => {
  setRotation(prev => prev + 0.01) // React re-render every frame
})

// GOOD
useFrame((_, delta) => {
  meshRef.current.rotation.y += delta * 0.5 // Direct mutation, zero re-renders
})
```

### 2. Never allocate in the render loop

`new Vector3()` per frame = 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 7196f765fc11

Questions about threejs-r3f

• github.com/athevon/genjutsu/tree/main/skills/_jutsu/threejs-r3f — the audited source at commit 7196f765fc11 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology