threejs-r3f（Three.js R3F 命令行）

Three.js / React Three Fiber

Guide for building 3D web experiences with R3F v9 (React 19) and the pmndrs ecosystem.

Version Constraints

Use fiber v8 + rapier v1 for React 18 projects. Never mix version lines.

Installation

Standalone Vite + R3F app

bun create vite my-scene -- --template react-ts
cd my-scene
bun add three @react-three/fiber @react-three/drei
bun add -d @types/three
bun dev

Into an existing React 19 project

bun add three @react-three/fiber @react-three/drei
bun add -d @types/three

Optional packages: bun add @react-three/rapier (physics), bun add zustand (state), bun add leva (debug GUI).

Scene Setup

For the minimal scene template, Canvas prop table, frameloop values, responsive canvas, and WebGPU renderer bootstrap, read references/scene-setup.md.

Key facts to keep in mind without reading the reference:

• Canvas defaults: antialias: true, outputColorSpace = SRGBColorSpace, toneMapping = ACESFilmicToneMapping, ColorManagement.enabled = true
• Always set dpr={[1, 2]} to clamp device pixel ratio
• Use shadows="soft" for shadow maps; add castShadow/receiveShadow to meshes
• frameloop="demand" for static scenes that only need to re-render on interaction

Drei Helpers — Top 15

All import from @react-three/drei. Read references/drei-helpers.md for full inventory, props, and examples.

Controls

• OrbitControls — rotate/zoom/pan; add makeDefault to expose via useThree
• ScrollControls — scroll-driven scenes; pair with useScroll inside useFrame
• PresentationControls — spring-animated drag; no OrbitControls needed
• KeyboardControls — typed key state context; read imperatively via get() in useFrame

Staging

• Environment — IBL from preset ('sunset' | 'warehouse' | 'city' |...) or custom HDR
• Stage — one-component scene staging: lighting, camera fit, shadows
• ContactShadows — fake soft shadow on a plane; cheaper than shadow maps
• Float — floating/bobbing idle animation for hero objects

Shapes / Content

• Text — SDF 3D text with font loading, line wrapping, outlines
• Html — embed DOM content in 3D; supports occlude and transform

Loaders

• useGLTF — load and cache GLTF/GLB; auto-configures Draco CDN decoder
• useTexture — load and cache textures; object form for PBR maps

Performance

• Instances / Instance — instanced meshes with simple component API
• Detailed — LOD: show different meshes by camera distance
• PerformanceMonitor — FPS callbacks; pair with AdaptiveDpr

Materials

• MeshTransmissionMaterial — physically-based glass with refraction and chromatic aberration

Asset Pipeline

GLTF Loading

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

function Model(props) {
  const { nodes, materials } = useGLTF('/model.glb')
  return (
    <group {...props} dispose={null}>
      <mesh geometry={nodes.Body.geometry} material={materials.Metal} castShadow />
    </group>
  )
}

useGLTF.preload('/model.glb')

// Wrap in Suspense
<Canvas>
  <Suspense fallback={null}>
    <Model />
  </Suspense>
</Canvas>

gltfjsx CLI

# Generate TypeScript component + Draco-compress the GLB
npx gltfjsx model.glb --transform --types --shadows
# Outputs: model-transformed.glb (move to /public) + Model.tsx (move to /src/components)

--transform shrinks most models 70–90% via Draco geometry compression, 1024px texture resize, and WebP conversion.

For clone pattern, KTX2 textures, lazy loading, and parallel preloading, read references/r3f-patterns.md.

Performance Rules

Draw call budgets:

• Mobile: < 100 draw calls
• Desktop: < 300 draw calls

The 7 anti-patterns — never do these:

1. Never setState inside useFrame — mutate refs directly
2. Always use delta for animation — never fixed increments
3. Never setState in onPointerMove — mutate refs directly
4. Never read reactive store state in useFrame — use store.getState() imperative form
5. Never conditionally mount/unmount in render loop — use visible prop instead
6. Never create new THREE.Vector3() inside useFrame — allocate outside, reuse with .set()
7. Never create duplicate geometries/materials for identical meshes — share via useMemo or Instances

Disposal: Always call geometry.dispose() and material.dispose() in useEffect cleanup for dynamically created Three.js objects.

Read references/performance.md for all 7 anti-patterns with wrong/correct code pairs, texture optimization, frustum culling, stats tooling, and mobile rules.

State, Physics, Debug GUI, and WebGPU

For these topics, read references/extras.md:

• Zustand imperative pattern (required for useFrame correctness)
• Leva debug GUI setup
• Rapier physics quick start
• WebGPU renderer bootstrap

For the full Rapier v2 API (all collider types, collision events, sensors, joints, forces, InstancedRigidBodies), read references/physics.md.

Reference Files

• references/scene-setup.md — Minimal scene template, Canvas defaults, frameloop, responsive canvas, WebGPU renderer
• references/r3f-patterns.md — Canvas props, useFrame, useThree, event system, scroll-driven scenes, GLTF clone pattern, KTX2, lazy loading
• references/drei-helpers.md — Full Drei inventory by category: every helper with import, key props, and example
• references/performance.md — All 7 anti-patterns with wrong/correct code, instancing, LOD, texture compression, disposal checklist, mobile rules
• references/physics.md — Full Rapier v2: colliders, collision events, sensors, 6 joints, forces/impulses, InstancedRigidBodies
• references/extras.md — Zustand imperative pattern, Leva debug GUI, Rapier quick start, WebGPU bootstrap