Camera 2D

2D Camera viewport controller supporting target tracking, zoom levels, rotation, and screen offsets.

Type: CameraNode · Category: Core & 2D · Also found as: camera

Properties

Property	Type	Default	Description
isCurrent	boolean	true	The camera the game renders through (one per scene).
followMode	enum: Static, SingleTarget, MultiTarget, Manual	SingleTarget	Static: stays put. Single Target: follows its Follow Target. Multi Target: frames all targets. Manual: moved by scripts.
dragType	enum: None, SmoothDamp, SpringDamp, LookAhead, AutoSpeed	SmoothDamp	How the camera catches up with its target: none (locked), smooth damp, spring, look-ahead (leads by the target’s velocity) or auto speed.
targetPosition	vec2	(0, 0)	Where the camera is heading (world px).
currentPosition	vec2	(0, 0)	Where the camera is now (world px). Runtime state: read-only, not saved.
smoothDrag	boolean	true	Ease towards the target instead of snapping.
smoothDragSpeed	vec2	(0.2, 0.2)	Smooth-damp time per axis (s): higher lags more.
springConstant	number	15	Spring Damp: stiffness pulling the camera to the target. Range 1 to 100.
dampingRatio	number	1	Spring Damp: 1 settles without overshoot, lower wobbles. Range 0.1 to 5.
predictionTime	vec2	(0.5, 0.5)	Look Ahead: how far ahead of the target to aim, in seconds of its velocity.
maxDistance	vec2	(100000, 100000)	Reserved (not used yet).
offset	vec2	(0, 0)	Added to the target position (world px).
smoothOffset	boolean	true	Ease offset changes in.
smoothOffsetSpeed	number	0.2	How fast offset changes ease in. Range 0.1 to 20.
screenOffset	vec2	(640, 360)	Where on screen the camera’s position appears (px; half the window = centred).
currentRotation	number	0	The camera’s rotation now (degrees). Range -360 to 360. Runtime state: read-only, not saved.
targetRotation	number	0	Rotation the camera turns to (degrees). Range -360 to 360.
allowRotation	boolean	true	Let the camera rotate (else it stays upright).
smoothRotation	boolean	true	Ease rotation changes in.
smoothRotationSpeed	number	0.2	How fast rotation eases in. Range 0.1 to 20.
zoom	number	1	Zoom now (1 = 100%, 2 = everything twice as big). Range 0.01 to 50.
targetZoom	number	1	Zoom the camera eases to. Range 0.01 to 50.
smoothZoom	boolean	true	Ease zoom changes in.
smoothZoomSpeed	number	0.2	How fast zoom eases in. Range 0.1 to 20.
minZoom	number	0.1	Smallest zoom (auto zoom and scripts). Range 0.01 to 10.
maxZoom	number	10	Largest zoom (auto zoom and scripts). Range 0.1 to 50.
autoZoom	boolean	true	Multi Target: zoom out to keep every target on screen.
zoomMargin	number	0.1	Auto zoom: extra space around the targets (0.1 = 10%). Range 0 to 1.
hasLimits	boolean	false	Keep the view inside the left / right / top / bottom limits.
smoothLimit	boolean	true	Ease into the limits instead of stopping hard.
leftLimit	number	-1000000	Left edge the view may not pass (world px).
rightLimit	number	1000000	Right edge the view may not pass (world px).
topLimit	number	-1000000	Top edge the view may not pass (world px).
bottomLimit	number	1000000	Bottom edge the view may not pass (world px).
useHMargins	boolean	false	Dead zone: the target moves freely between the left / right margins before the camera follows.
useVMargins	boolean	false	Dead zone: the target moves freely between the top / bottom margins before the camera follows.
leftMargin	number	0.25	Left dead-zone margin (fraction of the screen). Range 0 to 0.5.
rightMargin	number	0.25	Right dead-zone margin (fraction of the screen). Range 0 to 0.5.
topMargin	number	0.25	Top dead-zone margin (fraction of the screen). Range 0 to 0.5.
bottomMargin	number	0.25	Bottom dead-zone margin (fraction of the screen). Range 0 to 0.5.
enableMouseFollow	boolean	false	Nudge the camera towards the mouse.
mouseInfluence	vec2	(0.2, 0.2)	How much the mouse pulls the camera per axis (0-1).
shakePreset	enum: Custom, Gunshot, Earthquake, Handheld, Explosion, Impact, Rumble, Vibration, Wobbly	Custom	Ready-made shake (gunshot, earthquake…); Custom uses the settings below.
shakeTypes	flags: Vertical, Horizontal, Random, Perlin, Rotate, Circular, Zoom	[Vertical, Horizontal, Random]	Custom shake: which motions combine.
isShaking	boolean	false	A shake is running. Runtime state: read-only, not saved.
shakeSpeed	number	15	Custom shake: how fast it shakes.
shakeIntensity	number	10	Custom shake: how far it moves (px).
shakeTrauma	number	1	Shake strength now (0-1); decays over time.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

CameraNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("isCurrent")

• path CameraNodeProperty|string

Returns any

CameraNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("isCurrent", true)

• path CameraNodeProperty|string
• value any
• y? number

CameraNode:camera_set_zoom(zoom)

Sets the zoom level on this CameraNode.

local cam = Scene.find_node("MainCamera"); cam:camera_set_zoom(2.0)

• zoom number

CameraNode:camera_get_zoom()

Gets the configured zoom level on this CameraNode.

local cam = Scene.find_node("MainCamera"); cam:camera_set_zoom(cam:camera_get_zoom() * 1.1)

Returns number

CameraNode:camera_set_target(target)

Sets the target Node to follow.

local cam = Scene.find_node("MainCamera"); cam:camera_set_target(Scene.find_node("Player"))

• target Node?

CameraNode:camera_add_target(target, options)

Adds a node to the group this camera frames (see Camera.add_target).

local cam = Scene.find_node("MainCamera"); cam:camera_add_target(Scene.find_node("Boss"), {weight = 2})

• target Node
• options? CameraTargetOptions

CameraNode:camera_remove_target(target)

Takes a node out of this camera’s group.

local cam = Scene.find_node("MainCamera"); cam:camera_remove_target(Scene.find_node("Boss"))

• target Node

CameraNode:camera_clear_targets()

Stops this camera following anything.

local cam = Scene.find_node("MainCamera"); cam:camera_clear_targets()

CameraNode:camera_get_target()

The node this camera follows (single target), or nil.

local cam = Scene.find_node("MainCamera"); local target = cam:camera_get_target()

Returns Node?

CameraNode:camera_get_targets()

Every node this camera follows.

local cam = Scene.find_node("MainCamera"); for _, t in ipairs(cam:camera_get_targets()) do Log.info(t.name) end

Returns Node[]

CameraNode:camera_set_target_position(x, y)

Sets the fixed world position for the camera target.

local cam = Scene.find_node("MainCamera"); cam:camera_set_target_position(640, 360)

• x number
• y number

CameraNode:camera_shake(strength, duration)

Triggers trauma screen shake on this CameraNode.

local cam = Scene.find_node("MainCamera"); cam:camera_shake(0.6, 0.3)

• strength number Shake intensity (0.0 to 1.0)
• duration? number Duration in seconds (default 0.5)

CameraNode:camera_stop_shake()

Immediately cancels any active screen shake.

local cam = Scene.find_node("MainCamera"); cam:camera_stop_shake()

CameraNode:camera_is_shaking()

Checks if screen shake is currently active.

local cam = Scene.find_node("MainCamera"); if not cam:camera_is_shaking() then cam:camera_shake(0.4) end

Returns boolean

CameraNode:camera_set_limits(left, right, top, bottom)

Constrains camera movement within bounding rectangle limits.

local cam = Scene.find_node("MainCamera"); cam:camera_set_limits(0, 2560, 0, 720)

• left number
• right number
• top number
• bottom number

CameraNode:camera_clear_limits()

Clears all bounding rectangle limits.

local cam = Scene.find_node("MainCamera"); cam:camera_clear_limits()

In a scene file

{
  "type": "CameraNode",
  "name": "Camera2D",
  "position": [
    0,
    0
  ],
  "properties": {
    "isCurrent": true,
    "followMode": "SingleTarget",
    "dragType": "SmoothDamp"
  }
}