Screen Handles
Orbit and Map Handles as replacements for Orbit and Map controls
Screen handles are available for screen-based devices like smartphones and PCs and allow users to move the camera by dragging, swiping, and scrolling on the screen. Three.js directly offers OrbitControls
and MapControls
, which are built for this purpose, and we are building on top of their success. The main difference is that the OrbitHandles
and MapHandles
we provide use the event system of the scene, which means that interactions with objects in the scene prevent dragging the camera. Furthermore, the event system can forward the screen inputs on a virtual screen to a virtual camera inside a virtual scene, which is showcased in the editor example.
Using the OrbitHandles
and MapHandles
in React Three Fiber requires disabling the built-in event system and adding the event system of @react-three/xr
.
import { OrbitHandles } from '@react-three/handles'
import { noEvents, PointerEvents } from '@react-three/xr'
<Canvas events={noEvents}>
<PointerEvents />
<OrbitHandles />
</Canvas>
Orbit Handles
alias for OrbitControls
Orbit handles allow the user to orbit around a center, which can be moved by panning with a right click or two fingers touching the screen.
Properties
store
The screen camera store contains the current state of the camera, including the position of the origin, the yaw and pitch of the camera, and the distance of the camera to the origin. By passing an external store to the Orbit Handles, you can take control of the current state of the camera from multiple sources.
apply
The apply function applies the modifications to the screen camera state that occurred based on user interactions to the screen camera store. Overriding this function allows you to manually modify the screen camera store and prevent or restrict certain modifications, such as the maximum pitch angle.
enabled
Allows you to disable the orbit handles momentarily by setting enabled to false
.
damping
Allows you to configure how much the camera movement should be smoothed. Set to true
for the default damping and false
to disable damping.
camera
Allows you to configure the camera on which the transformation should be applied. Not setting the camera will apply the transformations to the default camera of the scene.
rotate
Allows you to configure the rotation speed and a filter function to disable rotation on certain input devices. Setting rotate to false
will disable rotation entirely.
zoom
Allows you to configure the zoom speed and a filter function to disable zooming on certain input devices. Setting zoom to false
will disable zooming entirely.
pan
Allows you to configure the pan speed and a filter function to disable panning on certain input devices. Setting pan to false
will disable panning entirely.
Map Handles
alias for MapControls
Map handles have the same properties and functionality as the orbit handles but move the camera's transform origin only in the X and Y planes, which is perfect for building applications with a flat map.