Управление камерой: OrbitControls

Писать управление камерой с нуля — мучение. OrbitControls делает это за вас одной строкой.

OrbitControls — это addon, который заставляет камеру вращаться вокруг точки по движению мыши: зажали — крутим, колесо — зум, правая кнопка — сдвиг.

Зачем

Почти в любой демке хочется покрутить объект мышью и рассмотреть его со всех сторон. Реализовать это вручную (ловить события мыши, считать углы, двигать камеру по сфере) — десятки строк и куча краевых случаев. OrbitControls решает задачу из коробки.

Подключение

Это дополнение, поэтому импортируем из three/addons, передаём камеру и DOM-элемент рендерера.

import { OrbitControls } from 'three/addons/controls/OrbitControls.js';

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true; // плавная инерция
controls.target.set(0, 0, 0);  // точка, вокруг которой вращаемся

Обновление в цикле

Если включён enableDamping (плавное затухание движения), контролы нужно обновлять каждый кадр — иначе инерция не доиграет. Добавьте одну строку в цикл рендера.

function animate() {
  requestAnimationFrame(animate);
  controls.update();             // важно при enableDamping
  renderer.render(scene, camera);
}
animate();

Полезные настройки

Свойство	Что делает
`enableDamping`	плавная инерция после движения
`enableZoom`	разрешить зум колесом
`enablePan`	разрешить панорамирование
`minDistance` / `maxDistance`	ограничить приближение/отдаление
`autoRotate`	сцена медленно крутится сама

OrbitControls — лишь один из контролов в addons. Есть ещё FlyControls, PointerLockControls (для шутеров от первого лица) и другие. Но Orbit — самый ходовой для просмотра объектов и сцен.

Важная деталь: target и center

OrbitControls вращает камеру не «вокруг себя», а вокруг точки target — по умолчанию это центр сцены (0,0,0). Если ваш главный объект смещён, поставьте target в его центр, иначе вращение будет ощущаться кривым: объект уезжает за край, пока вы крутите вокруг пустого места. Менять target можно на лету, например при выборе нового объекта.

Ещё один частый вопрос — как сбросить вид к исходному. У контролов есть метод controls.reset(), который возвращает камеру и target к стартовым значениям. Это удобно повесить на кнопку «Сбросить вид» в интерфейсе демо.

И помните: OrbitControls создан для осмотра сцены пользователем. Если вам нужно программно вести камеру по заданной траектории (например, кат-сцена), контролы лучше временно отключить (controls.enabled = false), иначе ваш код и мышь пользователя будут бороться за камеру.

Итог

OrbitControls — готовое вращение/зум/сдвиг камеры мышью.
Импорт из three/addons/controls/OrbitControls.js.
При enableDamping вызывайте controls.update() каждый кадр.