用途:帮助在 Three.js 中搭建和管理场景图,包括创建 Scene、向场景添加对象、维护父子层级、遍历与查找对象,以及组织 3D 内容。
主要能力:
- 场景图层级:Object3D 是所有 3D 对象的基类,提供变换、层级与遍历;Scene 为根容器,支持 background、environment、fog、overrideMaterial;Group 为无语义附加功能的逻辑容器;Mesh 由几何体与材质组成;Camera 和 Light 始终应加入场景以获得矩阵更新与渲染。
- Object3D 属性:position、rotation、quaternion(与 rotation 联动)、scale、visible(false 时跳过自身及全部后代)、layers、castShadow、receiveShadow、frustumCulled、renderOrder、name、userData,以及只读的 uuid、id、type。
- 层级方法:使用 add()、remove()、removeFromParent()、clear()、attach()。重挂载时 add() 保留局部变换,attach() 保留世界变换;remove() 对非子对象静默无操作。
- 遍历与查找:traverse()、traverseVisible()、traverseAncestors()、getObjectByName()、getObjectById()、getObjectByProperty();查找为 O(n),频繁使用应缓存引用。
- 矩阵系统:默认渲染前自动调用 updateMatrixWorld();静态对象可设 matrixAutoUpdate=false 手动 compose。同帧修改变换后需先 updateWorldMatrix(true, false) 再读矩阵或世界位置。
- 场景属性与雾:background、environment、environmentIntensity、environmentRotation、fog(Fog 线性、FogExp2 指数)、overrideMaterial 等。
- Layers:32 位掩码,支持 set/enable/disable/toggle 与 camera.layers.test(),用于选择性渲染与射线检测。
使用方式:按需从 'three' 导入 Scene、Group、Mesh、BoxGeometry、MeshStandardMaterial、Color、Fog、FogExp2、TextureLoader、Vector3、Quaternion、Layers 等类使用。lookAt() 需在设置 position 后调用;相机使负 Z 指向目标,非相机对象使正 Z 指向目标。
适用场景:搭建三维场景、对象分组与变换、按名称或属性查找对象、分层渲染(如辅助线、泛光对象)、选择性射线检测、调试用统一材质等。
限制与注意:不要直接修改 children 数组;遍历中不要增删对象;删除对象不会释放 GPU 内存,需手动 dispose 纹理、几何体和材质;userData 不会自动清理;ShaderMaterial 与 RawShaderMaterial 的 fog 默认 false,需手动设置并加入雾着色器片段。具体安装命令与版本信息资料中暂未提供。