britzl/defold-orthographic/orthographic.camera
Orthographic camera functionality for the Defold game engine
- GitHub: britzl/defold-orthographic — pinned to
3.6.4- Pick a release from britzl/defold-orthographic releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as camera from "orthographic.camera"
- Pick a release from britzl/defold-orthographic releases and add its Source code (zip) URL (or a packaged
Functions
follow(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)
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 cameratargets:Hash | Url | (Hash | Url)[]— Game object(s) to followoptions?:{ lerp?: number; offset?: Vector3; horizontal?: boolean; vertical?: boolean; immediate?: boolean; }— Optionslerp?: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 camerazoom: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 cameraenabled: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 cameraintensity?:number— Intensity of the shake, in percent of screen. Defaults to 0.05duration?:number— Duration of the shake, in seconds. Defaults to 0.5direction?:{ both?: boolean; horizontal?: boolean; vertical?: boolean; }— Direction of the shake. Possible values:both,horizontal,vertical. Defaults toboth.both?:booleanhorizontal?:booleanvertical?: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 camerascreen: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 camerawindow: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 | Urloffset:Vector3— Offset to apply to the camera. Defaults to 0.05duration?: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 cameraoffset: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 cameraleft:number— Number of pixels to the left of the cameratop:number— Number of pixels above the cameraright:number— Number of pixels to the right of the camerabottom: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 cameraleft:number— Left edge of the camera boundstop:number— Top edge of camera boundsright:number— Right edge of camera boundsbottom: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 cameraworld: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:Matrix4projection:Matrix4screen: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:Matrix4projection:Matrix4world: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.