mcpField
T
threejs-syntax-controls

threejs-syntax-controls

github.com/impertio-studio開発23134 回インストール30 週間前に更新
リポジトリ

threejs-syntax-controls について

Three.js 開発者向けに、カメラとオブジェクトの操作方法をまとめたリファレンススキルです。各種コントロールの選択、初期化、更新、破棄、連携時の注意点を解説します。

主な機能

  1. 01操作方法に応じたコントロール選択
  2. 02オービット・マップ・フライト操作
  3. 03一人称視点とポインターロック操作
  4. 04オブジェクト変換とドラッグ用ギズモ
  5. 05ライフサイクルと連携のガイダンス

活用シーン

  1. 01モデルビューアーへの回転・ズーム追加
  2. 02一人称カメラ操作の構築
  3. 03ギズモによるオブジェクト変換の編集

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/impertio-studio/three.js-claude-skill-package --skill threejs-syntax-controls

インストール後、Claude Code で/threejs-syntax-controlsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.gitkeep
references/
anti-patterns.md
examples.md
methods.md

詳細

threejs-syntax-controls

クイックリファレンス

コントロール選択の決定木
ユースケースコントロール理由
3Dモデルをあらゆる角度から確認するOrbitControls対象点を中心に回転／パン／ズームできます
上面図の地図や2D風のナビゲーションMapControls左ドラッグでパン、右ドラッグで回転します
自由飛行するエディターや宇宙空間のシーンFlyControls6自由度で、WASDキーとマウスを使用します
ポインターロックを使う一人称視点のゲームPointerLockControlsカーソルを非表示にし、マウスの動きを捕捉します
ポインターロックを使わない一人称視点FirstPersonControlsブラウザーのロックAPIを使わずにマウスで視点を操作します
ギズモを使ってオブジェクトを移動／回転／拡縮するTransformControls移動／回転／拡縮用のハンドルを操作できます
平面に沿ってオブジェクトをドラッグするDragControlsオブジェクトをクリックしてドラッグし、位置を変更できます
拘束のない回転（ジンバルロックなし）ArcballControlsアニメーション付きの全方向回転ができます
拘束のない回転（よりシンプル）TrackballControlsOrbitControlsに似ていますが、極方向の制約がありません
インポートパス（Three.js r160以降）
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { MapControls } from 'three/addons/controls/MapControls.js';
import { FlyControls } from 'three/addons/controls/FlyControls.js';
import { FirstPersonControls } from 'three/addons/controls/FirstPersonControls.js';
import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
import { TransformControls } from 'three/addons/controls/TransformControls.js';
import { TrackballControls } from 'three/addons/controls/TrackballControls.js';
import { ArcballControls } from 'three/addons/controls/ArcballControls.js';
import { DragControls } from 'three/addons/controls/DragControls.js';

r160以降では、必ず 'three/addons/controls/...' を使用してください。旧パスの 'three/examples/jsm/controls/...' も引き続き動作しますが、非推奨です。

重要な警告

enableDamping または autoRotate が true の場合は、アニメーションループ内で必ず controls.update() を呼び出してください。呼び出さないと、ユーザーの操作終了後にカメラが停止します。

コントロールを削除する際は、必ず controls.dispose() を呼び出してください。呼び出さないと、DOMイベントリスナー（pointermove、wheel、keydown）がリークし、メモリリークやゴースト操作が発生します。

無効化せずに、同じカメラに2つのカメラコントロールクラスを絶対に同時にアタッチしないでください。同じカメラにOrbitControlsとFlyControlsをアタッチすると、動きが不規則になります。

TransformControlsがドラッグ中の間は、必ずOrbitControlsを無効にしてください。dragging-changedイベントを監視し、orbitControls.enabled を切り替えます。

PointerLockControls.lock() はユーザーのジェスチャー（クリックハンドラー）から必ず呼び出してください。ユーザー操作がない場合、ブラウザーはポインターロックの要求を拒否します。

FlyControls.update(delta) には、必ず delta 時間を渡してください。引数を渡さない場合や経過時間を渡す場合、速度がフレームレートに依存します。

コントロールのライフサイクル

すべてのコントロールは、同じライフサイクルパターンに従います。

construct --> configure --> attach to loop --> dispose on cleanup
ステップ1：生成
const controls = new OrbitControls(camera, renderer.domElement);

2番目の引数には、必ず renderer.domElement を渡してください。document や document.body を渡すと、コントロールがイベントをグローバルに捕捉し、UIオーバーレイが正常に動作しなくなります。

ステップ2：設定
controls.enableDamping = true;
controls.dampingFactor = 0.05;
controls.minDistance = 2;
controls.maxDistance = 50;
controls.target.set(0, 1, 0);
ステップ3：レンダーループ内で更新
function animate() {
  requestAnimationFrame(animate);
  controls.update(); // REQUIRED when enableDamping or autoRotate is true
  renderer.render(scene, camera);
}
animate();
ステップ4：クリーンアップ時に破棄
controls.dispose();

OrbitControls

最もよく使われるコントロールです。対象点を中心に回転、パン、ズームします。

コンストラクター
new OrbitControls(camera: THREE.Camera, domElement: HTMLElement)
主なプロパティ
プロパティ型デフォルト説明
enabledbooleantrueすべての操作を有効／無効にします
targetVector3(0,0,0)オービットの注視点
enableDampingbooleanfalse慣性のあるスムーズな移動を有効にします
dampingFactornumber0.05慣性の強さ（0～1）
autoRotatebooleanfalse注視点を中心に自動回転します
autoRotateSpeednumber2.060fps 時の角速度（度／秒）
enablePanbooleantrueパン操作を有効にします
enableRotatebooleantrue回転操作を有効にします
enableZoombooleantrueズーム操作を有効にします
minDistancenumber0最小ズーム距離（PerspectiveCamera）
maxDistancenumberInfinity最大ズーム距離（PerspectiveCamera）
minZoomnumber0最小ズーム（OrthographicCamera）
maxZoomnumberInfinity最大ズーム（OrthographicCamera）
minPolarAnglenumber0最小垂直角度（ラジアン）
maxPolarAnglenumberMath.PI最大垂直角度（ラジアン）
minAzimuthAnglenumber-Infinity最小水平角度（ラジアン）
maxAzimuthAnglenumberInfinity最大水平角度（ラジアン）
screenSpacePanningbooleantrue画面平面（true）または水平面（false）でパンします
zoomToCursorbooleanfalseカーソル位置に向かってズームします
panSpeednumber1.0パン速度の倍率
rotateSpeednumber1.0回転速度の倍率
zoomSpeednumber1.0ズーム速度の倍率
mouseButtonsobject{LEFT: ROTATE, MIDDLE: DOLLY, RIGHT: PAN}マウスボタンの割り当て
touchesobject{ONE: ROTATE, TWO: DOLLY_PAN}タッチジェスチャーの割り当て
keysobject{LEFT, UP, RIGHT, BOTTOM}パン操作に使用する矢印キーのコード
メソッド
メソッドシグネチャ説明
update(deltaTime?)(number?) => booleanコントロールの状態を更新します。減衰／自動回転を使用する場合は、毎フレーム呼び出す必要があります
dispose()() => voidすべてのイベントリスナーを削除します
saveState()() => void現在のカメラ位置／注視点／ズームを保存します
reset()() => void最後に保存した状態に戻します
getDistance()() => numberカメラから注視点までの距離
getPolarAngle()() => number垂直角度（ラジアン）
getAzimuthalAngle()() => number水平角度（ラジアン）
listenToKeyEvents(el)(HTMLElement) => voidキーボードによるパン操作を有効にします
stopListenToKeyEvents()() => voidキーボードによるパン操作を無効にします
イベント
イベント発生条件
changeカメラ位置または注視点が変更されたとき
startユーザー操作が始まったとき（pointerdown）
endユーザー操作が終了したとき（pointerup）

MapControls

上から見下ろすマップナビゲーションに最適化された OrbitControls のサブクラスです。

ボタンOrbitControlsMapControls
左マウスボタン回転パン
中マウスボタンドリードリー
右マウスボタンパン回転

プロパティ、メソッド、イベントはすべて OrbitControls と同じです。異なるのはデフォルトの mouseButtons の割り当てと、screenSpacePanning のデフォルト値が true である点だけです。

FlyControls

6自由度のフライトカメラです。移動には WASD、ロールには QE、上下移動には RF を使用します。

主なプロパティ
プロパティ型デフォルト説明
movementSpeednumber1.0平行移動速度
rollSpeednumber0.005ロール回転速度
dragToLookbooleanfalse回転するにはマウスのドラッグが必要です（常にマウスに追従するのではなく）
autoForwardbooleanfalse自動的に前進します
メソッド
  • update(delta) -- クロックから取得した delta 時間を必ず渡してください。この引数を省略しないでください。
  • dispose() -- イベントリスナーを削除します。

PointerLockControls

Pointer Lock API を使用する一人称視点カメラです。マウスカーソルを非表示にして捕捉します。

主なプロパティ
プロパティ型デフォルト説明
isLockedboolean読み取り専用ポインターが現在ロックされているかどうか
maxPolarAnglenumberMath.PI垂直方向の最大視角
minPolarAnglenumber0垂直方向の最小視角
pointerSpeednumber1.0マウス感度の倍率
メソッド
メソッド説明
lock()ポインターロックを要求します（ユーザー操作から呼び出す必要があります）
unlock()ポインターロックを解除します
connect()イベントリスナーを登録します
disconnect()イベントリスナーを削除します
dispose()完全にクリーンアップします（disconnect を呼び出します）
getObject()操作対象のカメラを返します
getDirection(target)視線の方向を target の Vector3 に書き込みます
moveForward(distance)カメラを前方に移動します
moveRight(distance)カメラを横方向に移動します
イベント
イベント発生条件
changeカメラの向きが変化したとき
lockポインターロックを取得したとき
unlockポインターロックを解除したとき

アニメーションループ内では、必ず独自の WASD 移動処理を実装してください。PointerLockControls が処理するのは視線の方向だけであり、位置は処理しません。

TransformControls

シーン内のオブジェクトを移動、回転、拡大縮小するためのインタラクティブなギズモです。

主なプロパティ
プロパティ型デフォルト説明
modestring'translate''translate'、'rotate'、または 'scale'
spacestring'world''world' または 'local' 座標空間
showXbooleantrueX 軸のハンドルを表示します
showYbooleantrueY 軸のハンドルを表示します
showZbooleantrueZ 軸のハンドルを表示します
sizenumber1ギズモの表示スケール
translationSnap`numbernull`null
rotationSnap`numbernull`null
scaleSnap`numbernull`null
draggingboolean読み取り専用ユーザーが現在ドラッグしているかどうか
メソッド
メソッド説明
attach(object)ギズモをシーン内のオブジェクトに取り付けます
detach()現在のオブジェクトからギズモを取り外します
setMode(mode)変換モードを設定します
setSpace(space)座標空間を設定します
setSize(size)ギズモのスケールを設定します
setTranslationSnap(snap)位置のスナップを設定します
setRotationSnap(snap)回転のスナップを設定します
setScaleSnap(snap)スケールのスナップを設定します
getRaycaster()内部のレイキャスターにアクセスします
dispose()クリーンアップします
イベント
イベント発生条件
changeギズモの表示が変化したとき
dragging-changedドラッグ開始時は event.value が true、終了時は false になります
objectChange取り付けたオブジェクトの変換が変更されたとき
mouseDownギズモ上でポインターを押したとき
mouseUpギズモからポインターを離したとき
重要な統合パターン

ギズモのドラッグ中は、必ずカメラコントロールを無効にしてください。

transformControls.addEventListener('dragging-changed', (event) => {
  orbitControls.enabled = !event.value;
});

TransformControls は必ずシーンに追加してください：scene.add(transformControls.getHelper()) または scene.add(transformControls)。

概要：その他のコントロール

ArcballControls

アニメーション状態を備えた、制約のない回転機能です。極角の制限がないため、カメラは全方向に自由に回転します。CAD スタイルのモデル確認に最適です。

TrackballControls

極角の制約がない OrbitControls のようなコントロールです。カメラは極を越えて回転できます。プロパティ：rotateSpeed、zoomSpeed、panSpeed、staticMoving、dynamicDampingFactor。

DragControls

平面に沿ってシーン内のオブジェクトをドラッグします。コンストラクター：new DragControls(objects, camera, domElement)。イベント：dragstart、drag、dragend、hoveron、hoveroff。

FirstPersonControls

ポインターロックを使用しないマウス視点操作のカメラです。プロパティ：movementSpeed、lookSpeed、activeLook、constrainVertical、verticalMin、verticalMax。

参考リンク

公式ソース

コメント

Markdown 対応