Camera

Description

The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes.

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

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.

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.
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.
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.
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.
stopLookingAt None Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.

Signals

Name Summary
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.
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.
Mirror "mirror" The camera is positioned such that you are looking directly at your avatar. The camera moves and rotates with your avatar.
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) 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) 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) 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) stopLookingAt( )

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

Signal Details

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);