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.

Inherits from

Usage

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

local SgCamera = require 'engine/sceneobjects/sgcamera'

Reference

class Projection

Enumeration of the available projection modes

Name

Description

Perspective

perspective projection

Orthographic

orthographic projection
class CameraMode

Enumeration of the available camera modes

Name

Description

Free

Camera uses transform to freely rotate

LookAt

Camera uses the lookAt/upVector to handle rotation of the camera
class SgCamera
module:

Camera

create(options, parent)

Create a new camera object in the scenegraph.

Parameters:

  • options (table) – A table of options to fill the parameters

  • parent (SceneObject) – The parent scene object to add this to

Returns:

a promise which will resolve to the created object

Return type:

Promise

Usage:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
-- 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 = {0},
    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)
})
setDefault()

setDefault

activate()

activate the camera

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(x, y, z)

Set up vector of the camera

Parameters:

  • x (number)

  • y (number)

  • z (number)

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:

4x4 view matrix

Return type:

Matrix

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:

the projection 4x4 matrix

Return type:

Matrix

projectPointToNDC(x, y, z)

Projects a 3D point from world space into Normalized 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:

{ x: number, y: number, z: number } NDC coordinates

Return type:

table

projectPointToScreen(x, y, z)

Projects a 3D point from world space into screen 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:

{ x: number, y: number } screen coordinates in pixels

Return type:

table

Examples