# Camera

The Camera object can be aquired by calling this.scene().camera(). With it you can manipulate the attributes of your game’s camera.

Function | Description |
---|---|

farPlane() |
Returns the far render distance of the camera. |

fieldOfView() |
Returns the field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment. |

followForce() |
Returns the follow force of the camera. This determines how much ‘force’ the camera follows an object with. |

followOffset() |
Returns the follow offset of the camera. The camera will follow the object from this many units away. |

followThreshold() |
Returns the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving. |

nearPlane() |
Returns the near render distance of the camera. This is the minimum distance from the camera that an object will be rendered. |

orthoScale() |
Returns the orthographic scale of the camera (only works if camera projection is orthographic) |

position() |
Returns the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will return {0, 0, 0} until the relative position is changed with setPosition(), even if you adjust the camera position in the settings. |

projection() |
Returns the projection type of the camera. There are only two possibilities, kPerspective or kOrthogonal. |

rotation() |
Returns the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will return {0, 0, 0} until the relative rotation is changed with setRotation(), even if you adjust the rotation of your camera in the settings. |

rotationFollowSmooth() |
Returns the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp(). |

screenCenterRay() |
Casts a ray based on the center of the Camera. The object returned has the properties origin and direction. |

screenRay(point) |
Casts a ray based on the given screen point. The object returned has the properties origin and direction. This is useful in coordination with Physic’s World’s rayTest(). |

screenToWorld(screenPoint) |
Converts the given Vec2 screenPoint to a 3D World Position. |

setFarPlane(value) |
Sets the far render distance of the camera. This is the maximum distance from the camera that an object will be rendered. |

setFieldOfView(value) |
Sets field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment. |

setFollowForce(x, y, z) |
Sets the follow force of the camera. This determines how much ‘force’ the camera follows an object with. |

setFollowOffset(x, y, z) |
Sets the follow offset of the camera. The camera will follow the object from this many units away. |

setFollowThreshold(x, y, z) |
Sets the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving. |

setNearPlane(value) |
Sets the Near Render Distance of the camera. This is the minimum distance from the camera that an object will be rendered. |

setOrthoScale(value) |
Sets the orthographic scale of the camera (only works if camera projection is orthographic) |

setPosition(x, y, z) |
Sets the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will not override a camera’s position in the settings, but adjust the position relative to the original camera position. |

setPositionFollow(value) |
Sets which object the Camera will follow. There are three options you can pass. “None” – Camera will not follow anything |

setProjection(value) |
Sets the projection type of the camera. There are two possibilities: kPerspective or kOrthogonal. |

setProjectionMatrix(matrix) |
Sets a custom projection matrix. https://en.wikipedia.org/wiki/Projection_matrix |

setRotation(x, y, z) |
Sets the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will not override a camera’s rotation in the settings, but adjust the rotation relative to the original camera rotation. |

setRotationFollowSmooth(value) |
Sets the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp(). |

setRotationQuat(value) |
Sets the “additional” rotation in Quaternion. Note that unlike in Entity, these “setRotation” and “setRotationQuat” are independent, meaning that the result rotation will be a sum of these two. |

setWorldPosition(x, y, z) |
Sets the actual position of the camera, the same way it is set in the camera settings panel. Note that if the camera is set to follow position of a character or path, this function won’t work. Use setPosition() to change the camera’s position relative to the object it’s following. |

worldPosition() |
Returns the actual position of the camera. This is the same position as the one set in the camera settings panel. |

worldRotation() |
Returns the actual rotation of the camera. This is the same rotation as the one set in the camera settings panel. |

worldToScreen(x, y, z) |
Projects a World (3D) position into Screen (2D) coordinates. |

## farPlane()

Returns the far render distance of the camera.

### Returns

number The Far Render Distance of the camera. This is the maximum distance from the camera that an object will be rendered.

## fieldOfView()

Returns the field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.

### Returns

number the field of view of the camera.

## followForce()

Returns the follow force of the camera. This determines how much ‘force’ the camera follows an object with.

### Returns

Vec3 the {x, y, z} follow force of the camera.

## followOffset()

Returns the follow offset of the camera. The camera will follow the object from this many units away.

### Returns

Vec3 the {x, y, z} follow offset of the camera.

## followThreshold()

Returns the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving.

### Returns

Vec3 the {x, y, z} follow threshold of the camera.

## nearPlane()

Returns the near render distance of the camera. This is the minimum distance from the camera that an object will be rendered.

### Returns

number The near render distance of the camera.

## orthoScale()

Returns the orthographic scale of the camera (only works if camera projection is orthographic)

### Returns

number the orthographic scale of the camera

## position()

Returns the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will return {0, 0, 0} until the relative position is changed with setPosition(), even if you adjust the camera position in the settings.

### Returns

Vec3 the {x, y, z} relative position of the camera.

let camera = this.camera(); camera.setPositionFollow("Character"); log(camera.position()); // result: {0, 0, 0} camera.setPosition(0, 10, 0); // the camera still follows the Character, but 10 units higher log(camera.position()); // result: {0, 10, 0}

## projection()

Returns the projection type of the camera. There are only two possibilities, kPerspective or kOrthogonal.

### Returns

string “kPerspective” if the projection is Perspective, “kOrthogonal” if the projection is Orthogonal

## rotation()

Returns the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will return {0, 0, 0} until the relative rotation is changed with setRotation(), even if you adjust the rotation of your camera in the settings.

### Returns

Vec3 the {x, y, z} relative rotation of the camera.

let camera = this.camera(); camera.setPositionFollow("Character"); log(camera.rotation()); // result: {0, 0, 0}, regardless of camera settings camera.setRotation(30, 0, 0); // the camera still follows the Character, but rotated on the X axis log(camera.position()); // result: {30, 0, 0}

## rotationFollowSmooth()

Returns the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().

### Returns

number the rotation follow smoothness/coefficient

## screenCenterRay()

Returns a ray cast at the center of the Camera. The object returned has the properties origin and direction.

### Returns

Object the ray cast into the 3D world based on the screen point

## screenRay(point)

Returns a ray cast at the given screen point. The object returned has the properties origin and direction. This is useful in coordination with Physic’s World’s rayTest().

### Parameters

Vec2 point – an {x, y} coordinate on the screen

### Returns

Object the ray cast into the 3D world based on the screen point

```
function touchBegan(point){
let cam = this.scene().camera();
let ra = cam.screenRay(pt);
log(ra.origin);
log(ra.direction);
}
```

## screenToWorld(screenPoint)

Converts the given Vec2 screenPoint to a 3D World Position.

### Parameters

Vec2 screenPoint – an {x, y} coordinate on the screen

### Returns

Vec3 the {x, y, z} 3D world coordinate relative to the given Vec2 screenPoint

function touchMove(point){ // move an entity to the point where the user is touching the screen. let pos = this.scene().camera().screenToWorld(point); this.entity().setPosition(pos.x, pos.y, pos.z); }

## setFarPlane(value)

Sets the far render distance of the camera. This is the maximum distance from the camera that an object will be rendered.

### Parameters

number value – the new far render distance of the camera. Minimum 100.

## setFieldOfView(value)

Sets field of view of the camera. The field of view is the extent of the observable world that is seen at any given moment.

### Parameters

number value – the field of view, from a range of 10-100. The smaller the number, the more “focused in” your field of view becomes.

## setFollowForce(x, y, z)

Sets the follow force of the camera. This determines how much ‘force’ the camera follows an object with. Another way to think of this is the speed at which your camera reacts to the object’s movement.

### Parameters

number x – the x axis component of the follow force

number y – the y axis component of the follow force

number z – the z axis component of the follow force

## setFollowOffset(x, y, z)

Sets the follow offset of the camera. The camera will follow the object from this many units away.

### Parameters

number x – the x axis component of the follow offset

number y – the y axis component of the follow offset

number z – the z axis component of the follow offset

## setFollowThreshold(x, y, z)

Sets the follow threshold of the camera. This determines how far the followed object can get from the camera before it starts moving. A 0 follow threshold means the camera will start moving as soon as the object does, whereas a 100 means the camera starts moving when the object is 100 units away. This function also accepts a Vec3 optionally instead of x, y, z.

### Parameters

number x – the x axis component of the follow threshold

number y – the y axis component of the follow threshold

number z – the z axis component of the follow threshold

## setNearPlane(value)

Sets the Near Render Distance of the camera. This is the minimum distance from the camera that an object will be rendered.

### Parameters

number value – The Near Render Distance of the camera.

## setOrthoScale(value)

Sets the orthographic scale of the camera (only works if camera projection is orthographic)

### Parameters

number value – the new orthographic scale of the camera

## setPosition(x, y, z)

Sets the relative position of the camera. It is important to note that if your camera is set to position follow the Character or Path, that will take precedence over a position set with setPosition(). This function will not override a camera’s position in the settings, but adjust the position relative to the original camera position.

### Parameters

number x – the relative x axis position

number y – the relative y axis position

number z – the relative z axis position

let camera = this.camera(); camera.setPositionFollow("Character"); log(camera.position()); // result: {0, 0, 0} camera.setPosition(0, 10, 0); // the camera still follows the Character, but 10 units higher log(camera.position()); // result: {0, 10, 0}

## setPositionFollow(value)

Sets which object the Camera will follow. There are three options you can pass. “None” – Camera will not follow anything

“Game Path” – Game Path will be followed

“Character” – Any Entity that is considered a Character will be followed

### Parameters

string – three possibilities: “None”, “Game Path”, “Character”

## setProjection(value)

Sets the projection type of the camera. There are two possibilities: kPerspective or kOrthogonal. If an invalid string is passed, will default to perspective.

### Parameters

string – two possibilities: “kPerspective” or “kOrthogonal”

## setProjectionMatrix(matrix)

Sets a custom projection matrix. https://en.wikipedia.org/wiki/Projection_matrix

### Parameters

Mat4 matrix – custom projection matrix

## setRotation(x, y, z)

Sets the relative rotation of the camera. It is important to note that if your camera is set to rotation follow the Character or Path, that will take precedence over a rotation set with setRotation(). This function will not override a camera’s rotation in the settings, but adjust the rotation relative to the original camera rotation.

### Parameters

number x – the relative x axis rotation

number y – the relative y axis rotation

number z – the relative z axis rotation

let camera = this.camera(); camera.setPositionFollow("Character"); log(camera.rotation()); // result: {0, 0, 0}, regardless of camera settings camera.setRotation(30, 0, 0); // the camera still follows the Character, but rotated on the X axis log(camera.position()); // result: {30, 0, 0}

## setRotationFollowSmooth(value)

Sets the rotation smoothness of the camera. The range is 0-1. This is like the coefficient of Quaternion.slerp().

### Parameters

number value – the new rotation follow smoothness/coefficient

## setRotationQuat(value)

Sets the “additional” rotation in Quaternion. Note that unlike in Entity, these “setRotation” and “setRotationQuat” are independent, meaning that the result rotation will be a sum of these two.

### Parameters

Quaternion value – the new rotation in Quaternion

## setWorldPosition(x, y, z)

Sets the actual position of the camera, the same way it is set in the camera settings panel. Note that if the camera is set to follow position of a character or path, this function won’t work. Use setPosition() to change the camera’s position relative to the object it’s following.

Take care when using setWorldPosition and setPosition together, as setPosition sets a relative position based on the camera’s world position.

### Parameters

number x – the x-axis component of the new world position

number y – the y-axis component of the new world position

number z – the z-axis component of the new world position

## worldPosition()

Returns the actual position of the camera. This is the same position as the one set in the camera settings panel.

### Returns

Vec3 {x, y, z} position of the camera

## worldRotation()

Returns the actual rotation of the camera. This is the same rotation as the one set in the camera settings panel.

### Returns

Quaternion the rotation of the camera in Quaternion

## worldToScreen(x, y, z)

Projects a World (3D) position into Screen (2D) coordinates.

### Parameters

number x – the x-axis 3D coordinate

number y – the y-axis 3D coordinate

number z – the z-axis 3D coordinate

### Returns

Vec2 the resulting 2D screen coordinates