Orthographic camera API for the Defold game engine. The API wraps the Defold camera API and provides additional functionality to follow other game objects and to make camera effects such as screen shake and recoil.

The project is shipped with an example that shows all the features of the orthographic camera. Test the example app in your browser.

You can use the orthograpic camera in your own project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field under project add:

https://github.com/britzl/defold-orthographic/archive/master.zip

Or point to the ZIP file of a specific release.

Getting started with Orthographic is easy. Just add a camera.go to your game and configure the script properties of the camera.script attached to camera.go. The camera has the following configurable properties:

This is the near and far z-values used in the projection matrix, ie the near and far clipping plane. Anything with a z-value inside this range will be drawn by the render script.

This is the zoom level of the camera. Modify it by calling camera.set_zoom(), go.set(camera, "zoom", zoom) or go.animate(camera, "zoom", ...). Read it using camera.get_zoom() or go.get(camera_id, "zoom").

Note that when using go.animate(), go.get() and go.set() you need to make sure to specify the URL to the actual camera script and not to the camera game object:

• go.animate("mycamera#camerascript", "zoom", ...)
• go.set("mycamera#camerascript", "zoom")
• go.get("mycamera#camerascript", "zoom")

Check this property if you wish the camera to automatically adjust the zoom to fit the area covered by the display width and height defined in game.project on the screen regardless of actual physical screen resolution. This means that the camera will zoom out when the content is viewed on a screen with a lower resolution, and zoom in when the content is viewed on a higher resolution screen.

This value is used to sort the cameras in the list returned by camera.get_cameras(), from low to high values. In a multi-camera scenario the order can be used to control which camera to render first. This is for instance used in orthographic/render/orthographic.render_script.

This controls if the camera is enabled by default or not. Send enable and disable messages to the script or use go.set(id, "enable", true|false) to toggle this value.

This controls if the camera should follow a target or not. See camera.follow() for details.

This controls if the camera should follow the target along the horizontal axis or not. See camera.follow() for details.

This controls if the camera should follow the target along the vertical axis or not. See camera.follow() for details.

This controls if the camera should immediately position itself on the follow target when initialized or if it should apply lerp (see below). See camera.follow() for details.

Id of the game object to follow. See camera.follow() for details.

Amount of lerp when following a target. See camera.follow() for details.

Camera offset from the position of the followed target. See camera.follow() for details.

The camera bounds. See camera.bounds() for details.

The camera deadzone. See camera.deadzone() for details.

The camera viewport.

The default render script will always only render a single camera with a viewport covering the entire screen. In order to use multiple cameras or render the camera using a custom viewport you need to modify the render script or use the render script included in orthographic/render/orthographic.render_script

The camera API allows you to convert from screen to world coordinates and vice versa. Screen coordinates are the screen_x and screen_y values of an input and the values returned from camera.get_size().

The API can be used in two ways:

1. Calling functions on the camera.lua module
2. Sending messages to the camera.script

Get the current view of the camera.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• view (matrix) The current view

Get the current viewport of the camera.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• x (number) The viewport left position
• y (number) The viewport bottom position
• w (number) The viewport width
• h (number) The viewport height

Get the current projection of the camera.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• projection (matrix) The current projection

Shake the camera.

PARAMETERS

• camera_id (hash|url)
• 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 (hash) - Direction of the shake. Possible values: both, horizontal, vertical. Defaults to both.
• cb (function) - Function to call when the shake has finished. Optional.

Stop shaking the camera.

PARAMETERS

• camera_id (hash|url)

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 the current offset of the camera (caused by shake or recoil)

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• offset (vector3) The current offset of the camera

Get the current zoom level of the camera.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• zoom (number) The current zoom of the camera

Change the zoom level of the camera.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera
• zoom (number) The new zoom level of the camera

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

RETURN

• auto_zoom (boolean) True if automatic zoom is enabled

Set if the camera should use automatic zoom level.

PARAM

• enabled (boolean) True if automatic zoom should be enabled

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|nil) nil for the first camera
• targets (hash|url|table) - Game object(s) to follow
• options (table) - Options (see below)

Acceptable values for the options table:

• 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.

Change the camera follow offset.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera
• offset (vector3) - Camera offset from target position.

Stop following a game object.

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

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|nil) nil 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

Limits the camera position to within the specified rectangle.

PARAMETERS

• camera_id (hash|url|nil) nil 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

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

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera
• screen (vector3) Screen coordinates to convert

RETURN

• world_coords (vector3) World coordinates

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

PARAMETERS

• camera_id (hash|url|nil) nil for the first camera

RETURN

• bounds (vector4) Screen bounds (x = left, y = top, z = right, w = bottom)

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.

PARAMETER

• camera_id (hash|url|nil) nil for the first camera
• world (vector3) World coordinates to convert

RETURN

• screen_coords (vector3) Screen coordinates

Get the current window size. The default values will be the ones specified in game.project.

RETURN

• width (number) - Current window width.
• height (number) - Current window height.

Get the display size, as specified in game.project.

RETURN

• width (number) - Display width.
• height (number) - Display height.

Most of the functions of the API have message equivalents that can be sent to the camera component.

Message equivalent to camera.shake(). Accepted message keys: intensity, duration and direction.

msg.post("camera", "shake", { intensity = 0.05, duration = 2.5, direction = "both" })

Message equivalent to camera.stop_shaking().

msg.post("camera", "stop_shaking")

Message equivalent to camera.recoil(). Accepted message keys: offset and duration.

msg.post("camera", "recoil", { offset = vmath.vector3(100, 100, 0), duration = 0.75 })

Message sent back to the sender of a shake message when the shake has completed.

Message equivalent to camera.follow(). Accepted message keys: target, lerp, horizontal, vertical, immediate, offset.

msg.post("camera", "follow", { target = hash("player"), lerp = 0.7, horizontal = true, vertical = false, immediate = true })

Message equivalent to camera.follow_offset(). Accepted message keys: offset.

msg.post("camera", "follow_offset", { offset = vmath.vector3(150, 250, 0) })

Message equivalent to camera.unfollow().

msg.post("camera", "unfollow")

Message equivalent to camera.deadzone(). Accepted message keys: left, right, bottom and top.

msg.post("camera", "deadzone", { left = 10, right = 200, bottom = 10, top = 100 })

Message equivalent to camera.bounds(). Accepted message keys: left, right, bottom and top.

msg.post("camera", "bounds", { left = 10, right = 200, bottom = 10, top = 100 })

Message equivalent to camera.zoom_to(). Accepted message keys: zoom.

msg.post("camera", "zoom_to", { zoom = 2.5 })

Message equivalent to camera.set_automatic_zoom(). Accepted message keys: enabled.

msg.post("camera", "set_automatic_zoom", { enabled = true })

Enable the camera. While the camera is enabled it will update it's view and projection and send these to the render script.

msg.post("camera", "enable")

Disable the camera.

msg.post("camera", "disable")

Set which projection to use.

msg.post("camera", "use_projection", { projection = hash("FIXED_AUTO") })