CameraControls

Lets the user orbit, pan and zoom with the mouse or touch.

A user-controlled orbit camera, built on camera-controls. It still takes part in priority and blending like any other camera. Unlike other Bodies, it controls both position and rotation, so don't add an Aim next to it.

camera-controls is a three.js library, so this Body exists only in integrations built on three.js.

pnpm add camera-controls

With a target, the camera orbits around it and follows it when it moves. Without one, it's free: orbit, pan and zoom anywhere.

Note

Use initialPosition to set the starting point. The camera's initialState has no effect on CameraControls.

Settings

Setting	Description	Default
`target`	What to orbit around. See Targets. Omit for free controls.
`initialPosition`	Where the camera starts.
`enableTransition`	Animate the internal `camera-controls` calls.	`false`
`impl`	A custom `CameraControls` subclass to use instead.
`waitForBlend`	Ignore input until the blend into this camera has finished. An option of `klipp.whileOnScreen` in three.js.	`true`
`makeDefault`	React only. Set as r3f's `state.controls` while it accepts input.	`false`
`regress`	React only. Lower render quality while moving (`performance.regress()`).	`false`

controls is the camera-controls instance, for its own options like minDistance or dollySpeed, and methods like rotateTo or setLookAt.

Usage

import { CameraControlsBodyThree } from '@pmndrs/klipp/three/camera-controls';
import { VirtualCameraThree } from '@pmndrs/klipp/three';

const body = new CameraControlsBodyThree(ball);
body.controls.minDistance = 2;
const orbit = new VirtualCameraThree('orbit', { priority: 10 });
klipp.add(orbit);
orbit.body = body;

klipp.whileOnScreen(orbit, () => {
  body.controls.connect(renderer.domElement);
  return () => body.controls.disconnect();
});

whileOnScreen connects the controls only while their camera is on screen, so several orbit cameras don't fight over the mouse.

import { CameraControls } from '@pmndrs/klipp/react/camera-controls';

<VirtualCamera name="orbit" priority={10}>
  <CameraControls target={ballRef} minDistance={2} />
</VirtualCamera>

Any option of a camera-controls instance can be passed as a prop, and its events too: onControlStart, onControl, onControlEnd, onTransitionStart, onUpdate, onWake, onRest and onSleep.

Input only works while this camera is on screen, so you can mount several orbit cameras without them fighting over the mouse.

ref gives you the CameraControlsBodyThree.

Edit this page