136 lines
2.8 KiB
Plaintext
136 lines
2.8 KiB
Plaintext
---
|
||
description: 3D 工程师规范 - Three.js 渲染、模型处理、资源管理
|
||
alwaysApply: false
|
||
---
|
||
|
||
# 3D 工程师规范
|
||
|
||
## 一、技术栈
|
||
|
||
| 库 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Three.js | 0.182.0 | 3D 渲染核心 |
|
||
| @react-three/fiber | 9.5.0 | React 集成 |
|
||
| @react-three/drei | 10.7.7 | 常用工具 |
|
||
| GSAP | - | 动画 |
|
||
|
||
---
|
||
|
||
## 二、目录结构
|
||
|
||
```
|
||
src/components/3d/
|
||
├── Scene.tsx # 主场景
|
||
├── ModelViewer.tsx # 模型查看器
|
||
├── AnimationEngine.ts # 动画引擎
|
||
└── controls/ # 控制器
|
||
|
||
src/lib/three/
|
||
├── loaders/ # 加载器
|
||
├── materials/ # 材质
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
---
|
||
|
||
## 三、资源清理（必须）
|
||
|
||
组件卸载时必须清理所有资源：
|
||
|
||
```typescript
|
||
public dispose(): void {
|
||
// 1. 停止动画循环
|
||
if (this.animationId) {
|
||
cancelAnimationFrame(this.animationId)
|
||
}
|
||
|
||
// 2. 移除事件监听
|
||
window.removeEventListener('resize', this.handleResize)
|
||
|
||
// 3. 深度清理场景对象
|
||
this.scene.traverse((obj) => {
|
||
if (obj instanceof THREE.Mesh) {
|
||
obj.geometry?.dispose()
|
||
this.disposeMaterial(obj.material)
|
||
}
|
||
})
|
||
|
||
// 4. 清理控制器和渲染器
|
||
this.controls?.dispose()
|
||
this.renderer?.dispose()
|
||
this.renderer?.forceContextLoss()
|
||
}
|
||
|
||
private disposeMaterial(material: THREE.Material | THREE.Material[]): void {
|
||
const materials = Array.isArray(material) ? material : [material]
|
||
for (const mat of materials) {
|
||
// 清理所有贴图
|
||
;['map', 'normalMap', 'roughnessMap', 'metalnessMap'].forEach((key) => {
|
||
const texture = mat[key]
|
||
if (texture) texture.dispose()
|
||
})
|
||
mat.dispose()
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、GSAP 动画清理
|
||
|
||
```typescript
|
||
dispose(): void {
|
||
if (this.currentTimeline) {
|
||
this.currentTimeline.kill()
|
||
this.currentTimeline = null
|
||
}
|
||
|
||
if (this.scene) {
|
||
this.scene.traverse((object) => {
|
||
gsap.killTweensOf(object)
|
||
gsap.killTweensOf(object.position)
|
||
gsap.killTweensOf(object.rotation)
|
||
gsap.killTweensOf(object.scale)
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 五、性能优化
|
||
|
||
### LOD 策略
|
||
根据距离切换模型精度
|
||
|
||
### 内存管理
|
||
- 及时释放 geometry、material、texture
|
||
- 避免在循环中创建新对象
|
||
|
||
### 渲染优化
|
||
- 使用 `React.memo` 包装组件
|
||
- 避免不必要的重渲染
|
||
|
||
---
|
||
|
||
## 六、模型存储
|
||
|
||
```
|
||
public/uploads/models/
|
||
├── demo/ # 演示模型
|
||
└── {productId}/ # 按产品ID组织
|
||
├── original/ # 原始上传文件（DWG等）
|
||
└── model.glb # 转换后的 3D 模型
|
||
```
|
||
|
||
---
|
||
|
||
## 七、禁止事项
|
||
|
||
```
|
||
❌ 组件卸载时不清理资源
|
||
❌ 不清理事件监听器
|
||
❌ 不停止 GSAP 动画
|
||
❌ 在循环中创建新对象
|
||
```
|