Advanced Camera

A virtual camera (Phantom Camera style): follow modes (glued, damped with look-ahead, group with auto-zoom, path, dead zone), limits incl. the LDtk level the target is in, trauma shake. The highest priority one is shown; switching blends.

Type: AdvancedCameraNode · Category: Core & 2D · Also found as: advanced camera, virtual camera, phantom, cinemachine

Properties

Property	Type	Default	Description
priority	integer	0	The host camera shows the enabled advanced camera with the highest priority (a tie: the one added last); raise it to switch. Range -100 to 100.
followMode	enum: None, Glued, Simple, Group, Path, Framed	Simple	None (stays where placed), Glued (exactly on the target), Simple (offset, damping, look-ahead), Group (frames all targets, auto-zoom), Path (on a PathNode, closest to the target), Framed (moves only when the target leaves the dead zone).
followTarget	string	""	The node it follows (a path like Player or ../Hero).
followTargets	string	""	Group: more nodes to frame, comma separated.
followPath	string	""	Path: the PathNode the camera rides along.
followOffset	vec2	(0, 0)	Added to the target’s position (px). Range -2000 to 2000.
damping	number	0	Smoothing time in seconds: 0 locks on, 0.2-0.5 feels smooth. Range 0 to 5.
axisLock	enum: None, X, Y, XY	None	Don’t follow along these axes (e.g. Y for a side-scroller that never moves vertically).
lookahead	number	0	Looks ahead of a moving target by this many seconds of its velocity. Range 0 to 2.
deadZone	vec2	(0.3, 0.3)	Framed: the part of the view (fraction of width / height) the target can move in without the camera moving. Range 0 to 1.
zoom	number	1	Zoom (2 = twice as close). Range 0.05 to 20.
autoZoom	boolean	false	Group: zoom so every target fits, between Auto Zoom Min and Max.
autoZoomMin	number	0.25	Group auto zoom: farthest out. Range 0.05 to 20.
autoZoomMax	number	2	Group auto zoom: closest in. Range 0.05 to 20.
autoZoomMargin	number	120	Group auto zoom: space kept around the targets (px). Range 0 to 2000.
limitMode	enum: None, Rect, Node, LdtkLevel	None	Keeps the view inside: None, Rect (Limit Rect), Node (a TileMap / LDtk level / Navigation Region / StaticBody’s bounds), Ldtk Level (the LDtk level the target is in - changes as it walks into linked levels).
limitNode	string	""	Node limits: the node whose bounds the view stays in.
limitMargin	number	0	Shrinks (+) or grows (-) the limits (px). Range -500 to 500.
limitBlend	number	0.4	Seconds to glide to new limits (moving into another LDtk level); 0 = at once. Range 0 to 5.
blendTime	number	0.8	Seconds the host takes to move from the previous camera to this one when it becomes active. Range 0 to 10.
blendEase	enum: Linear, In_Sine, Out_Sine, In_Out_Sine, In_Quad, Out_Quad, In_Out_Quad, In_Cubic, Out_Cubic, In_Out_Cubic, In_Quart, Out_Quart …	In_Out_Sine	The easing of that blend.
snapToPixel	boolean	false	Round the position to whole pixels (pixel art).
shakeIntensity	number	24	Shake offset at full trauma (px). Range 0 to 500.
shakeRotation	number	2	Shake rotation at full trauma (degrees). Range 0 to 45.
shakeDecay	number	1.5	Trauma lost per second. Range 0 to 20.
shakeFrequency	number	12	How fast the shake moves (noise speed). Range 0.1 to 100.
traumaExponent	number	2	Shake = trauma ^ exponent: 2-3 makes small hits subtle and big ones strong. Range 1 to 4.
trauma	number	0	Current trauma 0..1 (add_trauma stacks it; runtime). Runtime state: read-only, not saved.
active	boolean	false	The host camera shows this one now (runtime, read-only). Runtime state: read-only, not saved.

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.

AdvancedCameraNode:connect(event, handler)

Connects a handler to one of this node’s events: became_active (The host camera switched to this advanced camera), became_inactive (Another advanced camera took over); the tree events; custom ones.

self.node:connect("became_active", function(value, source) Log.info("became_active") end)

• event AdvancedCameraNodeEvent|string
• handler fun(value: any, source: AdvancedCameraNode)

Returns integer id Connection id for disconnect

AdvancedCameraNode: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("priority")

• path AdvancedCameraNodeProperty|string

Returns any

AdvancedCameraNode: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("priority", 2)

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

AdvancedCameraNode:add_trauma(amount)

Adds shake trauma (stacks up to 1, decays by Shake Decay per second).

cam:add_trauma(0.4)  -- a hit

• amount number 0..1

AdvancedCameraNode:make_active()

Raises its priority above every other advanced camera: the host blends to it.

Scene.find_node("BossCam"):make_active()

AdvancedCameraNode:is_active()

The scene’s camera shows this one now.

if cam:is_active() then hud:show_hint() end

Returns boolean

AdvancedCameraNode:snap()

Jumps to where it wants to be now (no damping; ends the blend if active) - after a teleport.

player.position = spawn; cam:snap()

In a scene file

{
  "type": "AdvancedCameraNode",
  "name": "AdvancedCamera",
  "position": [
    0,
    0
  ],
  "properties": {
    "priority": 0,
    "followMode": "Simple",
    "followTarget": ""
  }
}