SgCamera

Represents a camera in the scene used to render the view from a specific perspective. Supports various projection modes (e.g., perspective, orthographic). Usually attached to the player or used for cinematic scenes and off-screen rendering.

Switching Cameras at Runtime

You can switch between cameras dynamically by using the Composer.setValue function to set the active camera by its tag. Make sure the camera node has a unique name assigned via its Name property. For example:

-- Switch to a camera with the tag "CinematicCamera"
Composer.setValue("Camera", "Tag", "CinematicCamera")

The first parameter, "Camera", specifies the type of value being set. The second parameter, "Tag", indicates that you are targeting the camera's tag. The third parameter is the tag of the camera you want to activate.

Inherits from

SceneObject

Usage

To use this class, add the following require at the top of your script:

local SgCamera = require 'engine/sceneobjects/sgcamera'

Reference

create

static create(self, options, parent)

Create a new camera object in the scenegraph.

Parameters

• self
• options (table): A table of options to fill the parameters
• parent (SceneObject): The parent scene object to add this to

Returns

• Promise: promise which will resolve to the created object

Example

-- Options can be omitted. This example shows the defaults,
-- only specify the ones you want different.
SgCamera.create({
    active = true,
    name = "",
    transform = Transform.new(),
    layers = {1},
    tags = {},
    type = SgCamera.Projection.Perspective,
    fieldOfView = 60,
    left = -1,
    right = 1,
    top = -1,
    bottom = 1,
    nearPlane = 0.1,
    farPlane = 1000,
    mode = SgCamera.CameraMode.Free,
    lookAt = Vector3.new(0, 0, 0),
    upVector = Vector3.new(0, 1, 0)
})

Properties

You can access these properties directly on the object or through :get("propertyName") or :set("propertyName", value) methods.

setDefault

setDefault()

setDefault

activate

activate()

activate the camera

lookAt

lookAt(x, y, z)

Set the look at position of the camera. Camera need to be in look at mode for this to have an effect

Parameters

• x (number)
• y (number)
• z (number)

setUpVector

setUpVector(x, y, z)

Set up vector of the camera

Parameters

• x (number)
• y (number)
• z (number)

getViewMatrix

getViewMatrix()

Returns the view matrix of the camera.

The view matrix transforms coordinates from world space to view space (camera-relative space). Hence, the view matrix is the inverse of the camera's world transform.

Returns

• Matrix: view matrix

getProjectionMatrix

getProjectionMatrix()

Returns the projection matrix of the camera.

The projection matrix defines how 3D points in view space are projected into clip space. - For a perspective projection, it applies perspective division so that distant objects appear smaller. - For an orthographic projection, it preserves object size regardless of distance.

The projection matrix transforms points from view space to clip space. After the transformation, the coordinates are in homogeneous clip space, and then converted to Normalized Device Coordinates (NDC) by dividing by the w component of the homogeneous coordinate vector.

This matrix is essential for converting 3D world coordinates to 2D screen coordinates.

Returns

• Matrix: projection 4x4 matrix

projectPointToNDC

projectPointToNDC(x, y, z)

Projects a 3D point from world space intoNormalized Device Coordinates (NDC)**.**

This applies the full transformation: world → view → clip → NDC. The result is a 3D point in NDC, where: - X ∈ [-1, 1] maps to horizontal screen space (left to right) - Y ∈ [-1, 1] maps to vertical screen space (bottom to top) - Z ∈ [-1, 1] corresponds to the camera’s depth range (near to far)

Values outside of [-1, 1] in X or Y indicate the point is offscreen. Z outside [-1, 1] indicates the point is behind the near or beyond the far plane.

Parameters

• x (number): X position in world space
• y (number): Y position in world space
• z (number): Z position in world space

Returns

• Vector2: coordinates

projectPointToScreen

projectPointToScreen(x, y, z)

Projects a 3D point from world space intoscreen coordinates** in pixels.**

This performs the same transformation as projectPointToNDC, but maps the resulting NDC coordinates into screen space using the current viewport size.

The result: - X ∈ [0, screenWidth] where 0 is the left edge and screenWidth is the right - Y ∈ [0, screenHeight] where 0 is the top and screenHeight is the bottom (Y-flipped)

This is useful for positioning GUI elements, tooltips, or 2D overlays on top of 3D content.

Parameters

• x (number): X position in world space
• y (number): Y position in world space
• z (number): Z position in world space

Returns

• Vector2: coordinates in pixels

screenPointToRay

screenPointToRay(x, y, width, height)

Unprojects a 2D screen coordinate in pixels to a 3D world space ray

Parameters

• x (number): X screen coordinate
• y (number): Y screen coordinate
• width (number): Width of the screen in pixels
• height (number): Height of the screen in pixels

Returns

• table: origin: Vector3, direction: Vector3 } position and direction vectors

Enum: Projection

Enumeration of the available projection modes

Enum: CameraMode

Enumeration of the available camera modes