Skip to Content
defold-typescript
Get startedGuidesAPILibraries
Defold

camera

Messages to control camera components and camera focus.

Functions

camera.get_aspect_ratio(camera?: Url | number | string | Hash): number

Gets the effective aspect ratio of the camera. If auto aspect ratio is enabled, returns the aspect ratio calculated from the current render target dimensions. Otherwise returns the manually set aspect ratio.

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • aspect_ratio: number — the effective aspect ratio.

camera.get_auto_aspect_ratio(camera?: Url | number | string | Hash): boolean

Returns whether auto aspect ratio is enabled. When enabled, the camera automatically calculates aspect ratio from render target dimensions. When disabled, uses the manually set aspect ratio value.

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • auto_aspect_ratio: boolean — true if auto aspect ratio is enabled

camera.get_cameras(): Url[]

This function returns a table with all the camera URLs that have been registered in the render context.

const predicate = render.predicate([hash("my_tag")]);
for (const camera_id of camera.get_cameras()) {
  render.set_camera(camera_id);
  render.draw(predicate);
  render.set_camera();
}
for k,v in pairs(camera.get_cameras()) do
    render.set_camera(v)
    render.draw(...)
    render.set_camera()
end

Returns

  • cameras: Url[] — a table with all camera URLs

camera.get_enabled(camera?: Url | number | string | Hash): boolean

get enabled

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • flag: boolean — true if the camera is enabled

camera.get_far_z(camera?: Url | number | string | Hash): number

get far z

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • far_z: number — the far z.

camera.get_fov(camera?: Url | number | string | Hash): number

get field of view

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • fov: number — the field of view.

camera.get_near_z(camera?: Url | number | string | Hash): number

get near z

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • near_z: number — the near z.

camera.get_orthographic_auto_zoom(camera?: Url | number | string | Hash): numberN

  • Since Defold 1.13.0

Gets the orthographic zoom calculated from the current window and project dimensions in auto-fit and auto-cover modes. Returns 1.0 in fixed mode.

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • orthographic_auto_zoom: number — the calculated orthographic auto zoom.

camera.get_orthographic_mode(camera?: Url | number | string | Hash): number

get orthographic zoom mode

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

camera.get_orthographic_zoom(camera?: Url | number | string | Hash): number

Gets the positive user-controlled orthographic zoom multiplier. In auto-fit and auto-cover modes, this value is multiplied with camera.get_orthographic_auto_zoom(camera).

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • orthographic_zoom: number — the positive zoom multiplier when the camera uses orthographic projection.

camera.get_projection(camera?: Url | number | string | Hash): Matrix4

get projection matrix

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • projection: Matrix4 — the projection matrix.

camera.get_view(camera?: Url | number | string | Hash): Matrix4

get view matrix

Parameters

  • camera?: Url | number | string | Hash — camera id

Returns

  • view: Matrix4 — the view matrix.

camera.screen_to_world(pos: Vector3, camera?: Url | number | string | Hash): Vector3

Converts a screen-space 2D point with view depth to a 3D world point. z is the view depth in world units measured from the camera plane along the camera forward axis. If a camera isn't specified, the last enabled camera is used.

// Place objects at the touch point with a random Z position, keeping them
// within the visible view zone.
export default defineScript({
  on_input(self, action_id, action) {
    if (action_id === hash("touch")) {
      if (action.pressed && action.screen_x !== undefined && action.screen_y !== undefined) {
        const perspective_camera = msg.url("#perspective_camera");
        const random_z = math.random(
          camera.get_near_z(perspective_camera) + 0.01,
          camera.get_far_z(perspective_camera) - 0.01,
        );
        const world_position = camera.screen_to_world(
          vmath.vector3(action.screen_x, action.screen_y, random_z),
          perspective_camera,
        );
        go.set_position(world_position, "/go1");
      }
    }
  },
});
 function on_input(self, action_id, action)
     if action_id == hash("touch") then
         if action.pressed then
             local percpective_camera = msg.url("#perspective_camera")
             local random_z = math.random(camera.get_near_z(percpective_camera) + 0.01, camera.get_far_z(percpective_camera) - 0.01)
             local world_position = camera.screen_to_world(vmath.vector3(action.screen_x, action.screen_y, random_z), percpective_camera)
             go.set_position(world_position, "/go1")
         end
     end
 end

Parameters

  • pos: Vector3 — Screen-space position (x, y) with z as view depth in world units
  • camera?: Url | number | string | Hash — optional camera id

Returns

  • world_pos: Vector3 — the world coordinate

camera.screen_xy_to_world(x: number, y: number, camera?: Url | number | string | Hash): Vector3

Converts 2D screen coordinates (x,y) to the 3D world-space point on the camera's near plane for that pixel. If a camera isn't specified, the last enabled camera is used.

// Place objects at the touch point.
export default defineScript({
  on_input(self, action_id, action) {
    if (action_id === hash("touch")) {
      if (action.pressed && action.screen_x !== undefined && action.screen_y !== undefined) {
        const world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y);
        go.set_position(world_position, "/go1");
      }
    }
  },
});
 function on_input(self, action_id, action)
     if action_id == hash("touch") then
         if action.pressed then
             local world_position = camera.screen_xy_to_world(action.screen_x, action.screen_y)
             go.set_position(world_position, "/go1")
         end
     end
 end

Parameters

  • x: number — X coordinate on screen.
  • y: number — Y coordinate on screen.
  • camera?: Url | number | string | Hash — optional camera id

Returns

  • world_pos: Vector3 — the world coordinate on the camera near plane

camera.set_aspect_ratio(camera: Url | number | string | Hash | undefined, aspect_ratio: number): void

Sets the manual aspect ratio for the camera. This value is only used when auto aspect ratio is disabled. To disable auto aspect ratio and use this manual value, call camera.set_auto_aspect_ratio(camera, false).

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • aspect_ratio: number — the manual aspect ratio value.

camera.set_auto_aspect_ratio(camera: Url | number | string | Hash | undefined, auto_aspect_ratio: boolean): void

Enables or disables automatic aspect ratio calculation. When enabled (true), the camera automatically calculates aspect ratio from render target dimensions. When disabled (false), uses the manually set aspect ratio value.

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • auto_aspect_ratio: boolean — true to enable auto aspect ratio

camera.set_far_z(camera: Url | number | string | Hash | undefined, far_z: number): void

set far z

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • far_z: number — the far z.

camera.set_fov(camera: Url | number | string | Hash | undefined, fov: number): void

set field of view

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • fov: number — the field of view.

camera.set_near_z(camera: Url | number | string | Hash | undefined, near_z: number): void

set near z

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • near_z: number — the near z.

camera.set_orthographic_mode(camera: Url | number | string | Hash | undefined, mode: number): void

set orthographic zoom mode

Parameters

camera.set_orthographic_zoom(camera: Url | number | string | Hash | undefined, orthographic_zoom: number): void

Sets the positive user-controlled orthographic zoom multiplier. In auto-fit and auto-cover modes, this value is multiplied with camera.get_orthographic_auto_zoom(camera).

Parameters

  • camera: Url | number | string | Hash | undefined — camera id
  • orthographic_zoom: number — the positive zoom multiplier when the camera uses orthographic projection.

camera.world_to_screen(world_pos: Vector3, camera?: Url | number | string | Hash): Vector3

Converts a 3D world position to screen-space coordinates with view depth. Returns a vector3 where x and y are in screen pixels and z is the view depth in world units measured from the camera plane along the camera forward axis. The returned z can be used with camera.screen_to_world to reconstruct the world position on the same pixel ray. If a camera isn't specified, the last enabled camera is used.

// Convert a game object position into a screen position.
go.update_world_transform("/go1");
const world_pos = go.get_world_position("/go1");
const screen_pos = camera.world_to_screen(world_pos);
 go.update_world_transform("/go1")
 local world_pos = go.get_world_position("/go1")
 local screen_pos = camera.world_to_screen(world_pos)

Parameters

  • world_pos: Vector3 — World-space position
  • camera?: Url | number | string | Hash — optional camera id

Returns

  • screen_pos: Vector3 — Screen position (x,y in pixels, z is view depth)

Constants

camera.ORTHO_MODE_AUTO_COVER: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_COVER" }

auto-cover orthographic zoom mode Computes zoom so the original display area covers the entire window while preserving aspect ratio. Equivalent to using max(window_width/width, window_height/height). The result is multiplied by the user-controlled orthographic zoom.

camera.ORTHO_MODE_AUTO_FIT: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_FIT" }

auto-fit orthographic zoom mode Computes zoom so the original display area (game.project width/height) fits inside the window while preserving aspect ratio. Equivalent to using min(window_width/width, window_height/height). The result is multiplied by the user-controlled orthographic zoom.

camera.ORTHO_MODE_FIXED: number & { readonly __brand: "camera.ORTHO_MODE_FIXED" }

fixed orthographic zoom mode Uses the manually set orthographic zoom value (camera.set_orthographic_zoom).

Properties

aspect_ratio: numberN

  • Since Defold 1.13.0

The ratio between the frustum width and height. Used when calculating the projection of a perspective camera. The type of the property is number.

far_z: numberN

  • Since Defold 1.13.0

Camera frustum far plane. The type of the property is float.

fov: numberN

  • Since Defold 1.13.0

Vertical field of view of the camera. The type of the property is float.

near_z: numberN

  • Since Defold 1.13.0

Camera frustum near plane. The type of the property is float.

orthographic_auto_zoom: numberN

  • Since Defold 1.13.0

READ ONLY The zoom calculated from the current window and project dimensions in auto fit and auto cover modes. The value is 1.0 in fixed mode. The type of the property is float.

orthographic_zoom: numberN

  • Since Defold 1.13.0

Positive zoom multiplier when using an orthographic projection. In auto fit and auto cover modes, this value is multiplied with the calculated orthographic_auto_zoom value. The type of the property is float.

projection: Matrix4N

  • Since Defold 1.13.0

READ ONLY The calculated projection matrix of the camera. The type of the property is matrix4.

view: Matrix4N

  • Since Defold 1.13.0

READ ONLY The calculated view matrix of the camera. The type of the property is matrix4.

On this page

Functionscamera.get_aspect_ratio(camera?: Url | number | string | Hash): numbercamera.get_auto_aspect_ratio(camera?: Url | number | string | Hash): booleancamera.get_cameras(): Url[]camera.get_enabled(camera?: Url | number | string | Hash): booleancamera.get_far_z(camera?: Url | number | string | Hash): numbercamera.get_fov(camera?: Url | number | string | Hash): numbercamera.get_near_z(camera?: Url | number | string | Hash): numbercamera.get_orthographic_auto_zoom(camera?: Url | number | string | Hash): numberNcamera.get_orthographic_mode(camera?: Url | number | string | Hash): numbercamera.get_orthographic_zoom(camera?: Url | number | string | Hash): numbercamera.get_projection(camera?: Url | number | string | Hash): Matrix4camera.get_view(camera?: Url | number | string | Hash): Matrix4camera.screen_to_world(pos: Vector3, camera?: Url | number | string | Hash): Vector3camera.screen_xy_to_world(x: number, y: number, camera?: Url | number | string | Hash): Vector3camera.set_aspect_ratio(camera: Url | number | string | Hash | undefined, aspect_ratio: number): voidcamera.set_auto_aspect_ratio(camera: Url | number | string | Hash | undefined, auto_aspect_ratio: boolean): voidcamera.set_far_z(camera: Url | number | string | Hash | undefined, far_z: number): voidcamera.set_fov(camera: Url | number | string | Hash | undefined, fov: number): voidcamera.set_near_z(camera: Url | number | string | Hash | undefined, near_z: number): voidcamera.set_orthographic_mode(camera: Url | number | string | Hash | undefined, mode: number): voidcamera.set_orthographic_zoom(camera: Url | number | string | Hash | undefined, orthographic_zoom: number): voidcamera.world_to_screen(world_pos: Vector3, camera?: Url | number | string | Hash): Vector3Constantscamera.ORTHO_MODE_AUTO_COVER: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_COVER" }camera.ORTHO_MODE_AUTO_FIT: number & { readonly __brand: "camera.ORTHO_MODE_AUTO_FIT" }camera.ORTHO_MODE_FIXED: number & { readonly __brand: "camera.ORTHO_MODE_FIXED" }Propertiesaspect_ratio: numberNfar_z: numberNfov: numberNnear_z: numberNorthographic_auto_zoom: numberNorthographic_zoom: numberNprojection: Matrix4Nview: Matrix4N