PhantomCamera2D

Inherits: Node2D

PhantomCamera2D, shortened to PCam2D (text) and pcam_2d (code), is used in 2D scenes.

PCam2Ds can manually be enabled / disabled by toggling its visibility in the Scene hierarchy panel.

Core Properties

Priority

Determines which PCam2D should be controlling the Camera2D.

Follow Mode

Enables the PCam2D to follow specific target(s) using various logics.

Tween

Determines how the Camera2D should tween to this PCam2D upon becoming active.

Secondary Properties

active

Type: bool

Default: false

Returns true if this PCam is the one controlling the scene's Camera.

---

Getter

bool is_active()

Example

pcam.is_active()

tween_on_load

Type: bool

Default: true

By default, the moment a PCam is instantiated into a scene, and has the highest priority, it will perform its tween transition.

This is most obvious if a PCam has a long duration and is attached to a playable character that can be moved the moment a scene is loaded.

Disabling the Tween on Load property will disable this behaviour and skip the tweening entirely when instantiated.

---

Setter

void set_tween_on_load(bool enable)

Example

pcam.set_tween_on_load(false)

Getter

bool get_tween_on_load()

Example

pcam.get_tween_on_load()

inactive_update_mode

Type: int

Default: 0

Determines how often an inactive PCam should update its positional and rotational values. This is meant to reduce the amount of calculations inactive PCams are doing when idling to improve performance. The value is based on the enum type InactiveUpdateMode.

Inactive Update Mode	Value
ALWAYS	0
NEVER	1

---

Setter

void set_inactive_update_mode(int update_mode)

Example

pcam.set_inactive_update_mode(InactiveUpdateMode.NEVER)

Getter

int get_inactive_update_mode()

Example

pcam.get_inactive_update_mode()

host_layers

Type: int

Default: 1

Determines which PCamHost this PCam should recognize.

At least one corresponding layer needs to be set on the PCam node for the PCamHost to recognize it.

Note: The layer value uses a bitmask.

Tip

A helper function also exists called set_host_layers_value(), where you can supply a specific layer number and then enable / disable it (see setter example below). Use this if you prefer not having to supply bitmask values.

---

Setter

void set_host_layers(int value)

void set_host_layers_value(int layer, bool enabled)

Example

## Bitmask assignment
pcam.set_host_layers(10) # Enables the 2nd and 4th layer using a bitmask value

## Specific layer change
pcam.set_host_layers_value(4, true) # Enables the 4th layer

Getter

int get_host_layers()

Example

pcam.get_host_layers() # Returns the layer value as a bitmask

tween_resource

Type: PhantomCameraTween

Default: null

The resource that defines how this PCam should be transitioned to.

Can be shared across multiple PCams.

See the Tween page for more details.

---

Setter

void set_tween_resource(PhantomCameraTween tween_resource)

Example

pcam.set_tween_resource(tween_resource)

Getter

PhantomCameraTween get_tween_resource()

Example

pcam.get_tween_resource()

tween_duration

Type: float

Default: 1

Property reference to tween_duration of the PhantomCameraTween.

---

Setter

void set_tween_duration(float value)

Example

pcam.set_tween_duration(value)

Getter

float get_tween_duration()

Example

pcam.get_tween_duration()

tween_transition

Type: int

Default: 0

Property reference to tween_transition of the PhantomCameraTween.

---

Setter

void set_tween_ease(int value)

Example

pcam.set_tween_transition(value)

Getter

float get_tween_transition()

Example

pcam.get_tween_transition()

tween_ease

Type: int

Default: 2

Property reference to tween_ease of the PhantomCameraTween.

---

Setter

void set_tween_ease(int value)

Example

pcam.set_tween_ease(value)

Getter

float get_tween_ease()

Example

pcam.get_tween_ease()

zoom

Type: Vector2

Default: Vector2(1,1)

Applies a zoom amount to the PCam2D, which will override the Zoom property of the Camera2D node.

---

Setter

void set_zoom(Vector2 zoom)

Example

pcam.set_zoom(Vector2(1.5, 1.5))

Getter

Vector2 get_zoom()

Example

pcam.get_zoom()

frame_preview

Type: bool

Default: true

Enables a preview of what the PCam2D will see in the scene. It works identically to how a Camera2D shows which area will be visible during runtime. Likewise, this too will be affected by the Zoom property and the Viewport Width and Viewport Height defined in the Project Settings.

Note: This property is only accessible within the node's inspector panel in the editor.

snap_to_pixel

Type: bool

Default: false

If enabled, will make the Camera2D always snap to whole pixels.

This should be particularly useful in pixel art projects, where assets should always be aligned to the monitor's pixels to avoid unintended stretching.

Note

This is not an intended solution for making a camera pixel perfect. That is a more complex issue to solve.

---

Setter

void set_snap_to_pixel(bool enable)

Example

pcam.set_snap_to_pixel(true)

Getter

bool get_snap_to_pixel()

Example

pcam.get_snap_to_pixel()

draw_limits

Type: bool

Default: false

Shows the Camera2D's built-in limit border. The Camera2D can move around anywhere within it.

Note: This property is only accessible within the node's inspector panel in the editor.

limit_left

Type: int

Default: -10000000

Defines the left side of the Camera2D limit. The camera will not be able to move past this point.

---

Setter

void set_limit_left(int value)

void set_limit(int side, int value)

Example

# Shorthand
pcam.set_limit_left(200)

# General Side setter
pcam.set_limit(SIDE_LEFT, 200)

Getter

int get_limit_left()

int get_limit(int side)

Example

# Shorthand
pcam.get_limit_left()

# General Side getter
pcam.get_limit(SIDE_LEFT)

limit_top

Type: int

Default: -10000000

Defines the top side of the Camera2D limit. The camera will not be able to move past this point.

---

Setter

void set_limit_top(int value)

void set_limit(int side, int value)

Example

# Shorthand
pcam.set_limit_top(200)

# General Side setter
pcam.set_limit(SIDE_TOP, 200)

Getter

int get_limit_top()

int get_limit(int side)

Example

# Shorthand
pcam.get_limit_top()

# General Side getter
pcam.get_limit(SIDE_TOP)

limit_right

Type: int

Default: 10000000

Defines the right side of the Camera2D limit. The camera will not be able to move past this point.

---

Setter

void set_limit_right(int value)

void set_limit(int side, int value)

Example

## Shorthand
pcam.set_limit_right(200)

## General Side setter
pcam.set_limit(SIDE_RIGHT, 200)

Getter

int get_limit_right()

int get_limit(int side)

Example

# Shorthand
pcam.get_limit_right()

# General Side getter
pcam.get_limit(SIDE_RIGHT)

limit_bottom

Type: int

Default: 10000000

Defines the bottom side of the Camera2D limit. The camera will not be able to move past this point.

---

Setter

void set_limit_bottom(int value)

void set_limit(int side, int value)

Example

# Shorthand
pcam.set_limit_bottom(200)

# General Side setter
pcam.set_limit(SIDE_BOTTOM, 200)

Getter

int get_limit_bottom()

int get_limit(int side)

Example

# Shorthand
pcam.get_limit_bottom()

# General Side getter
pcam.get_limit(SIDE_BOTTOM)

limit_target

Type: NodePath

Default: null

Allows for setting either a TileMap / TileMapLayer or CollisionShape2D node to automatically apply a limit size instead of manually adjusting the Left, Top, Right and Left properties.

TileMap / TileMapLayer

The Limit will update after the TileSet of the TileMap / TileMapLayer has changed.

Note: The limit size will only update after closing the TileMap / TileMapLayer editor bottom panel.

CollisionShape2D

The limit will update in realtime as the Shape2D changes its size whilst in the editor.

Note: For performance reasons, resizing the Shape2D while running the game will not change the Limit sides.

---

Setter

void set_limit_target(NodePath target)

Example

# TileMap / TileMapLayer node
pcam.set_limit_target(tile_map_node)

# CollisionShape2D node
pcam.set_limit_target(collision_shape_2d_node)

Getter

NodePath get_limit_target()

Example

pcam.get_limit_target()

limit_margin

Type: Vector4i

Default: Vector4i(0,0,0,0)

Applies an offset to the TileMap / TileMapLayer Limit or Shape2D Limit.

The values go from Left, Top, Right and Bottom.

The values can be either positive or negative, which will decrease and increase the limit size respectively.

---

Setter

void set_limit_margin(Vector4i margin)

Example

pcam.set_limit_margin(Vector4i(200, -200, 200, -200))

Getter

TileMap / TileMapLayer get_limit_margin()

Example

pcam.get_limit_margin()

noise

Type: PhantomCameraNoise2D

Default: null

Applies a noise, or shake, to a Camera2D using the PhantomCameraNoise2D resource. Once set, the noise will run continuously after the tween to the PhantomCamera2D is complete.

---

Setter

void set_noise(PhantomCameraNoise2D value)

Example

pcam.set_noise(noise_resource)

Getter

int get_noise()

Example

pcam.get_noise()

preview_noise

Type: bool

Default: true

If true, will trigger the noise while in the editor.

Useful in cases where you want to temporarily disabled the noise in the editor without removing the resource.

This property has no effect on runtime behaviour.

Note: This property is only accessible within the node's inspector panel in the editor.

noise_emitter_layer

Type: int

Default: 0

Enable a corresponding layer for a PhantomCameraNoiseEmitter2D noise_emitter_layer to make this PhantomCamera2D be affected by it.

Enabling multiple corresponding layers on the same PhantomCamera2D causes no additional effect.

Note: The layer value uses a bitmask.

Tip

A helper function also exists called set_noise_emitter_layer_value(), where you can supply a specific layer number and then enable / disable it (see setter example below). Use this if you prefer not having to supply bitmask values.

---

Setter

void set_noise_emitter_layer(int value)

void set_noise_emitter_layer_value(int layer, bool enabled)

Example

## Bitmask assignment
pcam.set_noise_emitter_layer(10) # Enables the 2nd and 4th layer using a bitmask value

## Specific layer change
pcam.set_noise_emitter_layer_value(4, true) # Enables the 4th layer

Getter

int get_noise_emitter_layer()

Example

pcam.get_noise_emitter_layer() # Returns the layer value as a bitmask

Methods

void emit_noise (Transform2D transform)

Emits a noise based on a custom Transform2D value.

Use this function if you wish to make use of external noise patterns from, for example, other addons.

Example

pcam.emit_noise(transform_value)

void teleport_position

Teleports the PhantomCamera2D to their designated position, bypassing the damping process.

Example

pcam.teleport_position()

Signals

became_active ()

Emitted when the PCam becomes active.

became_inactive ()

Emitted when the PCam becomes inactive.

dead_zone_changed ()

Emitted when the dead zone changes when in Framed Follow mode.

dead_zone_reached ()

Emitted when a target touches the edge of the dead zone in Framed Follow mode.

follow_target_changed ()

Emitted when the follow target changes.

is_tweening ()

Emitted when the Camera is being tweened.

tween_started ()

Emitted when the Camera starts to tween to the PCam.

tween_interrupted (Node pcam)

Emitted when the tween is interrupted due to another PCam becoming active.

The argument is the PCam that interrupted the tween.

tween_completed ()

Emitted when the Camera completes its tween to the PCam.