Antigravity Agent
317 lines
6.9 KiB
Markdown
317 lines
6.9 KiB
Markdown
---
|
|
id: frontend-three-r3f
|
|
title: Three.js / React Three Fiber — 3D 웹
|
|
category: Coding
|
|
status: draft
|
|
source_trust_level: B
|
|
verification_status: conceptual
|
|
created_at: 2026-05-09
|
|
updated_at: 2026-05-09
|
|
tags: [frontend, 3d, threejs, r3f, vibe-coding]
|
|
tech_stack: { language: "TS / React", applicable_to: ["Frontend"] }
|
|
applied_in: []
|
|
aliases: [Three.js, React Three Fiber, drei, Rapier, Spline, WebGL]
|
|
---
|
|
|
|
# Three.js / R3F (React Three Fiber)
|
|
|
|
> Web 3D 표준. **Three.js (vanilla) / React Three Fiber (React)** + **drei (helpers)** + **Rapier (physics)**. WebGL → WebGPU 미래.
|
|
|
|
## 📖 핵심 개념
|
|
- Scene: 3D 공간.
|
|
- Mesh: geometry + material.
|
|
- Camera: 시점.
|
|
- Light: 조명.
|
|
- Renderer: WebGL / WebGPU.
|
|
|
|
## 💻 코드 패턴
|
|
|
|
### 기본 R3F
|
|
```tsx
|
|
import { Canvas, useFrame } from '@react-three/fiber';
|
|
import { OrbitControls, Box } from '@react-three/drei';
|
|
import { useRef } from 'react';
|
|
|
|
function RotatingBox() {
|
|
const ref = useRef<THREE.Mesh>(null);
|
|
useFrame((_, delta) => {
|
|
ref.current!.rotation.y += delta;
|
|
});
|
|
return (
|
|
<Box ref={ref} args={[1, 1, 1]}>
|
|
<meshStandardMaterial color="orange" />
|
|
</Box>
|
|
);
|
|
}
|
|
|
|
export function Scene() {
|
|
return (
|
|
<Canvas camera={{ position: [3, 3, 5] }}>
|
|
<ambientLight intensity={0.5} />
|
|
<directionalLight position={[5, 5, 5]} intensity={1} />
|
|
<RotatingBox />
|
|
<OrbitControls />
|
|
</Canvas>
|
|
);
|
|
}
|
|
```
|
|
|
|
### drei (helpers)
|
|
```tsx
|
|
import {
|
|
OrbitControls, Environment, ContactShadows, Float,
|
|
Text, Html, useGLTF, useTexture, PerspectiveCamera, Stage,
|
|
} from '@react-three/drei';
|
|
|
|
<Canvas>
|
|
<Stage>
|
|
<Float speed={2} rotationIntensity={0.5}>
|
|
<mesh>...</mesh>
|
|
</Float>
|
|
</Stage>
|
|
|
|
<Text fontSize={1} color="white">Hello 3D</Text>
|
|
|
|
<Html position={[0, 2, 0]}>
|
|
<div>HTML overlay</div>
|
|
</Html>
|
|
</Canvas>
|
|
```
|
|
|
|
### GLTF 모델 로드
|
|
```tsx
|
|
function Model() {
|
|
const { scene, animations } = useGLTF('/model.glb');
|
|
return <primitive object={scene} />;
|
|
}
|
|
|
|
// Optimization — useGLTF preload
|
|
useGLTF.preload('/model.glb');
|
|
```
|
|
|
|
→ DRACO compression 자동 (drei 가).
|
|
|
|
### Animation (모델)
|
|
```tsx
|
|
import { useAnimations } from '@react-three/drei';
|
|
|
|
function AnimatedModel() {
|
|
const ref = useRef<THREE.Group>(null);
|
|
const { scene, animations } = useGLTF('/dancer.glb');
|
|
const { actions } = useAnimations(animations, ref);
|
|
|
|
useEffect(() => {
|
|
actions.idle?.play();
|
|
}, []);
|
|
|
|
return <primitive ref={ref} object={scene} />;
|
|
}
|
|
```
|
|
|
|
### Physics (Rapier)
|
|
```tsx
|
|
import { Physics, RigidBody } from '@react-three/rapier';
|
|
|
|
<Canvas>
|
|
<Physics gravity={[0, -9.81, 0]}>
|
|
<RigidBody>
|
|
<Box position={[0, 5, 0]} />
|
|
</RigidBody>
|
|
<RigidBody type="fixed">
|
|
<Plane args={[10, 10]} rotation={[-Math.PI / 2, 0, 0]} />
|
|
</RigidBody>
|
|
</Physics>
|
|
</Canvas>
|
|
```
|
|
|
|
### Material
|
|
```tsx
|
|
<mesh>
|
|
<boxGeometry args={[1, 1, 1]} />
|
|
<meshStandardMaterial
|
|
color="hotpink"
|
|
metalness={0.5}
|
|
roughness={0.3}
|
|
map={texture}
|
|
/>
|
|
</mesh>
|
|
|
|
// MeshPhysicalMaterial — 더 사실적
|
|
<meshPhysicalMaterial
|
|
clearcoat={1}
|
|
transmission={0.5} // 반투명 / glass
|
|
thickness={0.5}
|
|
ior={1.5}
|
|
/>
|
|
```
|
|
|
|
### Shader (custom GLSL)
|
|
```glsl
|
|
// vertex.glsl
|
|
varying vec2 vUv;
|
|
void main() {
|
|
vUv = uv;
|
|
gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
|
|
}
|
|
|
|
// fragment.glsl
|
|
varying vec2 vUv;
|
|
uniform float uTime;
|
|
void main() {
|
|
vec3 color = vec3(sin(vUv.x + uTime), sin(vUv.y + uTime), 1.0);
|
|
gl_FragColor = vec4(color, 1.0);
|
|
}
|
|
```
|
|
|
|
```tsx
|
|
<mesh>
|
|
<planeGeometry args={[2, 2]} />
|
|
<shaderMaterial
|
|
vertexShader={vertexShader}
|
|
fragmentShader={fragmentShader}
|
|
uniforms={{ uTime: { value: 0 } }}
|
|
/>
|
|
</mesh>
|
|
```
|
|
|
|
### Post-processing
|
|
```tsx
|
|
import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing';
|
|
|
|
<Canvas>
|
|
<Scene />
|
|
<EffectComposer>
|
|
<Bloom intensity={1.5} luminanceThreshold={0.5} />
|
|
<ChromaticAberration offset={[0.001, 0.001]} />
|
|
</EffectComposer>
|
|
</Canvas>
|
|
```
|
|
|
|
### Performance
|
|
```tsx
|
|
// Instances (수천 mesh)
|
|
import { Instances, Instance } from '@react-three/drei';
|
|
|
|
<Instances limit={1000}>
|
|
<boxGeometry />
|
|
<meshStandardMaterial />
|
|
{data.map((d, i) => (
|
|
<Instance key={i} position={d.pos} color={d.color} />
|
|
))}
|
|
</Instances>
|
|
```
|
|
|
|
```tsx
|
|
// LOD (Level of Detail)
|
|
import { Detailed } from '@react-three/drei';
|
|
|
|
<Detailed distances={[0, 10, 20]}>
|
|
<HighDetailMesh />
|
|
<MidDetailMesh />
|
|
<LowDetailMesh />
|
|
</Detailed>
|
|
```
|
|
|
|
```tsx
|
|
// Frustum culling 자동
|
|
// Manual: ref.current.frustumCulled = true (default)
|
|
|
|
// Shadows — 비싸. 작은 set 만
|
|
<directionalLight castShadow shadow-mapSize={[1024, 1024]} />
|
|
<mesh receiveShadow castShadow>
|
|
```
|
|
|
|
### Mobile / WebGL fallback
|
|
```tsx
|
|
// 작은 화면 / GPU = quality down
|
|
const isMobile = useMediaQuery('(max-width: 768px)');
|
|
<Canvas dpr={isMobile ? 1 : 2} shadows={!isMobile}>
|
|
```
|
|
|
|
### WebGPU (미래)
|
|
```tsx
|
|
import { WebGPURenderer } from 'three/examples/jsm/renderers/webgpu/WebGPURenderer.js';
|
|
|
|
<Canvas
|
|
gl={(canvas) => new WebGPURenderer({ canvas })}
|
|
>
|
|
```
|
|
|
|
→ WebGL 보다 빠름. 2025+ stable.
|
|
|
|
### React-spring + R3F
|
|
```tsx
|
|
import { useSpring, animated } from '@react-spring/three';
|
|
|
|
const { position } = useSpring({ position: hovered ? [0, 1, 0] : [0, 0, 0] });
|
|
<animated.mesh position={position} ... />
|
|
```
|
|
|
|
### 화면 → 3D coordinates
|
|
```ts
|
|
import { useThree } from '@react-three/fiber';
|
|
|
|
function ClickToWorld() {
|
|
const { camera, raycaster, mouse } = useThree();
|
|
|
|
const handle = (e: MouseEvent) => {
|
|
raycaster.setFromCamera(mouse, camera);
|
|
// raycaster.ray 로 intersection
|
|
};
|
|
}
|
|
```
|
|
|
|
### Spline (no-code 3D)
|
|
```tsx
|
|
import Spline from '@splinetool/react-spline';
|
|
|
|
<Spline scene="https://prod.spline.design/xxx/scene.splinecode" />
|
|
```
|
|
|
|
→ Designer 가 Spline app 에서 만들고 R3F 가 import.
|
|
|
|
### Bundle size 주의
|
|
```
|
|
Three.js: ~600KB (큰)
|
|
+ drei, postprocessing, rapier ...
|
|
|
|
→ Dynamic import + code split
|
|
```
|
|
|
|
```tsx
|
|
const Scene = lazy(() => import('./Scene'));
|
|
<Suspense fallback={<Loader />}>
|
|
<Scene />
|
|
</Suspense>
|
|
```
|
|
|
|
## 🤔 의사결정 기준
|
|
| 상황 | 추천 |
|
|
|---|---|
|
|
| Product showcase | R3F + drei + GLTF |
|
|
| Game | R3F + Rapier physics |
|
|
| Data viz | R3F + custom shader |
|
|
| Designer 만든 scene | Spline |
|
|
| 매우 simple (1-2 model) | <model-viewer> |
|
|
| 강력 / vanilla | Three.js direct |
|
|
|
|
## ❌ 안티패턴
|
|
- **모든 frame setState**: re-render. useFrame 안 ref.
|
|
- **Shadow 모든 light + 큰 mapSize**: 60fps 깨짐.
|
|
- **너무 많은 mesh (1000+)**: Instances.
|
|
- **모델 압축 안 함 (GLB 100MB)**: load 느림. DRACO + Meshopt.
|
|
- **WebGL fallback 없음 + GPU 약**: blank 화면.
|
|
- **Mobile 무 dpr 2**: 발열.
|
|
- **Memory leak (useEffect cleanup 없음)**: GPU resources 안 release.
|
|
|
|
## 🤖 LLM 활용 힌트
|
|
- R3F + drei + Rapier 가 표준 stack.
|
|
- GLTF + DRACO compression.
|
|
- Instances / LOD / shadow 절제.
|
|
- Suspense + lazy load.
|
|
|
|
## 🔗 관련 문서
|
|
- [[Frontend_Animation_Motion]]
|
|
- [[Web_Performance_Core_Vitals]]
|
|
- [[Perf_Bundle_Analysis]]
|