Skip to Content
defold-typescript libraries
britzl

britzl/defold-orthographic/orthographic.camera

Orthographic camera functionality for the Defold game engine

  • GitHub: britzl/defold-orthographic — pinned to 3.6.4
    1. Pick a release from britzl/defold-orthographic releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as camera from "orthographic.camera"

Functions

follow(camera_id: Hash | Url | undefined, targets: Hash | Url | (Hash | Url)[], options?: { lerp?: number; offset?: Vector3; horizontal?: boolean; vertical?: boolean; immediate?: boolean; })

Follow one or more game objects. When following multiple objects the camera will follow the center point between the objects.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • targets: Hash | Url | (Hash | Url)[] — Game object(s) to follow
  • options?: { lerp?: number; offset?: Vector3; horizontal?: boolean; vertical?: boolean; immediate?: boolean; } — Options
    • lerp?: number — Lerp from current position to target position with lerp as t.
    • offset?: Vector3 — Camera offset from target position.
    • horizontal?: boolean — True if following the target along the horizontal axis.
    • vertical?: boolean — True if following the target along the vertical axis.
    • immediate?: boolean — True if the camera should be immediately positioned on the target even when lerping.

get_zoom(camera_id: Hash | Url | undefined): number

Get the current zoom level of the camera.

Parameters

  • camera_id: Hash | Url | undefined — (hash | url), undefined for the first camera

Returns

  • number

set_zoom(camera_id: Hash | Url | undefined, zoom: number)

Change the zoom level of the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • zoom: number — The new zoom level of the camera

get_automatic_zoom(camera_id: Hash | Url | undefined): boolean

Get if the camera is configured to use automatic zoom level.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • boolean

set_automatic_zoom(camera_id: Hash | Url | undefined, enabled: boolean)

Set if the camera should use automatic zoom level.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • enabled: boolean — True if automatic zoom should be enabled

shake(camera_id: Hash | Url | undefined, intensity?: number, duration?: number, direction?: { both?: boolean; horizontal?: boolean; vertical?: boolean; }, cb?: () => void)

Shake the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • intensity?: number — Intensity of the shake, in percent of screen. Defaults to 0.05
  • duration?: number — Duration of the shake, in seconds. Defaults to 0.5
  • direction?: { both?: boolean; horizontal?: boolean; vertical?: boolean; } — Direction of the shake. Possible values: both, horizontal, vertical. Defaults to both.
    • both?: boolean
    • horizontal?: boolean
    • vertical?: boolean
  • cb?: () => void — Function to call when the shake has finished. Optional.

stop_shaking(camera_id: Hash | Url | undefined)

Stop shaking the camera.

Parameters

  • camera_id: Hash | Url | undefined — (hash | url), undefined for the first camera

screen_to_world(camera_id: Hash | Url | undefined, screen: Vector3): Vector3

Translate screen coordinates to world coordinates, based on the view and projection of the camera.

Parameters

  • camera_id: Hash | Url | undefined — (hash | url), undefined for the first camera
  • screen: Vector3 — Screen coordinates to convert

Returns

  • Vector3

window_to_world(camera_id: Hash | Url | undefined, window: Vector3): Vector3

Translate window coordinates to world coordinates, based on the view and projection of the camera.

Parameters

  • camera_id: Hash | Url | undefined — (hash | url), undefined for the first camera
  • window: Vector3 — Window coordinates to convert

Returns

  • Vector3

get_display_size(): LuaMultiReturn<[ number, number ]>

Get the display size (ie from game.project).

Returns

  • LuaMultiReturn<[ number, number ]>

get_window_size(): LuaMultiReturn<[ number, number ]>

Get window size.

Returns

  • LuaMultiReturn<[ number, number ]>

get_cameras(): Array<Hash | Url | undefined>

Get list of camera ids.

Returns

  • Array<Hash | Url | undefined>

get_view(camera_id: Hash | Url | undefined): Matrix4

Get the current view of the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • Matrix4

get_viewport(camera_id: Hash | Url | undefined): LuaMultiReturn<[ number, number, number, number ]>

Get the current viewport of the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • LuaMultiReturn<[ number, number, number, number ]>

get_projection(camera_id: Hash | Url | undefined): Matrix4

Get the current projection of the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • Matrix4

recoil(camera_id: Hash | Url, offset: Vector3, duration?: number)

Apply a recoil effect to the camera. The recoil will decay using linear interpolation.

Parameters

  • camera_id: Hash | Url
  • offset: Vector3 — Offset to apply to the camera. Defaults to 0.05
  • duration?: number — Duration of the recoil, in seconds. Defaults to 0.5

get_offset(camera_id: Hash | Url | undefined): Vector3

Get the current offset of the camera (caused by shake or recoil)

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • Vector3

follow_offset(camera_id: Hash | Url | undefined, offset: Vector3)

Change the camera follow offset.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • offset: Vector3 — Camera offset from target position.

unfollow(camera_id: Hash | Url | undefined)

Stop following a game object.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

deadzone(camera_id: Hash | Url | undefined, left: number, top: number, right: number, bottom: number)

If following a game object this will add a deadzone around the camera position where the camera position will not update. If the target moves to the edge of the deadzone the camera will start to follow until the target returns within the bounds of the deadzone.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • left: number — Number of pixels to the left of the camera
  • top: number — Number of pixels above the camera
  • right: number — Number of pixels to the right of the camera
  • bottom: number — Number of pixels below the camera

bounds(camera_id: Hash | Url | undefined, left: number, top: number, right: number, bottom: number)

Limits the camera position to within the specified rectangle.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • left: number — Left edge of the camera bounds
  • top: number — Top edge of camera bounds
  • right: number — Right edge of camera bounds
  • bottom: number — Bottom edge of camera bounds

screen_to_world_bounds(camera_id: Hash | Url | undefined): Vector4

Translate screen boundaries (corners) to world coordinates, based on the view and projection of the camera.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera

Returns

  • Vector4

world_to_screen(camera_id: Hash | Url | undefined, world: Vector3): Vector3

Translate world coordinates to screen coordinates, based on the view and projection of the camera. This is useful when manually culling game objects and you need to determine if a world coordinate will be visible or not. It can also be used to position gui nodes on top of game objects.

Parameters

  • camera_id: Hash | Url | undefined — undefined for the first camera
  • world: Vector3 — World coordinates to convert

Returns

  • Vector3

unproject(view: Matrix4, projection: Matrix4, screen: Vector3): Vector3

Translate screen coordinates to world coordinates using the specified view and projection.

Parameters

  • view: Matrix4
  • projection: Matrix4
  • screen: Vector3 — Screen coordinates to convert

Returns

  • Vector3

project(view: Matrix4, projection: Matrix4, world: Vector3): Vector3

Translate world coordinates to screen coordinates using the specified view and projection.

Parameters

  • view: Matrix4
  • projection: Matrix4
  • world: Vector3 — World coordinates to convert

Returns

  • Vector3

set_window_scaling_factor(scaling_factor: number)

Set window scaling factor (basically retina or no retina screen). There is no built-in way to detect if Defold is running on a retina or non retina screen. This information combined with the High DPI setting in game.project can be used to ensure that the zoom behaves the same way regardless of screen type and High DPI setting. You can use an extension such as DefOS to get the window scaling factor.

Parameters

  • scaling_factor: number — Current window scaling factor

Variables

PROJECTOR: { FIXED_ZOOM: Hash; DEFAULT: Hash; FIXED_AUTO: Hash; }

SHAKE_BOTH: Hash

SHAKE_VERTICAL: Hash

SHAKE_HORIZONTAL: Hash

MSG_DISABLE: Hash

MSG_UNFOLLOW: Hash

MSG_FOLLOW: Hash

MSG_FOLLOW_OFFSET: Hash

MSG_RECOIL: Hash

MSG_SHAKE: Hash

MSG_SHAKE_COMPLETED: Hash

MSG_STOP_SHAKING: Hash

MSG_DEADZONE: Hash

MSG_BOUNDS: Hash

MSG_UPDATE_CAMERA: Hash

MSG_ZOOM_TO: Hash

MSG_SET_AUTOMATIC_ZOOM: Hash

Posted to a camera to turn automatic zoom on or off.

MSG_VIEWPORT: Hash

MSG_ENABLE: Hash

On this page

Functionsfollow(camera_id: Hash | Url | undefined, targets: Hash | Url | (Hash | Url)[], options?: { lerp?: number; offset?: Vector3; horizontal?: boolean; vertical?: boolean; immediate?: boolean; })get_zoom(camera_id: Hash | Url | undefined): numberset_zoom(camera_id: Hash | Url | undefined, zoom: number)get_automatic_zoom(camera_id: Hash | Url | undefined): booleanset_automatic_zoom(camera_id: Hash | Url | undefined, enabled: boolean)shake(camera_id: Hash | Url | undefined, intensity?: number, duration?: number, direction?: { both?: boolean; horizontal?: boolean; vertical?: boolean; }, cb?: () => void)stop_shaking(camera_id: Hash | Url | undefined)screen_to_world(camera_id: Hash | Url | undefined, screen: Vector3): Vector3window_to_world(camera_id: Hash | Url | undefined, window: Vector3): Vector3get_display_size(): LuaMultiReturn<[ number, number ]>get_window_size(): LuaMultiReturn<[ number, number ]>get_cameras(): Array<Hash | Url | undefined>get_view(camera_id: Hash | Url | undefined): Matrix4get_viewport(camera_id: Hash | Url | undefined): LuaMultiReturn<[ number, number, number, number ]>get_projection(camera_id: Hash | Url | undefined): Matrix4recoil(camera_id: Hash | Url, offset: Vector3, duration?: number)get_offset(camera_id: Hash | Url | undefined): Vector3follow_offset(camera_id: Hash | Url | undefined, offset: Vector3)unfollow(camera_id: Hash | Url | undefined)deadzone(camera_id: Hash | Url | undefined, left: number, top: number, right: number, bottom: number)bounds(camera_id: Hash | Url | undefined, left: number, top: number, right: number, bottom: number)screen_to_world_bounds(camera_id: Hash | Url | undefined): Vector4world_to_screen(camera_id: Hash | Url | undefined, world: Vector3): Vector3unproject(view: Matrix4, projection: Matrix4, screen: Vector3): Vector3project(view: Matrix4, projection: Matrix4, world: Vector3): Vector3set_window_scaling_factor(scaling_factor: number)VariablesPROJECTOR: { FIXED_ZOOM: Hash; DEFAULT: Hash; FIXED_AUTO: Hash; }SHAKE_BOTH: HashSHAKE_VERTICAL: HashSHAKE_HORIZONTAL: HashMSG_DISABLE: HashMSG_UNFOLLOW: HashMSG_FOLLOW: HashMSG_FOLLOW_OFFSET: HashMSG_RECOIL: HashMSG_SHAKE: HashMSG_SHAKE_COMPLETED: HashMSG_STOP_SHAKING: HashMSG_DEADZONE: HashMSG_BOUNDS: HashMSG_UPDATE_CAMERA: HashMSG_ZOOM_TO: HashMSG_SET_AUTOMATIC_ZOOM: HashMSG_VIEWPORT: HashMSG_ENABLE: Hash