Meta Developers

The Camera API supports the standard first-person game camera that follows the local player avatar. It has no effect in VR, where the first person is always enabled.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeFirstPerson();

It’s also possible to transition to the new camera mode smoothly, by passing camera transition properties to the API. In the following code example, the camera takes half a second to transition from the current camera mode to the first person camera—easing its movement using an ease-in-out function.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.setCameraModeFirstPerson({
  duration: 0.5,
  easing: Easing.EaseInOut,
});

How to set the third person camera mode

The Camera API enables the standard third person game camera that follows the local player avatar. It has no effect in VR, where the first person is always enabled.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeThirdPerson();

Similar to the previous API, it’s also possible to pass camera transition properties to the API to smooth the transition between the previous camera mode and the new one.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.setCameraModeThirdPerson({
  duration: 0.5,
  easing: Easing.EaseInOut,
});

How to set the fixed camera mode

The Camera API enables you to set the camera to a fixed world position and rotation. It has no effect in VR, where the first person is always enabled. By calling this API without any parameter, the camera remains fixed in place from its current position and orientation.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeFixed();

It’s also possible to pass a specific position and rotation, as well as camera transition properties to smooth the transition.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.setCameraModeFixed({
  position: new hz.Vec3(0, 1, -5),
  rotation: hz.Quaternion.fromEuler(new hz.Vec3(0, 0, 0)),
  duration: 0.5,
  easing: Easing.EaseInOut,
});

How to set the attached camera mode

The Camera API allows you to attach the camera to a target entity, automatically following its position and rotation. It has no effect in VR, where the first person is always enabled. When the target entity is destroyed, the camera tracking stops, and it remains where it was before losing the target.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeAttach(targetEntity);

It’s also possible to specify a position offset to follow the target from a distance, and a translation and rotation speed, as well as camera transition properties to smooth the transition.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.setCameraModeAttach(targetEntity, {
  positionOffset: new hz.Vec3(0, 0, -5),
  translationSpeed: 1,
  rotationSpeed: 1,
  duration: 0.5,
  easing: Easing.EaseInOut,
});

How to set the pan camera mode

The Camera API enables you to set the camera to pan adjacent to the avatar at a fixed vector from the avatar. It has no effect in VR, where the first person is always enabled. It is also possible to set a translation speed.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModePan({
  positionOffset: new hz.Vec3(25, 0, 0),
  translationSpeed: 1,
});

How to set the follow camera mode

The follow camera mode is similar to the orbit camera mode, where the camera direction is not tied to the direction the avatar is facing. However, follow camera differs from the orbit camera as it can automatically rotate back behind the avatar as the player moves. This makes it easier for players to orient their avatar and their camera in the world.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeFollow();

It is possible to configure the behavior and position of the follow camera by passing the following options to the API. In this example, the listed values are the default values for these options.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraModeFollow({
  activationDelay: 2.0, // The delay from when the auto-turning is enabled after the camera has been manually turned.
  cameraTurnSpeed: 1.0, // Modifier for the speed at which the camera turns to return behind the player avatar.
  continuousRotation: false, // Enable the camera to continually rotate to behind the player once rotation has started and not be interrupted or disabled to only allow the rotation while the player moves.
  distance: 5.0, // The distance from the target to the camera. If not set, the camera remains at its current distance.
  horizonLevelling: false, // Enables levelling the camera to the horizon.
  rotationSpeed: 0.0, // Controls how quickly the camera moves with the player's avatar. The lower the number, the slower the camera's movement. If not set, the camera is always snapped to the position offset from the target.
  translationSpeed: 0.0, // Controls how quickly the camera moves with the player's avatar. The lower the number, the slower the camera's movement. If not set, the camera is always snapped to the target position.
  verticalOffset: 0.0, // Vertical offset up from the target position. The camera continues to look at the player's avatar.
});

How to set the camera field of view

The Camera API lets you set the camera field of view.

import LocalCamera from 'horizon/camera';

LocalCamera.overrideCameraFOV(72.5);

Similar to the previous APIs, it’s also possible to pass camera transition properties to the API to smooth the transition between the previous camera mode and the new one.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.overrideCameraFOV(72.5, {duration: 0.5, easing: Easing.EaseInOut});

How to adjust the camera roll

The Camera API lets you adjust the tilt of the camera on the Z-axis, also known as the camera roll.

import LocalCamera from 'horizon/camera';

LocalCamera.setCameraRollWithOptions(30);

Similar to previous APIs, it’s also possible to pass camera transition properties to the API to smooth the transition between the previous camera mode and the new one.

import LocalCamera, {CameraTransitionOptions, Easing} from 'horizon/camera';

LocalCamera.setCameraRollWithOptions(30, {
  duration: 0.5,
  easing: Easing.EaseInOut,
});

How to get the Camera look at position

The Camera API lets you get the world position that the player is currently looking at, ignoring the local player’s avatar.

import LocalCamera from 'horizon/camera';

let cameraLookAtPos = LocalCamera.lookAtPosition.get();

How to enable and disable camera collisions

You can use the Local Camera API to enable and disable camera collision. Camera collision gives the camera a physical presence in the world, which means it won’t clip into world geometry, and it won’t see through walls. Instead, the camera is moved closer to the avatar.

Note that small spaces can cause the camera to move very close to the avatar, which can make it difficult for the player to navigate the world. If your world includes a lot of small spaces, then consider:

Disabling camera collision
Switching to first-person camera mode
Enabling perspective switching

import LocalCamera from 'horizon/camera';

LocalCamera.collisionEnabled.set(true);

How to enable and disable perspective switching

The Camera API lets you control whether the player can toggle between first and third person modes using PageUp and PageDown. It does not affect your ability to force first and third person mode via the APIs. This has no effect in VR, where the first person is always enabled.

import LocalCamera from 'horizon/camera';

LocalCamera.perspectiveSwitchingEnabled.set(false);

How to modify the camera’s behavior at runtime

It is possible to change the options which define the camera configuration during gameplay. The available options to configure are:

Camera Mode	Options
Fixed Camera	position rotation
Attach Camera	positionOffset rotationOffset translationSpeed rotationSpeed target
Fixed Camera	position rotation
Pan Camera	positionOffset translationSpeed
Orbit Camera	distance verticalOffset translationSpeed rotationSpeed
Follow Camera	activationDelay cameraTurnSpeed continuousRotation distance horizonLevelling rotationSpeed translationSpeed verticalOffset

In order to configure the camera behavior at runtime, the Camera API enables you to get the camera’s current mode as an object, and then modify the parameters of that object. You must specify which camera mode you are expecting to get in the function call:

LocalCamera.getCameraModeObjectAs(AttachCameraMode)?.rotationSpeed.set(10);

If the camera mode specified is not the same as the current camera mode, then this function will return null.

LocalCamera.setCameraModeFollow();
const cameraMode = LocalCamera.getCameraModeObjectAs(AttachCameraMode); // returns null