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- 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— 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 shutter from "shutter.shutter"
- This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit,
Functions
activate(object:Hash):Matrix4deactivate():Matrix4force_update(object:Hash)get_viewport(object:Hash): LuaMultiReturn<[ number, number, number, number ]>get_view(object:Hash):Matrix4get_projection(object:Hash):Matrix4get_frustum(object:Hash):Matrix4get_distance(object:Hash, distance:Vector3, absolute?: boolean):Vector3shake(object:Hash, parent: boolean, count: number, duration: number, radius: number, duration_scalar?: number, radius_scalar?: number)cancel_shake(object:Hash, parent?: boolean)screen_to_world(object:Hash, x: number, y: number, visible?: boolean):Vector3| undefinedworld_to_screen(object:Hash, position:Vector3, visible?: boolean):Vector3| undefined
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 torender.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— Returnnilinstead when the position falls outside the camera's view.
Returns
Vector3 | undefined— The world position, ornilifvisiblefiltered 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— Returnnilinstead when the position falls outside the camera's view.
Returns
Vector3 | undefined— The screen position, ornilifvisiblefiltered 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.