threejs-controls について
three.js のコントロールを扱うエージェント向けのリファレンススキルです。公式アドオンの使い方やライフサイクル、操作時の注意点を説明します。
主な機能
- 01Orbit、Map、Fly によるカメラ操作
- 02Transform、Drag、PointerLock コントロール
- 03減衰更新と操作制約
- 04Transform と Orbit の操作調整
- 05終了時のコントロール破棄
活用シーン
- 01減衰付き OrbitControls の設定
- 02カメラ距離と極角の制限
- 03オブジェクト変形時の OrbitControls 停止
- 04PointerLock による一人称移動の実装
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/threejs-controlsを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamlexamples/workflow-orbit-damping.md
詳細
このスキルを使用するタイミング
ユーザーが次の内容に言及した場合は、必ずこのスキルを使用してください。
- 対象の周囲を回転／パン／ドリーする操作、慣性／減衰、距離や極角の最小値／最大値
- マップのようなパン操作（MapControls）や飛行（FlyControls）
TransformControlsを使った変換ギズモによる移動／回転／スケール変更- 平面上でのオブジェクトのドラッグ（DragControls）、ポインターロックによる FPS 操作（PointerLockControls）
重要：controls と webxr の使い分け
| コンテキスト | スキル |
|---|---|
| デスクトップ／ブラウザーでのカメラ操作 | threejs-controls |
| XR コントローラーのポーズ | threejs-webxr |
トリガーとなるフレーズの例：
- 「OrbitControls」、「TransformControls」、「MapControls」、「PointerLockControls」
- 「軌道」、「変換コントローラー」、「ウォークスルー」
このスキルの使用方法
- インポート：アドオンのパス（threejs-dev-setup）からインポートします。
- 構築：
(camera, domElement)を使って構築します。TransformControlsの場合は、レンダラーのイベントにもアタッチします。 - アニメーションループ：
enableDampingが有効な場合は、フレームごとにcontrols.update()を呼び出します。 - TransformControls：
dragging-changedを接続して、操作中は Orbit を一時的に無効にします。選択状態は threejs-objects と同期させます。 - 制約：視点の反転や地下からの表示を防ぐため、距離や角度の最小値／最大値を設定します。
- 破棄：終了処理の際に
controls.dispose()を呼び出します。
examples/workflow-orbit-damping.md を参照してください。
ドキュメントマップ（公式）
| ドキュメントのセクション | 代表的なリンク |
|---|---|
| Controls | https://threejs.org/docs/OrbitControls.html |
| Controls | https://threejs.org/docs/TransformControls.html |
| Controls | https://threejs.org/docs/MapControls.html |
| Controls（インデックス） | https://threejs.org/docs/#Controls |
対象範囲
- 対象範囲内： 公式アドオンの controls の使用パターン。
- 対象範囲外： 完全な物理ベースのキャラクター移動機構、モバイル向けジェスチャーフレームワーク。
よくある落とし穴とベストプラクティス
- 減衰が有効な状態で
update()を呼び忘れると、ドリフトがいつまでも収まりません。 - TransformControls と Orbit が干渉する場合は、使用中の一方を一時停止します。
- ポインターロックには、ユーザー操作による開始と解除の処理が必要です。
ドキュメントとバージョン
Controls は three.js docs の Controls（Addons）にあります。API の詳細（enableDamping、イベント）は変更されるため、ユーザーが使用している three.js のバージョンに対応する OrbitControls／TransformControls のページへリンクしてください。
エージェントの回答チェックリスト
このスキルに基づいて回答する場合は、次の点を優先してください。
- ドキュメント内の該当する controls クラスにリンクします。
- 減衰が有効な場合は、フレームごとに
controls.update()を呼び出すことを明記します。 TransformControlsを、選択状態／threejs-objects のレイキャスティングと連携させます。- デスクトップでのナビゲーションと threejs-webxr の移動を区別します。
- キャンバスのアンマウント時に controls の
dispose()を呼び出します。
参考資料
- https://threejs.org/docs/#Controls
- https://threejs.org/docs/OrbitControls.html
- https://threejs.org/docs/TransformControls.html
キーワード
英語： orbitcontrols、transformcontrols、mapcontrols、減衰、カメラコントロール、three.js
中国語： OrbitControls、軌道、TransformControls、変換コントローラー、減衰、three.js
コメント
Markdown 対応