Skip to Content
defold-typescript libraries
Klaleus

Klaleus/defold-shutter/shutter

Shutter is a library for 2D camera functionality in a Defold game engine project.

  • Codeberg: Klaleus/defold-shutter — pinned to fc0e632
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://codeberg.org/Klaleus/defold-shutter/archive/fc0e6321d7c2bbacf3a52ffe9e9b5b94b16954b1.zip — 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 shutter from "shutter.shutter"

Functions

activate(object: Hash): Matrix4

Installs a camera's viewport, view matrix and projection matrix into the render context. Call it from a render script before drawing the world.

Parameters

  • object: Hash — The game object the camera lives on.

Returns

  • Matrix4 — The camera's frustum, for passing to render.draw.

deactivate(): Matrix4

Restores the viewport and matrices Defold's GUI system expects, sized to the current window. Call it before drawing GUI.

Returns

  • Matrix4 — The frustum matching the restored matrices.

force_update(object: Hash)

Recalculates a camera's viewport, view matrix and projection matrix immediately. The shutter.script game object already does this once per frame; call it directly only after changing a camera property mid-frame.

Parameters

  • object: Hash — The game object the camera lives on.

get_viewport(object: Hash): LuaMultiReturn<[ number, number, number, number ]>

Calculates the camera's viewport in window coordinates, scaled from the game.project display size and, under center behavior, shrunk and centered to preserve the display ratio.

Parameters

  • object: Hash — The game object the camera lives on.

Returns

  • LuaMultiReturn<[ number, number, number, number ]> — The viewport's x, y, width and height.

get_view(object: Hash): Matrix4

Calculates the camera's view matrix from the inverse of its game object's world transform.

Parameters

  • object: Hash — The game object the camera lives on.

Returns

  • Matrix4

get_projection(object: Hash): Matrix4

Calculates the camera's orthographic projection matrix, sized from the display under center and stretch behavior and from the window under expand behavior.

Parameters

  • object: Hash — The game object the camera lives on.

Returns

  • Matrix4

get_frustum(object: Hash): Matrix4

Returns the camera's frustum, the product of its last calculated projection and view matrices.

Parameters

  • object: Hash — The game object the camera lives on.

Returns

  • Matrix4

get_distance(object: Hash, distance: Vector3, absolute?: boolean): Vector3

Converts a screen distance into the world distance an object must travel to cover it, accounting for the camera's zoom and, under center and stretch behavior, for the viewport no longer mapping to physical screen coordinates.

Parameters

  • object: Hash — The game object the camera lives on.
  • distance: Vector3 — The screen distance to convert.
  • absolute?: boolean — Skip rotating the result by the camera's rotation.

Returns

  • Vector3

shake(object: Hash, parent: boolean, count: number, duration: number, radius: number, duration_scalar?: number, radius_scalar?: number)

Starts a camera shake animation, cancelling and restarting any shake already running on this camera.

Parameters

  • object: Hash — The game object the camera lives on.
  • parent: boolean — Shake the camera object's parent instead of the camera itself.
  • count: number — How many times to displace the camera before stopping.
  • duration: number — Seconds each displacement takes.
  • radius: number — How far each displacement moves the camera.
  • duration_scalar?: number — Multiplies the duration after each displacement. Defaults to 1.
  • radius_scalar?: number — Multiplies the radius after each displacement. Defaults to 1.

cancel_shake(object: Hash, parent?: boolean)

Stops a running camera shake and returns the shaken object to where it started. Does nothing if no shake is running.

Parameters

  • object: Hash — The game object the camera lives on.
  • parent?: boolean — Whether the shake was started against the camera object's parent.

screen_to_world(object: Hash, x: number, y: number, visible?: boolean): Vector3 | undefined

Converts a screen position to its world position through the inverse of the camera's frustum.

Parameters

  • object: Hash — The game object the camera lives on.
  • x: number — The screen position's x coordinate.
  • y: number — The screen position's y coordinate.
  • visible?: boolean — Return nil instead when the position falls outside the camera's view.

Returns

  • Vector3 | undefined — The world position, or nil if visible filtered it out.

world_to_screen(object: Hash, position: Vector3, visible?: boolean): Vector3 | undefined

Converts a world position to its screen position through the camera's frustum.

Parameters

  • object: Hash — The game object the camera lives on.
  • position: Vector3 — The world position to convert.
  • visible?: boolean — Return nil instead when the position falls outside the camera's view.

Returns

  • Vector3 | undefined — The screen position, or nil if visible filtered it out.

Variables

camera_table: LuaMap<Hash, ShutterCamera>

Every live camera, keyed by the id of the game object it lives on. The shutter.script file writes to it; read from it rather than manipulating it directly.

center_behavior: Hash

Keeps the projection fixed and shrinks the viewport to preserve the display ratio, letterboxing or pillarboxing the remainder.

expand_behavior: Hash

Keeps the viewport filling the window and widens the projection as the window grows, showing more of the game world rather than scaling it.

stretch_behavior: Hash

Keeps both the viewport and the projection filling the window, so the game world distorts with the window ratio.

Types

ShutterCamera

ShutterCamera.behavior: Hash

One of center_behavior, expand_behavior or stretch_behavior.

ShutterCamera.viewport_x: number

ShutterCamera.viewport_y: number

ShutterCamera.viewport_width: number

ShutterCamera.viewport_height: number

ShutterCamera.near: number

ShutterCamera.far: number

ShutterCamera.zoom: number

ShutterCamera.viewport_x_adjusted: number

Viewport left edge after the window scale and any letterboxing margin.

ShutterCamera.viewport_y_adjusted: number

Viewport bottom edge after the window scale and any pillarboxing margin.

ShutterCamera.viewport_width_adjusted: number

ShutterCamera.viewport_height_adjusted: number

ShutterCamera.view: Matrix4

ShutterCamera.projection: Matrix4

ShutterCamera.shake_origin?: Vector3

Where the shaken object sat before the shake began, and nil while no shake is running. cancel_shake restores the object to it.

On this page