Skip to content

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

image alt

Priority

Determines which PCam2D should be controlling the Camera2D.

image alt

Follow Mode

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

image alt

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
gdscript
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
gdscript
pcam.set_tween_on_load(false)

Getter

bool get_tween_on_load()

Example
gdscript
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 ModeValue
ALWAYS0
NEVER1

Setter

void set_inactive_update_mode(int update_mode)

Example
gdscript
pcam.set_inactive_update_mode(InactiveUpdateMode.NEVER)

Getter

int get_inactive_update_mode()

Example
gdscript
pcam.get_inactive_update_mode()

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
gdscript
pcam.set_tween_resource(tween_resource)

Getter

PhantomCameraTween get_tween_resource()

Example
gdscript
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
gdscript
pcam.set_tween_duration(value)

Getter

float get_tween_duration()

Example
gdscript
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
gdscript
pcam.set_tween_transition(value)

Getter

float get_tween_transition()

Example
gdscript
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
gdscript
pcam.set_tween_ease(value)

Getter

float get_tween_ease()

Example
gdscript
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
gdscript
pcam.set_zoom(Vector2(1.5, 1.5))

Getter

Vector2 get_zoom()

Example
gdscript
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
gdscript
pcam.set_snap_to_pixel(true)

Getter

bool get_snap_to_pixel()

Example
gdscript
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
gdscript
# 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
gdscript
# 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
gdscript
# 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
gdscript
# 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
gdscript
## 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
gdscript
# 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
gdscript
# 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
gdscript
# 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
gdscript
# 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
gdscript
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
gdscript
pcam.set_limit_margin(Vector4i(200, -200, 200, -200))

Getter

TileMap / TileMapLayer get_limit_margin()

Example
gdscript
pcam.get_limit_margin()

noise

Type: PhantomCameraNoise2D

Default: null

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


Setter

void set_noise(PhantomCameraNoise2D value)

Example
gdscript
pcam.set_noise(noise_resource)

Getter

int get_noise()

Example
gdscript
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.

Note: The value used for this is a bitmask, for improved usability, a helper setter function is also available.


Setter

void set_noise_emitter_layer(int value)

void set_noise_emitter_layer_value(int layer, bool enabled)

Example
gdscript
## Bitmask assignment
pcam.get_noise_emitter_layer(16)

## Specific layer change
pcam.set_noise_emitter_layer_value(2, true)

Getter

int get_noise_emitter_layer()

Example
gdscript
pcam.get_noise_emitter_layer()

Methods

emit_noise

Type: Transform2D

Default: Transform2D()

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.


Setter

void emit_noise(Transform2D value)

Example
gdscript
pcam.emit_noise(transform_value)

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 (PhantomCamera: 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.