Phantom Camera
PhantomCamera3D
Inherits: Node3D
PhantomCamera3D, shortened to PCam3D (text) and pcam_3d (code), is used in 3D scenes.
PCam3Ds can manually be enabled / disabled by toggling its visibility in the Scene hierarchy panel.
Core Properties
Follow Mode
Enables the PCam3D to follow specific target(s) using various logics.
Look At Mode
Enables the PCam3D to look at specific node(s), effectively adjusting its rotational value.
Secondary Properties
active
Type: bool
Default: false
Returns true if this PCam is the one controlling the scene's Camera.
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.
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)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 layerGetter
int get_host_layers()
Example
pcam.get_host_layers() # Returns the layer value as a bitmasktween_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)tween_duration
Type: float
Default: 1
Property reference to tween_duration of the PhantomCameraTween.
tween_transition
Type: int
Default: 0
Property reference to tween_transition of the PhantomCameraTween.
camera_3d_resource
Type: Camera3DResource
Default: null
A resource type that allows for overriding the Camera3D node's properties.
See the Camera3DResource page for more details.
Setter
void set_camera_3d_resource(Camera3DResource resource)
Example
pcam.set_camera_3d_resource(resource)keep_aspect
Type: int
Default: 1
Property reference to keep_aspect property of the Camera3DResource.
Setter
void set_keep_aspect(int value)
Example
# Applies KEEP_WIDTH values
pcam.set_keep_aspect(0)
# Alternatively, use the enum value
pcam.set_keep_aspect(Camera3DResource.KeepAspect.KEEP_WIDTH)cull_mask
Type: int
Default: 1048575
Property reference to cull_mask property of the Camera3DResource.
frustum_offset
Type: Vector2
Default: Vector2(0, 0, 0)
Property reference to frustum_offset property of the Camera3DResource.
attributes
Type: CameraAttributes
Default: null
Allows for setting and dynamically tweening between CameraAttribute resources for each PCam3D. Used to enable and transition between things like depth-of-field, i.e. camera blur, and camera light exposure.
Important
If a CameraAttribute resource is already applied to a Camera3D node, then adding one to a PCam3D will automatically override it once that PCam3D becomes active.
Again, using an Attribute resource on the PCam3D should be intended as a means of dynamically switching between different resources for tweens. In other words, if a project, or scene, only needs one CameraAttribute resource, then consider using a WorldEnvironemnt node or apply it directly to Camera3D node instead.
Important
Aside from a few exposure properties, any tweening between different CameraAttribute resources will only occur if the types are the same. So for best results, stick to using just CameraAttributePractical or CameraAttributePhysical.
Important
If applying a CameraAttribute resource to a PCam3D, then the Camera3D will retain the most recently applied one if the consequent active PCam3Ds have no CameraAttribute applied. So if you want to move away from a current CameraAttribute setting, or reset it to default values, you would need to have another, active, PCam3D with another CameraAttribute resource with the desired changes / defaults.
environment
Type: Environment
Default: null
Allows for setting a Environment resources for individual PCam3Ds. The properties of this resource will not be tweened between each PCam3D that has resource.
Important
Only consider using this if there is a desire to change the environment variable per PCam3D instance. Otherwise, consider using a WorldEnvironemnt node or apply it directly to Camera3D node instead.
noise
Type: PhantomCameraNoise3D
Default: null
Applies a noise, or shake, to a Camera3D using the PhantomCameraNoise2D resource. Once set, the noise will run continuously after the tween to the PhantomCamera3D is complete.
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 PhantomCameraNoiseEmitter3D noise_emitter_layer to make this PhantomCamera3D be affected by it.
Enabling multiple corresponding layers on the same PhantomCamera3D 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 layerGetter
int get_noise_emitter_layer()
Example
pcam.get_noise_emitter_layer() # Returns the layer value as a bitmaskMethods
void emit_noise (Transform3D transform)
Emits a noise based on a custom Transform3D 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 PhantomCamera3D and Camera3D 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.
look_at_target_changed ()
Emitted when look_at_target changes.
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.
Editor-only
Align with View
Positions and rotates the PCam3D to match the 3D viewport's camera transform.
They are visible depending on if the PCam3D is following or looking at a target(s); e.g. if a PCam3D is following a target, then only Align Rotation with View will be available as the position will instantly be overridden.
The buttons can be found in Align with View submenu nested within the Editor property inspector group of the PCam3D node.
viewport_index
Type: int
Default: 0
Changes which viewport the alignment buttons should be based on - ranging from 0 to 3. If you are only using 1 editor viewport, keep the default value to 0.
Note: This property is only accessible within the node's inspector panel in the editor.
Target Gizmo Line
Draws a gizmo line between a PCam3D and its Follow / Look At target. If no target has been set, no line(s) will appear.
This can be toggled on / off (default) from the Gizmo Line submenu inside the Editor property inspector group of the PCam3D node.
Line color definition:
Red = Following
Blue = Looking At
Note
A Follow Mode or Look At Mode needs to be set for the corresponding toggles to appear in the inspector.
Important
The lines will not be visible at runtime.
draw_follow_line
Type: bool
Default: false
Draws a line between the PCam3D and the target position it is following.
Note: This property is only accessible within the node's inspector panel in the editor.
draw_look_at_line
Type: bool
Default: false
Draws a line between the PCam3D and the target position it is looking at.
Note: This property is only accessible within the node's inspector panel in the editor.