britzl/defold-orthographic/orthographic.camera

Orthographic camera functionality for the Defold game engine

GitHub: britzl/defold-orthographic — pinned to 2fe3aed
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, target: Hash | Url, options?: { lerp?: number; offset?: Vector3; horizontal?: boolean; vertical?: boolean; immediate?: boolean; })
get_zoom(camera_id: Hash | Url | undefined): number
set_zoom(camera_id: Hash | Url | undefined, zoom: number)
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): Vector3
window_to_world(camera_id: Hash | Url | undefined, window: Vector3): Vector3
get_display_size(): LuaMultiReturn<[ number, number ]>
get_window_size(): LuaMultiReturn<[ number, number ]>
get_cameras(): Array<Hash | Url | undefined>
get_view(camera_id: Hash | Url | undefined): Matrix4
get_viewport(camera_id: Hash | Url | undefined): LuaMultiReturn<[ number, number, number, number ]>
get_projection(camera_id: Hash | Url | undefined): Matrix4
get_projection_id(camera_id: Hash | Url | undefined): Hash
recoil(camera_id: Hash | Url, offset: Vector3, duration?: number)
get_offset(camera_id: Hash | Url | undefined): Vector3
follow_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): Vector4
world_to_screen(camera_id: Hash | Url | undefined, world: Vector3, adjust_mode?: typeof gui.ADJUST_FIT | typeof gui.ADJUST_STRETCH | typeof gui.ADJUST_ZOOM): Vector3
unproject(view: Matrix4, projection: Matrix4, screen: Vector3): Vector3
project(view: Matrix4, projection: Matrix4, world: Vector3): Vector3
add_projector(projector_id: Hash, projector_fn: (id: Hash, near_z: number, far_z: number) => void)
use_projector(camera_id: Hash | Url | undefined, projector_id: Hash)
set_window_scaling_factor(scaling_factor: number)

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

Follow a game object.

Parameters

camera_id: Hash | Url | undefined — undefined for the first camera
target: Hash | Url — Game object 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

`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

`get_projection_id(camera_id: Hash | Url | undefined): Hash`

Get the current projection id of the camera.

Parameters

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

Returns

Hash

`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, adjust_mode?: typeof gui.ADJUST_FIT | typeof gui.ADJUST_STRETCH | typeof gui.ADJUST_ZOOM): Vector3`

Translate world coordinates to screen coordinates, based on the view and projection of the camera, optionally taking into account an adjust mode. 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
adjust_mode?: typeof gui.ADJUST_FIT | typeof gui.ADJUST_STRETCH | typeof gui.ADJUST_ZOOM — One of gui.ADJUST_FIT, gui.ADJUST_ZOOM and gui.ADJUST_STRETCH, or undefined to not take into account the adjust mode.

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

`add_projector(projector_id: Hash, projector_fn: (id: Hash, near_z: number, far_z: number) => void)`

Add a custom projector that can be used by cameras in your project (see configuration above).

Parameters

projector_id: Hash — Id of the projector. Used as a value in the projection field of the camera script.
projector_fn: (id: Hash, near_z: number, far_z: number) => void — The function to call when a projection matrix is needed for the camera. The function will receive the id, near_z and far_z values of the camera.

`use_projector(camera_id: Hash | Url | undefined, projector_id: Hash)`

Set a specific projector for a camera. This must be either one of the predefined projectors (see above) or a custom projector added using camera.add_projector().

Parameters

camera_id: Hash | Url | undefined — undefined for the first camera
projector_id: Hash — Id of the projector.

`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