Camera

• Properties • Methods • Signals • Type Definitions • Method Details • Signal Details •

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes. The Vircadia camera has axes x = right, y = up, -z = forward.

Properties

Name Type Summary
position Vec3

The position of the camera. You can set this value only when the camera is in independent mode.
orientation Quat

The orientation of the camera. You can set this value only when the camera is in independent mode.
mode Camera.Mode

The camera mode.
frustum ViewFrustum

The camera frustum.
cameraEntity Uuid

The ID of the entity that is used for the camera position and orientation when the camera is in entity mode.
captureMouse boolean

The mouse capture state. When true, the mouse is invisible and cannot leave the bounds of Interface, as long as Interface is the active window and no menu item is selected. When false, the mouse behaves normally.
sensitivity number

The current camera sensitivity. Must be positive.

Methods

Name Return Value Summary
computePickRay PickRay

Computes a PickRay based on the current camera configuration and the specified x, y position on the screen. The PickRay can be used in functions such as Entities.findRayIntersection and Overlays.findRayIntersection.
getCameraEntity Uuid

Gets the ID of the entity that the camera is set to follow (i.e., use the position and orientation from) when it's in entity mode. You can also get the entity ID using the Camera.cameraEntity property.
getCaptureMouse boolean

Gets the current mouse capture state.
getModeString Camera.Mode

Gets the current camera mode. You can also get the mode using the Camera.mode property.
getOrientation Quat

Gets the current camera orientation. You can also get the orientation using the Camera.orientation property.
getPosition Vec3

Gets the current camera position. You can also get the position using the Camera.position property.
getSensitivity number

Gets the current camera sensitivity.
keepLookingAt None

Sets the camera to continue looking at the specified position even while the camera moves. Only works if the camera is in independent mode.
lookAt None

Rotates the camera to look at the specified position. Only works if the camera is in independent mode.
setCameraEntity None

Sets the entity that the camera should follow (i.e., use the position and orientation from) when it's in entity mode. You can also set the entity using the Camera.cameraEntity property.
setCaptureMouse None

Sets the mouse capture state. When true, the mouse is invisible and cannot leave the bounds of Interface, as long as Interface is the active window and no menu item is selected. When false, the mouse behaves normally.
setModeString None

Sets the camera mode. You can also set the mode using the Camera.mode property.
setOrientation None

Sets the camera orientation. You can also set the orientation using the Camera.orientation property. Only works if the camera is in independent mode.
setPosition None

Sets the camera position. You can also set the position using the Camera.position property. Only works if the camera is in independent mode.
setSensitivity None

Sets the camera sensitivity. Higher values mean that the camera will be more sensitive to mouse movements.
stopLookingAt None

Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.

Signals

Name Summary
captureMouseChanged

Triggered when the camera mouse capture state changes.
modeUpdated

Triggered when the camera mode changes.

Type Definitions

Mode
Type: string

Camera modes affect the position of the camera and the controls for camera movement. The camera can be in one of the following modes:

Mode String Description
First Person "first person"

The camera is positioned such that you have the same view as your avatar. The camera moves and rotates with your avatar.

Legacy first person camera mode.
First Person Look At "first person look at"

The camera is positioned such that you have the same view as your avatar. The camera moves and rotates with your avatar's head.

Default first person camera mode.
Third Person "third person"

The camera is positioned such that you have a view from just behind your avatar. The camera moves and rotates with your avatar.

Legacy third person camera camera mode.

Camera.mode = "third person";
Look At "look at"

The camera is positioned behind your avatar. The camera moves and rotates independently from your avatar. The avatar's head always faces the camera look at point.

Default third person camera mode.
Selfie "selfie"

The camera is positioned in front of your avatar. The camera moves and rotates independently from your avatar. Your avatar's head is always facing the camera.

Default "look at myself" camera mode.
Mirror "mirror"

The camera is positioned such that you are looking directly at your avatar. The camera is fixed and does not move with your avatar.

Legacy "look at myself" behavior.

Camera.mode = "mirror";
Independent "independent" The camera's position and orientation don't change with your avatar movement. Instead, they can be set via scripting.
Entity "entity" The camera's position and orientation are set to be the same as a specified entity's, and move with the entity as it moves.

Method Details

(static) computePickRay( x, y ) → {PickRay}
Returns: The computed PickRay.

Computes a PickRay based on the current camera configuration and the specified x, y position on the screen. The PickRay can be used in functions such as Entities.findRayIntersection and Overlays.findRayIntersection.

Parameters

Name Type Description
x number

X-coordinate on screen.
y number

Y-coordinate on screen.
Example

Use a PickRay to detect mouse clicks on entities.

function onMousePressEvent(event) {
    var pickRay = Camera.computePickRay(event.x, event.y);
    var intersection = Entities.findRayIntersection(pickRay);
    if (intersection.intersects) {
        print("You clicked on entity " + intersection.entityID);
    }
}

Controller.mousePressEvent.connect(onMousePressEvent);
(static) getCameraEntity( ) → {Uuid}
Returns: The ID of the entity that the camera is set to follow when in entity mode; null if no camera entity has been set.

Gets the ID of the entity that the camera is set to follow (i.e., use the position and orientation from) when it's in entity mode. You can also get the entity ID using the Camera.cameraEntity property.
(static) getCaptureMouse( ) → {boolean}
Returns: true if the mouse is captured (is invisible and cannot leave the bounds of Interface, if Interface is the active window and no menu item is selected), false if the mouse is behaving normally.

Gets the current mouse capture state.
(static) getModeString( ) → {Camera.Mode}
Returns: The current camera mode.

Gets the current camera mode. You can also get the mode using the Camera.mode property.
(static) getOrientation( ) → {Quat}
Returns: The current camera orientation.

Gets the current camera orientation. You can also get the orientation using the Camera.orientation property.
(static) getPosition( ) → {Vec3}
Returns: The current camera position.

Gets the current camera position. You can also get the position using the Camera.position property.
(static) getSensitivity( ) → {number}
Returns: The current camera sensitivity. Must be positive.

Gets the current camera sensitivity.
(static) keepLookingAt( position )

Sets the camera to continue looking at the specified position even while the camera moves. Only works if the camera is in independent mode.

Parameters

Name Type Description
position Vec3

The position to keep looking at.
(static) lookAt( position )

Rotates the camera to look at the specified position. Only works if the camera is in independent mode.

Parameters

Name Type Description
position Vec3

The position to look at.
Example

Rotate your camera to look at entities as you click on them with your mouse.

function onMousePressEvent(event) {
    var pickRay = Camera.computePickRay(event.x, event.y);
    var intersection = Entities.findRayIntersection(pickRay);
    if (intersection.intersects) {
        // Switch to independent mode.
        Camera.mode = "independent";
        // Look at the entity that was clicked.
        var properties = Entities.getEntityProperties(intersection.entityID, "position");
        Camera.lookAt(properties.position);
    }
}

Controller.mousePressEvent.connect(onMousePressEvent);
(static) setCameraEntity( entityID )

Sets the entity that the camera should follow (i.e., use the position and orientation from) when it's in entity mode. You can also set the entity using the Camera.cameraEntity property.

Parameters

Name Type Description
entityID Uuid

The entity that the camera should follow when it's in entity mode.
Example

Move your camera to the position and orientation of the closest entity.

Camera.setModeString("entity");
var entity = Entities.findClosestEntity(MyAvatar.position, 100.0);
Camera.setCameraEntity(entity);
(static) setCaptureMouse( captureMouse )

Sets the mouse capture state. When true, the mouse is invisible and cannot leave the bounds of Interface, as long as Interface is the active window and no menu item is selected. When false, the mouse behaves normally.

Parameters

Name Type Description
captureMouse boolean

true to capture the mouse, false to release the mouse.
(static) setModeString( mode )

Sets the camera mode. You can also set the mode using the Camera.mode property.

Parameters

Name Type Description
mode Camera.Mode

The mode to set the camera to.
(static) setOrientation( orientation )

Sets the camera orientation. You can also set the orientation using the Camera.orientation property. Only works if the camera is in independent mode.

Parameters

Name Type Description
orientation Quat

The orientation to set the camera to.
(static) setPosition( position )

Sets the camera position. You can also set the position using the Camera.position property. Only works if the camera is in independent mode.

Parameters

Name Type Description
position Vec3

The position to set the camera at.
(static) setSensitivity( sensitivity )

Sets the camera sensitivity. Higher values mean that the camera will be more sensitive to mouse movements.

Parameters

Name Type Description
sensitivity number

The desired camera sensitivity. Must be positive.
(static) stopLookingAt( )

Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.

Signal Details

captureMouseChanged( newCaptureMouse )
Returns: Signal

Triggered when the camera mouse capture state changes.

Parameters

Name Type Description
newCaptureMouse boolean

The new mouse capture state.
Example

Report mouse capture state changes.

function onCaptureMouseChanged(newCaptureMouse) {
    print("The mouse capture has changed to " + newCaptureMouse);
}

Camera.captureMouseChanged.connect(onCaptureMouseChanged);
modeUpdated( newMode )
Returns: Signal

Triggered when the camera mode changes.

Parameters

Name Type Description
newMode Camera.Mode

The new camera mode.
Example

Report camera mode changes.

function onCameraModeUpdated(newMode) {
    print("The camera mode has changed to " + newMode);
}

Camera.modeUpdated.connect(onCameraModeUpdated);