Camera

Available in: Interface Scripts Client Entity Scripts

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

Signals

Type Definitions

Properties:
Name Type Description
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

computePickRay(x, y) → {PickRay}
Compute 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.
Returns:
The computed PickRay.
Type: PickRay
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);
getCameraEntity() → {Uuid}
Get the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You can also get the entity ID using the Camera.cameraEntity property.
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.
Type: Uuid
getModeString() → {Camera.Mode}
Get the current camera mode. You can also get the mode using the Camera.mode property.
Returns:
The current camera mode.
Type: Camera.Mode
getOrientation() → {Quat}
Get the current camera orientation. You can also get the orientation using the Camera.orientation property.
Returns:
The current camera orientation.
Type: Quat
getPosition() → {Vec3}
Get the current camera position. You can also get the position using the Camera.position property.
Returns:
The current camera position.
Type: Vec3
keepLookingAt(position)
Set 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 Position to keep looking at.
lookAt(position)
Rotate the camera to look at the specified position. Only works if the camera is in independent mode.
Parameters:
Name Type Description
position Vec3 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);
setCameraEntity(entityID)
Set the entity that the camera should 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);
  
setModeString(mode)
Set 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.
setOrientation(orientation)
Set 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.
setPosition(position)
Set 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.
stopLookingAt()
Stops the camera from continually looking at the position that was set with Camera.keepLookingAt.

Signals

modeUpdated(newMode) → {Signal}
Triggered when the camera mode changes.
Parameters:
Name Type Description
newMode Camera.Mode The new camera mode.
Returns:
Type: Signal
Example

Report camera mode changes.

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

Camera.modeUpdated.connect(onCameraModeUpdated);
   

Type Definitions

Mode

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.
Type: string