threejs-syntax-controls

クイックリファレンス

コントロール選択の判断フロー

ユースケース	コントロール	理由
3Dモデルをあらゆる角度から検査する	OrbitControls	ターゲットポイント周辺の軌道回転/パン/ズーム
トップダウンマップまたは2Dスタイルナビゲーション	MapControls	左ドラッグでパン、右ドラッグで回転
フリーフライトエディタまたは宇宙シーン	FlyControls	6自由度、WASD+マウス
ポインターロック付きのファーストパーソンゲーム	PointerLockControls	カーソルを隠す、マウス移動をキャプチャ
ポインターロックなしのファーストパーソン	FirstPersonControls	ブラウザロックAPIなしのマウスルック
ギズモを介してオブジェクトを移動/回転/スケール	TransformControls	インタラクティブな変換/回転/スケールハンドル
オブジェクトを平面に沿ってドラッグ	DragControls	クリックアンドドラッグでオブジェクトを再配置
ジンバルロック制限なしの回転	ArcballControls	アニメーション状態を持つ完全な球面回転
より単純なジンバルロック制限なし回転	TrackballControls	OrbitControlsのようだがポール制約がない

インポートパス (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 時間を渡してください。引数を渡さないか経過時間を渡すと、速度がフレームレートに依存します。

---

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

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

構築 --> 設定 --> ループにアタッチ --> クリーンアップ時に破棄

ステップ1: 構築

const controls = new OrbitControls(camera, renderer.domElement);

必ず renderer.domElement を2番目の引数として渡してください。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(); // enableDamping または autoRotate が true のとき必須
  renderer.render(scene, camera);
}
animate();

ステップ4: クリーンアップ時に破棄

controls.dispose();

---

OrbitControls

最も一般的に使用されるコントロール。ターゲットポイント周辺で軌道回転、パン、ズームを行います。

コンストラクタ

new OrbitControls(camera: THREE.Camera, domElement: HTMLElement)

主要なプロパティ

プロパティ	型	デフォルト	説明
enabled	boolean	true	すべてのインタラクションを有効/無効
target	Vector3	(0,0,0)	軌道回転フォーカスポイント
enableDamping	boolean	false	スムーズな慣性移動
dampingFactor	number	0.05	慣性強度(0-1)
autoRotate	boolean	false	ターゲットの周囲を自動回転
autoRotateSpeed	number	2.0	度数/秒(60fpsで)
enablePan	boolean	true	パンを許可
enableRotate	boolean	true	回転を許可
enableZoom	boolean	true	ズームを許可
minDistance	number	0	最小ズーム距離(PerspectiveCamera)
maxDistance	number	Infinity	最大ズーム距離(PerspectiveCamera)
minZoom	number	0	最小ズーム(OrthographicCamera)
maxZoom	number	Infinity	最大ズーム(OrthographicCamera)
minPolarAngle	number	0	最小垂直角(ラジアン)
maxPolarAngle	number	Math.PI	最大垂直角(ラジアン)
minAzimuthAngle	number	-Infinity	最小水平角(ラジアン)
maxAzimuthAngle	number	Infinity	最大水平角(ラジアン)
screenSpacePanning	boolean	true	スクリーン平面でパン(true)または水平面でパン(false)
zoomToCursor	boolean	false	カーソル位置に向かってズーム
panSpeed	number	1.0	パン速度乗数
rotateSpeed	number	1.0	回転速度乗数
zoomSpeed	number	1.0	ズーム速度乗数
mouseButtons	object	{LEFT: ROTATE, MIDDLE: DOLLY, RIGHT: PAN}	マウスボタンマッピング
touches	object	{ONE: ROTATE, TWO: DOLLY_PAN}	タッチジェスチャーマッピング
keys	object	{LEFT, UP, RIGHT, BOTTOM}	パン用矢印キーコード

メソッド

メソッド	シグネチャ	説明
update(deltaTime?)	(number?) => boolean	コントロール状態を更新。ダンピング/autoRotate時は毎フレーム呼び出し必須
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 のサブクラス。

ボタン	OrbitControls	MapControls
左マウス	回転	パン
中央マウス	ドーリー	ドーリー
右マウス	パン	回転

すべてのプロパティ、メソッド、イベントは OrbitControls と同じです。唯一の違いはデフォルト mouseButtons マッピングと screenSpacePanning がデフォルトで true になることです。

---

FlyControls

6自由度フライトカメラ。移動はWASD、ロールはQE、上下はRFです。

主要なプロパティ

プロパティ	型	デフォルト	説明
movementSpeed	number	1.0	移動速度
rollSpeed	number	0.005	ロール回転速度
dragToLook	boolean	false	回転するにはマウスドラッグが必須(常にマウス追従 vs.)
autoForward	boolean	false	自動的に前方に移動

メソッド

• update(delta) -- 必ず クロックから delta 時間を渡してください。この引数を省略したり経過時間を渡したりしないでください。
• dispose() -- イベントリスナーを削除します。

---

PointerLockControls

Pointer Lock APIを使用するファーストパーソンカメラ。マウスカーソルを隠してキャプチャします。

主要なプロパティ

プロパティ	型	デフォルト	説明
isLocked	boolean	読み取り専用	ポインターが現在ロックされているかどうか
maxPolarAngle	number	Math.PI	最大垂直ルック角
minPolarAngle	number	0	最小垂直ルック角
pointerSpeed	number	1.0	マウス感度乗数

メソッド

メソッド	説明
lock()	ポインターロックをリクエスト(ユーザージェスチャーから呼び出し必須)
unlock()	ポインターロックを終了
connect()	イベントリスナーをアタッチ
disconnect()	イベントリスナーを削除
dispose()	完全クリーンアップ(disconnect を呼び出す)
getObject()	制御されたカメラを返す
getDirection(target)	ルック方向をターゲット Vector3 に書き込む
moveForward(distance)	カメラを前方に移動
moveRight(distance)	カメラを横方向に移動

イベント

イベント	トリガー
change	カメラ方向が変更された
lock	ポインターロック取得
unlock	ポインターロック解放

必ず アニメーションループで独自の WASD 移動を実装してください。PointerLockControls はルック方向のみを処理し、位置は処理しません。

---

TransformControls

シーンオブジェクトの移動、回転、スケーリング用のインタラクティブギズモ。

主要なプロパティ

プロパティ	型	デフォルト	説明
mode	string	'translate'	'translate'、'rotate'、または 'scale'
space	string	'world'	'world' または 'local' 座標空間
showX	boolean	true	X軸ハンドルを表示
showY	boolean	true	Y軸ハンドルを表示
showZ	boolean	true	Z軸ハンドルを表示
size	number	1	ギズモの視覚的スケール
translationSnap	`number	null`	null
rotationSnap	`number	null`	null
scaleSnap	`number	null`	null
dragging	boolean	読み取り専用	ユーザーが現在ドラッグ中

メソッド

メソッド	説明
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。

---

リファレンスリンク

• references/methods.md -- すべてのコントロールの完全なAPI署名
• references/examples.md -- 各コントロールタイプの実装例
• references/anti-patterns.md -- すべきではないこと

公式ソース

• https://threejs.org/docs/#examples/en/controls/OrbitControls
• https://threejs.org/docs/#examples/en/controls/MapControls
• https://threejs.org/docs/#examples/en/controls/FlyControls
• https://threejs.org/docs/#examples/en/controls/PointerLockControls
• https://threejs.org/docs/#examples/en/controls/TransformControls