Camera

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 High Fidelity 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.

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