threejs-helpers について
threejs-helpersは、three.jsの可視化ヘルパーに関する回答を支援するエージェント向けスキルです。デバッグ用ヘルパーの選択、設定、更新、削除に加え、性能や本番環境での注意点を扱います。
主な機能
- 01コアとアドオンのヘルパー案内
- 02ヘルパーの設定と更新方法
- 03デバッグ用途と本番利用の注意
- 04性能と変換に関する落とし穴
活用シーン
- 01カメラ、ライト、軸の可視化
- 02スケルトン、境界、メッシュ法線の確認
- 03リリース前のデバッグヘルパー整理
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/threejs-helpersを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamlexamples/workflow-light-camera-helpers.md
詳細
このスキルを使用するタイミング
ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください：
- 軸、グリッド、カメラの視錐台、シャドウカメラ、光の向きを可視化する
- メッシュの検査用に、スケルトンのボーン、バウンディングボックス、法線／接線を表示する
- ヘルパークラスを使ってライトプローブや矩形エリアライトを可視化する
重要：ヘルパーと本番用メッシュ
- ヘルパーはデバッグ用オブジェクトです。最終的なシーンジオメトリとして使用しないでください。
トリガーとなるフレーズの例：
- 「AxesHelper」、「GridHelper」、「CameraHelper」、「SkeletonHelper」、「VertexNormalsHelper」
- 「辅助线」、「法线显示」、「包围盒调试」
このスキルの使用方法
- 追加：ヘルパーを、説明する対象のオブジェクトに追加します（例：
CameraHelper(light.shadow.camera)）。 - 更新：対象が移動したら更新します。フレームごとの再描画が必要なヘルパーもあります。
- 削除：本番ビルドでは削除するか、デバッグフラグで有効化を制御します。
- パフォーマンス：ヘルパーはドローコールを増やします。パフォーマンスの問題を調査する際は無効にしてください。
- アドオン：threejs-dev-setupに従い、
three/addons/helpers/...のパスからインポートします。
examples/workflow-light-camera-helpers.mdを参照してください。
ドキュメントマップ（公式）
対象範囲
- 対象範囲内： 可視化用のCoreおよびAddonsのヘルパー。
- 対象範囲外： 本番用メッシュや出荷用アート（threejs-geometries、threejs-lights）；オービット／トランスフォームギズモの動作（threejs-controls）；DCCツールと同等のエディターUX；ヘルパーのスタブを超える物理演算のデバッグ。
よくある落とし穴とベストプラクティス
- ヘルパーが多すぎると視界が遮られるため、サブシステムごとに切り替えてください。
- 親オブジェクトを誤ると、ヘルパーの変換がずれます。
- ヘルパーはシーングラフの変換を継承します。まとめて表示／非表示を切り替えるには、デバッグ用グループの子にしてください。
- ヘルパーによってはジオメトリのコストが重複します。本番環境では除去するか、
#ifdef DEBUG形式のフラグを使ってください。 - シャドウカメラ用の
CameraHelperでは、メインビューカメラではなく、light.shadow.cameraを参照してください。
ドキュメントとバージョン
ヘルパーはHelpers（Core）と、three.js docsのAddons → Helpersに掲載されています。ヘルパーはデバッグ専用です。本番用のメッシュとライティングには、実際のジオメトリ／ライトを使用してください（threejs-geometries、threejs-lights）。
エージェントの回答チェックリスト
このスキルに基づいて回答する場合は、次の内容を優先してください。
- 使用するヘルパークラス（
AxesHelper、CameraHelperなど）へのリンクを記載する。 - ヘルパーは出荷用アートではないことを明記し、本番環境では除去するか、デバッグフラグで有効化を制御するよう案内する。
- シャドウ／ライトのヘルパーをthreejs-lightsの調整ワークフローと組み合わせる。
- 多数のヘルパーを有効にした場合のパフォーマンスコストに触れる。
- インポートパスはthreejs-dev-setupのアドオン規約に従う。
参考資料
- マニュアル（デバッグワークフローの概要）：https://threejs.org/manual/
- ドキュメントのインデックス（Helpersグループ）：https://threejs.org/docs/#Helpers
- 例：https://threejs.org/docs/DirectionalLightHelper.html
キーワード
英語： helper、debug、axes、grid、skeleton、normals、light helper、three.js
中国語： 辅助、调试、坐标轴、网格、骨架、法线、Helper、three.js
コメント
Markdown 対応