threejs-agents-scene-builder

threejs-agents-scene-builder

用途

此技能是用于构建完整 Three.js 场景的编排指南。它提供决策树，将不同用例映射到合适的照明、材质、相机、控制、环境和后期处理组合。创建 3D 场景或可视化时，务必先查阅此技能。

---

主决策树：从用例到场景方案

第 1 步：识别用例

用例	前往
产品查看器 / 配置器	方案 A
建筑漫游	方案 B
游戏关卡 / 交互式 3D	方案 C
数据可视化 / 图表	方案 D
作品集 / 主视觉区块	方案 E
CAD / BIM / IFC 查看器	方案 F
AR / XR 体验	方案 G

第 2 步：选择 R3F 或命令式方案

条件	决策
项目使用 React	务必使用 React Three Fiber（R3F）
项目使用 Vue、Svelte 或原生 JavaScript	务必使用命令式 Three.js
需要对渲染循环进行最大程度的控制	优先使用命令式 Three.js
需要快速原型开发和组件复用	优先使用 R3F + Drei
静态场景，无交互框架	两者均可；命令式方案更轻量

交叉参考：threejs-impl-r3f 查看 R3F 模式，threejs-core-scene-graph 查看命令式模式。

---

决策树：照明设置

第 1 步：根据场景类型选择照明策略

场景类型	主光源	补光	阴影
户外 / 日光	DirectionalLight（太阳）	HemisphereLight（天空 / 地面）	DirectionalLight 阴影，PCFSoftShadowMap
室内 / 房间	PointLight 或 SpotLight（灯具）	AmbientLight（低强度）	SpotLight 阴影，限制为 2-3 个
摄影棚 / 产品	SpotLight（主光）+ SpotLight（轮廓光）	AmbientLight 或 HemisphereLight	ContactShadows（Drei）或 AccumulativeShadows
风格化 / 卡通渲染	DirectionalLight	HemisphereLight	可选；硬边缘使用 BasicShadowMap
仅 HDR 环境	无（IBL 提供所有照明）	无	ContactShadows 或 AccumulativeShadows
夜间 / 黑暗场景	SpotLight（聚焦光池）	AmbientLight（极低，~0.05）	SpotLight 阴影

第 2 步：照明强度（物理正确，r160+）

光源类型	单位	典型室内值	典型户外值
DirectionalLight	lux	1-5	1-3（取决于场景比例）
PointLight	candela	50-200	不适用
SpotLight	candela	100-500	不适用
AmbientLight	无单位	0.1-0.5	0.2-0.5
HemisphereLight	无单位	0.3-0.8	0.5-1.0

第 3 步：光源数量预算

平台	实时光源上限	投射阴影的光源上限
移动设备	3-4	1（仅 DirectionalLight）
桌面设备	8-16	2-3（移动设备上绝不能使用 PointLight 阴影）
高端设备	16+（使用 TiledLighting）	4-5

重要规则：

• 移动设备上绝不能使用 PointLight 阴影——每个阴影都需要渲染 6 次阴影贴图
• 重新定位目标时，务必将 directionalLight.target 添加到场景中
• 创建 RectAreaLight 前，务必调用 RectAreaLightUniformsLib.init()

交叉参考：threejs-impl-lighting-shadows 查看阴影调优和伪影修复。

---

决策树：材质选择

视觉目标	材质	说明
写实 / PBR	MeshStandardMaterial	大多数场景的默认选择
写实 + 清漆层、透射、光泽	MeshPhysicalMaterial	开销高于 Standard；仅在需要时使用
卡通 / 色调着色	MeshToonMaterial	需要使用 gradientMap 纹理来设置色阶
无光照 / 平面颜色	MeshBasicMaterial	零光照开销；适用于线框和 UI
对性能要求高（大量对象）	MeshLambertMaterial	顶点光照；开销低于 Standard
玻璃 / 透明	MeshPhysicalMaterial (transmission: 1)	或在 R3F 中使用 Drei 的 MeshTransmissionMaterial
反射地面	Drei MeshReflectorMaterial	仅适用于 R3F
自定义着色器	ShaderMaterial 或 RawShaderMaterial	完全控制 GLSL
基于节点（WebGPU）	MeshStandardNodeMaterial	TSL 节点系统；r160+

关键规则：

• 仅当 MeshStandardMaterial 无法满足需求时才使用 MeshPhysicalMaterial——它的开销明显更高
• 更改 defines 或 extensions 后，始终设置 material.needsUpdate = true
• 从场景中移除对象时，始终释放材质

交叉参考： threejs-syntax-materials，了解材质属性和纹理。

---

决策树：相机选择

使用场景	相机类型	典型设置
大多数 3D 场景	PerspectiveCamera	fov: 50-75、near: 0.1、far: 1000
产品查看器（无透视畸变）	PerspectiveCamera	fov: 35-45（视角越窄，畸变越小）
建筑场景（广角）	PerspectiveCamera	fov: 60-90
2D 游戏 / 等距视图	OrthographicCamera	视锥体尺寸与世界单位匹配
CAD / 技术绘图	OrthographicCamera	始终使用
数据可视化（平面）	OrthographicCamera	视锥体 = 数据范围
电影感 / 戏剧化效果	PerspectiveCamera	fov: 20-35（长焦效果）

关键规则：

• 更改 fov、near、far 或 aspect 后，始终调用 camera.updateProjectionMatrix()
• 切勿将 near 设为 0——这会导致整个场景出现 z-fighting
• 始终尽可能缩小 near/far 比值（理想情况下小于 1:10000）

交叉参考： threejs-core-renderer-camera，了解相机 API 详情。

---

决策树：控件选择

交互模式	控件	说明
绕对象旋转（最常见）	OrbitControls	始终启用阻尼
地图 / 俯视导航	MapControls	左键拖动 = 平移，右键拖动 = 旋转
第一人称 / 漫游	PointerLockControls	需要指针锁定 API
飞行穿越（6DOF）	FlyControls	键盘 + 鼠标
拖动旋转（演示）	Drei PresentationControls	仅适用于 R3F；弹簧物理效果
滚动驱动动画	Drei ScrollControls	仅适用于 R3F
对象操作（平移 / 旋转 / 缩放）	TransformControls	附加到选定对象
适用于移动设备的环绕操作	OrbitControls	内置触控手势

关键规则：

• 当 enableDamping 为 true 时，始终在动画循环中调用 controls.update()
• 清理时始终调用 controls.dispose()
• 变换交互期间，若不禁用 OrbitControls，切勿将其与 TransformControls 同时使用

交叉参考： threejs-syntax-controls，了解控件 API 详情。

---

决策树：环境设置

视觉目标	方案	实现
逼真的反射 + 环境光	HDR 环境贴图	scene.environment = pmremGenerator.fromEquirectangular(hdrTexture)
纯色背景	scene.background = new Color(...)	最简单的选项
渐变背景	在背景平面上使用自定义着色器	或在透明画布后使用 CSS 渐变
天空盒	在 scene.background 上使用 CubeTexture	6 张面图像
程序化天空	Drei <Sky> 或 Three.js Sky 插件	动态太阳位置
无背景（透明）	renderer = new WebGLRenderer({ alpha: true })	由 CSS 控制后方显示的内容
R3F 环境	Drei <Environment preset="studio" />	预设：apartment、city、dawn、forest、lobby、night、park、studio、sunset、warehouse

关键规则：

• 务必使用 PMREMGenerator 对环境贴图进行预过滤，以供 PBR 材质使用
• 切勿将未经处理的 HDR 纹理用作 scene.environment——必须先经过 PMREM 处理
• 设置 scene.environment 会自动为所有 PBR 材质提供 IBL

交叉参考： threejs-syntax-materials，了解材质上的环境贴图用法。

---

决策树：后期处理

何时添加后期处理

条件	决策
场景显得平淡或缺乏纵深感	添加 SSAO/GTAO + 轻微辉光
需要光晕 / 自发光高光	添加 UnrealBloomPass
需要抗锯齿（无 MSAA）	添加 FXAA 或 SMAA
电影质感	添加 BokehPass（景深）+ FilmPass（颗粒）+ LUTPass（色彩分级）
轮廓选中效果	添加 OutlinePass
性能至关重要（移动设备）	切勿添加后期处理；使用烘焙效果

后期处理管线顺序

务必遵循以下通道顺序：

1. RenderPass（美观渲染）——务必放在最前
2. 几何通道：SSAO、GTAO、SSR
3. 效果通道：Bloom、DoF、Outline
4. 抗锯齿：FXAA 或 SMAA
5. 色彩分级：LUT、Film
6. OutputPass（色调映射 + 色彩空间）——务必放在最后

R3F 后期处理

在 R3F 中，使用 @react-three/postprocessing（封装 pmndrs/postprocessing 库）：

import { EffectComposer, Bloom, SSAO } from '@react-three/postprocessing'

<EffectComposer>
  <SSAO />
  <Bloom luminanceThreshold={0.9} intensity={0.5} />
</EffectComposer>

关键规则：

• 窗口大小变化时务必调整 composer 的尺寸：composer.setSize(w, h)
• 切勿忘记在末尾添加 OutputPass——否则会跳过色调映射和色彩空间转换
• 在 R3F 中，@react-three/postprocessing 会自动处理通道顺序

交叉参考： threejs-impl-postprocessing，了解通道配置和调优。

---

场景构建检查清单

构建场景时务必遵循此检查清单：

1. 渲染器——创建 WebGLRenderer，设置 antialias: true、像素比和尺寸
2. 场景——创建 Scene，设置背景和／或环境
3. 相机——根据决策树选择类型，设置位置
4. 光照——根据决策树选择方案，遵守预算
5. 地面／环境——添加地面平面、环境贴图或天空
6. 内容——添加几何体、加载模型、创建材质
7. 控制器——根据决策树选择，配置约束
8. 阴影——在渲染器、光源和对象上启用（3 步显式启用）
9. 后期处理——按需添加，并遵循管线顺序
10. 尺寸调整处理——务必处理窗口尺寸变化（相机 + 渲染器 + composer）
11. 动画循环——使用 requestAnimationFrame 或 R3F useFrame
12. 资源释放——清理时务必释放几何体、材质和纹理

---

性能速查

优化项	适用时机
InstancedMesh	超过 50 个相同对象
LOD（Level of Detail）	包含远处对象的大型场景
frustumCulled: true（默认值）	始终保持启用，除非对象必须在屏幕外渲染
matrixAutoUpdate: false	永远不会移动的静态对象
纹理压缩（KTX2/Basis）	生产环境始终启用；可将 GPU 内存占用降低 4～6 倍
合并几何体	材质相同的多个小型静态网格
frameloop="demand"（R3F）	静态场景／配置器
烘焙光照	静态环境
对象池	频繁创建／销毁的对象

交叉参考： threejs-errors-performance，了解详细的优化策略。

---

参考链接

• references/methods.md — 含详细选择标准的决策树
• references/examples.md — 各类用例的完整场景方案
• references/anti-patterns.md — 常见的场景构成错误

相关技能

技能	适用时机
threejs-core-scene-graph	场景层级、Object3D API、释放资源
threejs-core-renderer-camera	渲染器设置、相机配置
threejs-core-math-transforms	向量、矩阵、坐标变换
threejs-syntax-geometry	BufferGeometry、内置形状、InstancedMesh
threejs-syntax-materials	材质属性、纹理、环境贴图
threejs-syntax-loaders	GLTF、FBX、OBJ 加载与优化
threejs-syntax-controls	相机控制设置与配置
threejs-impl-lighting-shadows	光源类型、阴影配置、伪影
threejs-impl-animation	关键帧动画、变形目标、骨骼动画
threejs-impl-postprocessing	EffectComposer、泛光、SSAO、抗锯齿
threejs-impl-physics	Rapier/Cannon.js 集成
threejs-impl-r3f	React Three Fiber 模式与钩子
threejs-impl-webgpu	WebGPU 渲染器、TSL 节点材质
threejs-impl-ifc	IFC/BIM 模型加载与处理
threejs-errors-performance	FPS 优化、内存泄漏、绘制调用
threejs-errors-rendering	视觉伪影、深度冲突、颜色问题
threejs-agents-model-optimizer	GLTF 优化、压缩、LOD 生成

官方来源

• https://threejs.org/docs/
• https://threejs.org/examples/
• https://r3f.docs.pmnd.rs/
• https://drei.docs.pmnd.rs/