90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# Skill — React Three Fiber
|
|
|
|
## Component pattern
|
|
|
|
Every 3D scene object is a React component. No class-based scene objects.
|
|
|
|
```tsx
|
|
import { useRef } from "react";
|
|
import * as THREE from "three";
|
|
import { useFrame } from "@react-three/fiber";
|
|
import { useGLTF } from "@react-three/drei";
|
|
|
|
export function MyObject() {
|
|
const ref = useRef<THREE.Group>(null);
|
|
const gltf = useGLTF("/models/my-object.glb");
|
|
|
|
useFrame((_, delta) => {
|
|
// per-frame logic here
|
|
});
|
|
|
|
return <primitive ref={ref} object={gltf.scene.clone()} />;
|
|
}
|
|
```
|
|
|
|
## Rules
|
|
|
|
- Scene components return JSX with Three.js elements (`<mesh>`, `<group>`, `<primitive>`)
|
|
- Use `useRef` for mutable per-frame values — never `useState`
|
|
- Use `useFrame` for animation loops — never `requestAnimationFrame`
|
|
- Use `useGLTF` / `useTexture` from drei for asset loading — they handle caching
|
|
- Clone scenes with `.clone()` when reusing a GLTF in multiple places
|
|
- Cleanup in `useEffect` return — stop AnimationMixers, dispose owned resources
|
|
|
|
## Loading assets
|
|
|
|
```tsx
|
|
// Models
|
|
const gltf = useGLTF("/models/workshop/ebike.glb");
|
|
|
|
// Textures
|
|
const [diffuse, normal] = useTexture([
|
|
"/textures/wall_diffuse.jpg",
|
|
"/textures/wall_normal.jpg",
|
|
]);
|
|
|
|
// Preload (call outside component)
|
|
useGLTF.preload("/models/map/base.glb");
|
|
```
|
|
|
|
## Physics (Rapier)
|
|
|
|
```tsx
|
|
import { RigidBody, CuboidCollider } from "@react-three/rapier";
|
|
|
|
<RigidBody type="fixed">
|
|
<CuboidCollider args={[10, 0.1, 10]} />
|
|
<mesh>
|
|
<boxGeometry args={[20, 0.2, 20]} />
|
|
<meshStandardMaterial />
|
|
</mesh>
|
|
</RigidBody>;
|
|
```
|
|
|
|
- Wrap physics scene in `<Physics>` component
|
|
- `type="fixed"` for static colliders (ground, walls)
|
|
- `type="dynamic"` for movable objects
|
|
- Player uses `type="dynamic"` with `lockRotations`
|
|
|
|
## Postprocessing
|
|
|
|
```tsx
|
|
import { EffectComposer, Bloom, Vignette } from "@react-three/postprocessing";
|
|
|
|
<EffectComposer>
|
|
<Bloom intensity={0.5} luminanceThreshold={0.9} />
|
|
<Vignette offset={0.3} darkness={0.5} />
|
|
</EffectComposer>;
|
|
```
|
|
|
|
- Always wrap in `<EffectComposer>`
|
|
- Keep effects minimal for performance
|
|
- Disable heavy effects on low-end devices via Debug panel
|
|
|
|
## What NOT to do
|
|
|
|
- Do not use `new THREE.Scene()` or `new THREE.WebGLRenderer()` — R3F handles this
|
|
- Do not use `requestAnimationFrame` — use `useFrame`
|
|
- Do not store per-frame values in `useState` — use `useRef`
|
|
- Do not manually append to DOM — everything goes through `<Canvas>`
|