v0.9.3.1

🐛 Fixes

• Resolved an issue where instantiating a scene that contains a PCam with a higher priority than the current one could result in the Camera shifting to that new PCam before it's fully instantiated (#549).
  • Thanks @Jack-023 for raising the issue and @mikest for proposing the solution (#544).

v0.9.3

Warning

This version will now require Godot 4.3 or later to function.

Important

A change in this release will reset the initial rotation in the scene editor of any PCam3D that uses the Third Person follow mode and make the Rotation property in the inspector, under Node3D, no longer function.
Setting the initial rotation in the scene editor is, however, straightfoward and this side-effect comes with some much needed improvements to how the Follow Mode works in general.

See the Vertical & Horizontal Rotational Offset Properties section below for more details.

✨ New Features

PhantomCameraHost Interpolation Mode Override

Note

Unless this has been a problem in your project, there's no need to change this setting.

This allows the user to manually override the internal physics interpolation checker, and define whether if a Camera should always be performing its logic in the _process or _physics_process.

Currently, the addon automatically checks this based on whether if the target is inherited from PhysicsBody2D/3D. In most cases, leaving it on its default Auto and letting the addon decide which to use should work fine, but there are a few cases where you might want to change this; hence this option.

Thanks @danbolt for raising the issue (#535) and PR (#536).

Rotate with Follow Target (2D)

PCam2D can now, optionally, follow the rotation of their follow target (#541).

The feature also includes rotational offset parameter along with rotational damping to offset the rotation and damping the rotation speed respectively.

Thanks @nanodeath for the proposal (#341).

2d-rotate-with-target.mp4

🌟 Improvements

Persistent Third-Person Editor Rotation

Addressing #463, this change allows PCam3D with the Third Person Follow Mode to have a persistent rotation, no matter its target's or world's rotation; it will always look at its target from the same angle that the user has set.

Previously, the PCam3D would not retain its relative position and rotation to its target if it was set up inside a scene that was instantiated and rotated inside another scene. Making a reusable Third Person PCam3D + player scene difficult to set up and use.

Vertical & Horizontal Rotational Offset Properties

As a result of the above change, the rotation property is now being overridden by the addon and is thus no longer possible to be modified through the inspector property when using Third Person Follow. Instead, there's two new added properties; vertical_rotational_offset and horizontal_rotational_offset. Both control the orbit position of the PCam3D while working in the scene view. Once the scene starts, the typical methods of controlling the rotation works as usual.

Thanks @soomr for the report (#463).

rotational-offset.mp4

Linked Property Values

As part of the Godot 4.3 upgrade, a quality-of-life change is that some properties now make use of the PROPERTY_HINT_LINK.
It makes adjusting commonly applied values such as Zoom (2D) or Follow Damping (2D / 3D) easier, where you now only have to adjust one value to change the others in the exposed Vector2 / Vector3 properties.

Thanks @P5ina for the PR (#402).

🐛 Fixes

• Fixed an issue where setting the Follow Mode to Path could trigger a series of errors due to a Path2D/3D not having been assigned yet.

🏅 New Contributors

• @danbolt made their first contribution in #536

v0.9.2

✨ New Features

C# Wrapper

Following the proposal in #286 and thanks to the stellar work from two contributors, Phantom Camera now has an official C# wrapper, which should make using the addon in .cs files feel a lot more native.

Massive kudos to @sircodemane, who initially made a PR for this (#351) and set up the structure, system and wrapper codebase, and @GabCoolDude who worked on top of the existing work and got the feature pushed over the finish line (#512).

Read more, including how to use it, on the documentation page.

🌟 Improvements

• Introduced a pcam_became_active and pcam_became_inactive signal to PCamHost. As the name implies, it's a signal that gets emitted whenever a PCam becomes and ceases to be the active for a given PCamHost node (#527).
  • Thanks @mikest for the suggestion (#524).
• follow_damping is now no longer being applied when dragging nodes in the editor, and now only occurs when the scene is being run. This was changed to avoid slow camera reactions when working in the editor. Adjustments to follow_damping can still be modified during runtime, as to avoid having to relaunch a scene for incremental changes.
• Refactored and greatly simplified the PCam3D gizmo codebase.
• Added an upward direction of the PCam3D gizmo. Should help with identifying the direction of the PCam3D and further mimic the Camera3D frustum appearance.
• Scripts extending PhantomCamera3D will now display the gizmo in the editor (#530).
  • Thanks @mikest for raising the issue (#529).
• Added a is_following() (2D & 3D) and is_looking() (3D) getter functions. Allows for checking whether if a PCam2D/3D has a follow_mode or look_at_mode (3D) enabled and a valid target.

🏅 New Contributors

• @sircodemane made their first contribution in #512 (#351)
• @GabCoolDude made their first contribution in #512

C# Wrapper (Beta)

New Features

C# Wrapper (Beta)

Important

This is a pre-release version of the addon, and so will not be available through the addon's updater until it has been fully released.
So try out this pre-release, download the zip file at the bottom of the release document and extract the addon from it and add it to your project.

Following the proposal in #286 and with the stellar work from two contributors, Phantom Camera now has a C# wrapper, which should make using the addon in C# files feel a lot more native.

Massive thanks to @sircodemane, who initially made a PR for this (#351) and set up pretty much the structure, system and wrapper codebase, and @GabCoolDude who worked on top of the existing work and got the feature pushed over the finish line (#512).

How to use

Note

The documentation will be added to the documentation site once the wrapper has been added to a stable addon release post-beta.

About the wrapper

PCam nodes can be referenced using the PhantomCamera namespace, which then allows for assigning the appropriate types to variables. The property and method names are the same as the GDScript version, but are here Pascal Cased to follow the common C# naming convention.

Note, that due to some technical constraints with how adding a wrapper to custom GDScript declared nodes like PhantomCamera2D and PhantomCameraHost, referencing the addon nodes works a bit differently than one might initially expect.

Example

using Godot;
using PhantomCamera;
using PhantomCamera.Manager;

public partial class MyClassName : Node
{

  private PhantomCamera2D _pcam;
  private PhantomCameraHost _pcamHost;

  public override void _Ready()
  {
    // PhantomCamera reference
    _pcam = GetNode<Node2D>("%PhantomCamera2D").AsPhantomCamera2D();
    _pcam.Priority = 40; // Changes the priority of the PCam to 40

    // PhantomCameraHost reference using the PhantomCameraManager singleton
    _pcamHost = PhantomCameraManager.PhantomCameraHosts[0]; // Fetches the first PCamHost through the PCamManager singleton
    GD.Print(_pcamHost.HostLayers); // Outputs the host_layer value of the PCamHost
  }
}

You may notice the perhaps slightly odd inclusion of .AsPhantomCamera2D() and the usage of <GetNode2D>. What it is doing is essentially casting the Node2D as a PhantomCamera2D class, which allows for referencing the various public properties, methods, and signals available from the PhantomCamera GDScript class. Due to how nodes are registered in Godot with GDScript, we could unfortunately not find a way to avoid this without adding compromises in other areas of the developer experience.

The same approach is also needed for other addon nodes:

_pcam2D = GetNode<Node2D>("PathToNode").AsPhantomCamera2D(); // PhantomCamera2D
_pcam3D = GetNode<Node3D>("PathToNode").AsPhantomCamera3D(); // // PhantomCamera3D
_pcamHost = GetNode<Node>("PathToNode").AsPhantomCameraHost(); // PhantomCameraHost
_pcamNoiseEmitter2D = GetNode<Node2D>("PathToNode").AsPhantomCameraNoiseEmitter2D(); // PhantomCameraNoiseEmitter2D
_pcamNoiseEmitter3D = GetNode<Node3D>("PathToNode").AsPhantomCameraNoiseEmitter3D(); // PhantomCameraNoiseEmitter3D

What this also means, is that to change the properties inherited from the Node2D class, you would need to explicitly reference the Node2D class before getting/setting or calling any methods from it.
For example, to change the visibility of the Node2D property that the _pcam variable above is based on, you can do that with:

_pcam.Node2D.Visible = false; // Sets the Visible property of the Node2D class to false

Bug reports and Feedback

If you spot anything that is missing or not working as intended, please submit an issue.

Questions

If you have any questions about the C# wrapper, feel free to make a sub-post in the GitHub discussion post for this beta release.

v0.9.1.3

🐛 Fixes

• Fixed an issue with follow damping not working for PCam3Ds when Follow Mode is set to Third Person.
  • Thanks @TuulikkiUnelma for the report (#519)

v0.9.1.2

🐛 Fixes

• Resolved a minor issue where the Up related properties in PCam3D nodes were visible in the inspector when Look At Mode was set to None.
• Resolved an issue with teleporting a PCam when starting a scene not working as intended (#515). This PR should also resolve an issue with Framed Follow 2D not following its target when inactive as reported in #395 (thanks @cathairnowhere for raising this).
  • Thanks @eaglesemanation for the report (#510)
• Resolved an issue where using the disable_3d project template export flag would result in a crash. This was due to references to ConvexPolygonShape3D and PhysicsServer3D being used explicitly. These have now changed to string-based references.

v0.9.1.1

🐛 Fixes

• Resolved an issue with output spam occurring when a PCam3D with Look At set is looking directly upward or downward at its target (#507).
  • Thanks @apolesskiy for the report (#497).
• Resolved an issue with PhantomCameraNoiseEmitter2D not working in Godot 4.4 when using physics interpolation (#513).
  • Thanks @xuc1995 for the report (#491).

v0.9.1

✨ New Features

Look At - Up (3D)

• It's now possible to define the Up direction for the PCam3D when Look At Mode is being used. It allows for controlling the upward direction of the Camera using either a Vector3 Up value or a Up Target. Setting a Up Target will make the PCam3D copy the Upward direction of the target, this can be a separate node from the Look At Target. Previously, the up direction was hardcoded to Vector.UP (#501). This should be useful where the upward direction of the camera is changing dynamically such as flight-sims or F-Zero-like projects.
  • Thanks @stevenmraines and @apolesskiy for the suggestion and testing the feature (#498).

🐛 Fixes

• Follow Axis property is now hidden for PCam2D/3D when Follow Mode is set to None.
• Fixed an issue where changing the Follow Offset at runtime when a Follow Axis Lock was applied would stack the Follow Offset value, resulting in a jumpy camera behavior.
  • Thanks @JamesLoyMartin for the report (#499).
• Resolved an issue with the addon not working in exports due to referencing the EditorInterface as a singleton. Has been replaced with Engine.get_singleton(&"EditorInterface") instead.
• Resolved a case where many warnings about the UID for camera_3d_resource.gd not being correct. This would mainly occur when exporting a project.
• Resolved an issue where PCam is being freed mid-process. This could occur when (#504)
  • Thanks @TranquilMarmot for the PR and for identifying the issue.
  • Thanks @salmonmoose for reporting, suggestion and help testing the fix (#504)
  • Thanks @mak448a for reporting the export issue (#503)

v0.9

❗ Breaking Changes

• As part of the added support for multiple PCamHosts in this release, the notion of a PCam having a PCamHost owner has been removed. Meaning, any code that relied on pcam_host_owner will no longer work.

⚠️ Notes

Important

The updater Project Setting for the addon has changed from being checkboxes to a single dropdown menu. This was done in part to simplify the UX and lead to more expected behavior.
If updating from a previous addon version, this setting will reset to its default value; "Updater Window" and "Output log" for end-user and fork projects respectively (documentation). Updater prompts options can still be disabled entirely by changing this setting to Off.

Note

The addon is still compatible down to Godot 4.2, however with the introduction of .uid for script files in Godot 4.4, Godot 4.2 / 4.3 projects will likely see persistent warnings in their output log. While these will not cause any issues, the recommendation is still to upgrade to the latest stable Godot 4.5+ release to avoid these and make the most out of the recent addon features.

✨ New Features

Multi Phantom Camera Host Support

Note

In the vast majority of cases, having multiple PCamHosts is not necessary, and will likely cause more scene complications than be helpful. Using more than one is mainly for use-cases where multiple cameras need to render different at the same time, such as for splitscreen co-op.

Resolving one of the oldest, and most requested, issues (#26), adding multiple PCamHosts, and Camera2D/3D, nodes to a scene is now fully supported (#461).

PCamHost	PCam

Each PCam instance can belong to multiple PcamHosts, where a PCamHost regonises a PCam by its host_layers value. In other words, if a PCamHost has no layers enabled, then it cannot be controlled by a PCam. By default every new instance of PCam and PCamHost will be on the same layer.

As a result of these changes, each PCam no longer belongs to or communicates with any specific PCamHost. Instead, PCams now relies on signal buses via the PCamManager singleton.

Phantom Camera Host List

The moment two or more PCamHosts are in a given scene, a small button will appear in the bottom left of the Phantom Camera editor panel. Pressing on the icon, will open a list that displays all the PCamHost instances in the scene. Each list item contains two buttons; a small select icon, which will select the given PCamHost from the Scene Hierarchy, and a bigger button that will swap the Viewfinder to display the output of that Camera2D/3D that PCamHost belongs to.

🛠️ Improvements

• Removed usage of node_added and node_removed signals and replaced with Phantom Camera Manager event bus signals in the viewfinder script. Previously caused numerous internal calls to be triggered whenever a node was added to a scene, whereas the new approach is only called as needed.
• Made addon Project Settings options, i.e., Updater and Tips, visible when Advanced Settings is disabled. Should make it easier to find and access without having to make many other settings visible.
• Added a teleport_position function to PCam2D and PCam3D. It allows for jumping the camera to the target's position, bypassing any damping movement (#495).

🔀 Changes

• Look At Mimic now uses global_basis instead of basis (#475).
  • Thanks @BitiLope for the suggestion (#459).
• Follow Axis Lock now allows for changes to the Follow Offset axis that is being locked at runtime. Note: Be mindful that changes to the offset can make the camera jump to an undesired position when disabling Follow Lock Axis (#476).
  • Thanks @Trashdaw for the suggestion (#471).
• frame_preview property in PCam2D is no longer disabled when that PCam2D is active. For context, this is the green outline in the viewport that shows what a given PCam2D will see once active. The preview will still be invisible when a PCam2D is active, and so this change is to allow for setting whether if that PCam2D should display the preview once inactive. Previously, the PCam2D had to be inactive to modify this property.
• Changed Updateroptions in Project Setting to be a dropdown list instead of separate checkboxes. This should simplify this setting — particularly for non-forked versions of the addon. Example can be seen on the documentation site.
• Added an output warning when setting both a Follow Mode and Look Mode to be anything but None on the same PCam3D node, stating that the usage of the two modes together has yet to be thoroughly tested (#489).
  • Thanks @CentiGames for the suggestion (#450).
• Camera3DResource has received an under-the-hood refactor:
  • Previously, when a PCam3D had this resource assigned, it would set the resource values to the Camera3D for every process tick while in the editor; at runtime it would only change when the properties were changed. This was to prevent users from accidentally making the Camera3D node out of sync with the Camera3DResource overrides while working in the editor. Now, the Camera3D properties will only ever change whenever the Camera3DResource properties are changed; both during runtime and in the editor. New safeguards have been in place to prevent direct changes to the Camera3D's properties from happening if an active PCam3D with the resource should override it.
  • Keep Aspect property has been added to the resource.
  • h_offset and v_offset values can now both be above 1 and less than 0.
    • Thanks @TheDrewlander for the suggestion (#494).

🐛 Fixed

• If the editor is opened while the viewfinder was opened in the previous session, it will now display the camera view correctly. Previously, it needed to be closed and opened manually to function properly.
• Fixed an issue where follow_offset was not being applied to PCam2D when it was in the Group Follow.
• Fixed an issue where setting Auto Zoom to a PCam2D in Group Follow and then changing the editor viewport size would change the camera viewport size as well. The camera viewport size is now based on the width and height defined in Project Settings / Display / Window / Size. The sizes defined in the Project Settings only affect the editor viewport here; running the game will adapt to the given viewport size the game window is using.
• Fixed an issue where having only one follow target in Group Follow with Auto Distance enabled used the follow_distance value to set its distance between the single target and the camera. This has now been changed so that the auto_follow_distance_min is now being used instead (#484).
  • Thanks @namelessvoid for raising the issue (#473).
• Fixed an issue where PCam2D wouldn't resize frame size when the viewport changes during runtime. This issue was mainly present when working with the limit feature and having resized the viewport when the scene is running (#485).
  • Thanks @francogp for raising the issue (#480).
• Resolved an issue for PCam3D where referencing a Camera3DResource values from a PCam3D that does not have such resource applied would result in a runtime error. More importantly, this issue also presented itself if one tried to use the Godot debugger in a script that had a reference to a PhantomCamera3D class (#488).
  • Thanks @laurentsenta for raising the issue (#487).
• Resolved an issue with Third Person Follow where moving the cursor erratically upon starting a scene could lead to the camera being tilted.
  • Thanks @StaleLoafOfBread for the report (#347).

v0.8.2.3

🐛 Fixes

• Resolved an unintended crash when closing the editor. This resulted in some editor features like Reload Current Project not working correctly. The issue was caused by the Phantom Camera Manager singleton being automatically freed before Phantom Camera scene nodes, who reference the manager whenever they are freed (#389).
  • Thanks @imberny for the PR (#457)