threejs-helpers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此 skill

ALWAYS use this skill when the user mentions:

Visualizing axes, grids, camera frusta, shadow cameras, light directions
Showing skeleton bones, bounding boxes, normals/tangents for mesh inspection
Light probe or rect area visualization via helper classes

IMPORTANT: helpers vs production meshes

Helpers are debug objects; do not use as final scene geometry.

Trigger phrases include:

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

当用户提到以下内容时，始终使用此 skill：

可视化坐标轴、网格、相机视锥、shadow camera 或光照方向
显示骨架骨骼、包围盒，以及用于 mesh 检查的法线和切线
通过 helper 类可视化 light probe 或 rect area

重要：helpers 与生产用网格

Helpers 是 debug 对象；不要将其作为最终场景几何体。

触发短语包括：

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

How to use this skill

如何使用此 skill

Attach helper to the object it describes (e.g.,
```
CameraHelper(light.shadow.camera)
```
).
Update when targets move—some helpers need per-frame refresh.
Remove in production builds or behind debug flags.
Performance: helpers add draw calls—disable when profiling performance issues.
Addons: import from
```
three/addons/helpers/...
```
paths per threejs-dev-setup.

See examples/workflow-light-camera-helpers.md.

将 helper 附加到其所描述的对象（例如
```
CameraHelper(light.shadow.camera)
```
）。
当目标移动时进行更新——某些 helpers 需要逐帧刷新。
在生产构建中移除，或将其置于 debug flags 之后。
性能：helpers 会增加 draw calls——发现性能问题时禁用它们。
Addons：按照 threejs-dev-setup 的规范，从
```
three/addons/helpers/...
```
路径导入。

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

Doc map (official)

文档映射（官方）

Docs section	Representative links
Helpers	https://threejs.org/docs/AxesHelper.html
Helpers	https://threejs.org/docs/GridHelper.html
Helpers	https://threejs.org/docs/CameraHelper.html
Helpers	https://threejs.org/docs/SkeletonHelper.html

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

Scope

适用范围

In scope: Core + Addons helpers for visualization.
Out of scope: Production meshes or shipping art (threejs-geometries, threejs-lights); orbit/transform gizmo behavior (threejs-controls); editor UX parity with DCC tools; physics debug beyond helper stubs.

范围内： 用于可视化的 Core + Addons helpers。
范围外： 生产用网格或最终发布的美术内容（threejs-geometries、threejs-lights）；orbit/transform gizmo 行为（threejs-controls）；与 DCC 工具一致的编辑器 UX；超出 helper stubs 范围的物理调试。

Common pitfalls and best practices

常见问题与最佳实践

Too many helpers obscures view—toggle per subsystem.
Wrong attachment parent misaligns helper transforms.
Helpers inherit scene graph transforms—parent under a debug group to batch hide/show.
Some helpers duplicate geometry cost; strip in production or use
```
#ifdef DEBUG
```
style flags.
```
CameraHelper
```
for shadow cameras must reference
```
light.shadow.camera
```
, not the main view camera.

过多的 helpers 会遮挡视图——按子系统切换显示。
挂载到错误的父级会导致 helper 变换错位。
Helpers 会继承场景图变换——将其挂载到 debug group 下，以便批量隐藏或显示。
某些 helpers 会重复产生几何体开销；在生产环境中将其移除，或使用
```
#ifdef DEBUG
```
风格的 flags。
用于 shadow camera 的
```
CameraHelper
```
必须引用
```
light.shadow.camera
```
，而不是主视图相机。

Documentation and version

文档与版本

Helpers are listed under Helpers (core) and Addons → Helpers in three.js docs. They are for debug only; production meshes and lighting should use real geometry/lights (threejs-geometries, threejs-lights).

Helpers 列于 Helpers（core）以及 three.js 文档中的 Addons → Helpers。它们仅用于 debug；生产用网格和光照应使用真实的 geometry/lights（threejs-geometries、threejs-lights）。

Agent response checklist

Agent 回答检查清单

When answering under this skill, prefer responses that:

Link the helper class (
```
AxesHelper
```
,
```
CameraHelper
```
, …) being used.
State that helpers are not shipping art—strip or gate behind debug flags.
Pair shadow/light helpers with threejs-lights tuning workflows.
Mention performance cost when many helpers are enabled.
Import paths follow threejs-dev-setup addon conventions.

在此 skill 下回答时，优先采用以下方式：

链接所使用的 helper 类（
```
AxesHelper
```
、
```
CameraHelper
```
等）。
说明 helpers 不是用于最终发布的美术内容——应将其移除或置于 debug flags 之后。
将 shadow/light helpers 与 threejs-lights 调优工作流配合使用。
启用大量 helpers 时，提及其性能开销。
确保导入路径遵循 threejs-dev-setup 的 addon 规范。

References

参考资料

Manual (debug workflow context): https://threejs.org/manual/
Docs index (Helpers group): https://threejs.org/docs/#Helpers
Examples: https://threejs.org/docs/DirectionalLightHelper.html

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

Keywords

关键词

English: helper, debug, axes, grid, skeleton, normals, light helper, three.js

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

英文： helper, debug, axes, grid, skeleton, normals, light helper, three.js

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