threejs-helpers

何时使用此技能

用户提到以下内容时，始终使用此技能：

• 可视化坐标轴、网格、相机视锥体、阴影相机、光照方向
• 显示骨骼、包围盒、网格检查用的法线／切线
• 通过辅助类可视化光照探针或矩形区域光

重要：辅助对象与生产网格

• 辅助对象是调试对象；不要将其用作最终场景几何体。

触发短语包括：

• "AxesHelper", "GridHelper", "CameraHelper", "SkeletonHelper", "VertexNormalsHelper"
• "辅助线", "法线显示", "包围盒调试"

如何使用此技能

1. 附加辅助对象到其描述的对象上（例如，CameraHelper(light.shadow.camera)）。
2. 更新移动的目标对象——有些辅助对象需要逐帧刷新。
3. 在生产构建中移除辅助对象，或通过调试标志控制其启用。
4. **性能：**辅助对象会增加绘制调用——分析性能问题时请禁用。
5. **附加组件：**按照 threejs-dev-setup 的约定，从 three/addons/helpers/... 路径导入。

参见 examples/workflow-light-camera-helpers.md。

文档索引（官方）

文档章节	代表性链接
辅助对象	https://threejs.org/docs/AxesHelper.html
辅助对象	https://threejs.org/docs/GridHelper.html
辅助对象	https://threejs.org/docs/CameraHelper.html
辅助对象	https://threejs.org/docs/SkeletonHelper.html

范围

• **范围内：**用于可视化的核心库与附加组件辅助对象。
• **范围外：**生产网格或正式发布的美术资源（threejs-geometries、threejs-lights）；轨道／变换操纵器的行为（threejs-controls）；与 DCC 工具的编辑器 UX 对齐；超出辅助对象存根范围的物理调试。

常见问题与最佳实践

• 辅助对象过多会遮挡视图——按子系统切换显示。
• 附加到错误的父对象会导致辅助对象变换错位。
• 辅助对象会继承场景图变换——将其设为调试组的子对象，以便批量隐藏／显示。
• 有些辅助对象会产生额外的几何体开销；在生产环境中移除，或使用 #ifdef DEBUG 样式的标志控制。
• 阴影相机的 CameraHelper 必须引用 light.shadow.camera，而不是主视图相机。

文档与版本

辅助对象列于 Helpers（核心库）以及 three.js 文档中的 Addons → Helpers。它们仅用于调试；生产网格和光照应使用真实几何体／光源（threejs-geometries、threejs-lights）。

Agent 回复检查清单

使用此技能回答时，优先采用以下做法：

1. 链接所用的辅助类（AxesHelper、CameraHelper 等）。
2. 说明辅助对象不是正式发布的美术资源——应移除，或通过调试标志控制。
3. 将阴影／光照辅助对象与 threejs-lights 调优工作流配合使用。
4. 启用大量辅助对象时，提及其性能开销。
5. 导入路径遵循 threejs-dev-setup 的附加组件约定。

参考资料

• 手册（调试工作流背景）：https://threejs.org/manual/
• 文档索引（Helpers 分组）：https://threejs.org/docs/#Helpers
• 示例：https://threejs.org/docs/DirectionalLightHelper.html

关键词

**英语：**辅助对象、调试、坐标轴、网格、骨架、法线、光照辅助对象、three.js

中文： 辅助、调试、坐标轴、网格、骨架、法线、Helper、three.js