v0.7

❗ Breaking Changes

Note

The breaking changes in this release are a one-time thing.
It's a combined number of system changes that needed to happen at some point, and so it was decided to do it in one go rather than over the course of multiple releases.

Important

Always be sure to have your current changes commited to source control before updating to avoid losing work.

Godot 4.2 Minimum Requirement

This release, specifically the property change, further down the page, relies on changes that were only released in Godot 4.2. As such, it will now only be compatible with that and future versions of Godot.

Addon Filename Consolidation & Dependency Errors

A lot of the addon's filenames have been changed to align with a general snake_case naming convention, but as a result will likely run into an error on start-up that looks like this:

If you're well-versed with Godot, then this should be a relatively simple thing to resolve, but if you're unsure how to solve this, follow the steps below.

Tip

After doing the steps below, if you're running into an issue where the editor will constantly say that it can't find Phantom Camera scripts, then it's likely due to there being a cached reference to the previous file inside .godot directory. To solve that, try and delete the entire .godot directory. It will be repopulate itself once you reopen the project.

Fixing Missing Dependencies

Revamped Property System

This is mainly an under-the-hood change and will only impact existing users of the addon.

TLDR

• All the property variables have changed from using _property_list to @export.
• For existing users, a lot of property names have changed as a result, which will break, or more precisely reset, existing setups.
  • See the end of the section for a mitigation guide.

Why the change?

The shift to @export was always planned, but for a later release — initial thinking was for v1.0. The reason it is being introduced now is due to a project export bug (#164), where an important feature didn't consistently work when exporting a project — despite working consistently in the editor. Suffice to say, that's a pretty big problem. From some initial tests, this issue did not occur when using the aforementioned @export approach. So the decision was made to make the jump sooner than originally planned. So far, the issue has yet to reappear.

The change was also meant to coincide with a better editor experience, as @export allows for supporting inspector property tooltips (#55) as well as an in-editor documentation page for all the addon's public node properties, functions, and signals (#168).

From a development perspective, the change also greatly simplifies the process of adding, removing and debugging properties, which in turn reduces the code complexity and time spent testing new and old features.

Why was @export not used from the beginning?

The addon has been in the worked since before Godot 4 was fully released. Not until Godot 4.2 was it possible to dynamically show or hide properties using @export. If the addon had used @export from the start, it would have resulted in all the available properties for a given addon node always being displayed. The vast majority of which being both irrelevant and confusing without contextual toggles or modes enabled — awful developer experience, in other words.

One of the changes made here is that property names do not have any nested names, e.g. follow_parameters/target_offset, are now named as a single variable name, e.g. follow_offset.

I have set up a lot already from previous release(s), what can I do to mitigate breaking changes?

Assuming you're using some form of source control, such as Git, the good news is that you can convert the property names manually from the individual scene files (.tscn) directly and keep your existing property values. Below is an example of how I would migrate an existing setup from a pre-0.7 project to be using the new property names from this release. Note that the follow_damping_value property is the exception to this - more in the Important section below.

Mitigation Guide

Once you've updated the addon and opened an existing scene that has PCam2D and PCam3D nodes, their values will have reset - you may have to re-save the scene first. From here, if you want to keep your existing setup, you can look at your source control and compare what values have been changed. In the example below, I've readded a follow_target and damping with random values.

As the image above shows, the names are not changed to be unrecognisable from the previous version. They are different, however, which does mean manual intervention if you wish to migrate the values over. Simply use your text editor of choice and add the values into the .tscn file directly.

Tip

If you're unsure what a property name is called now I would suggest looking it up on the documentation site. It will have all the up-to-date names.

Important

As you may have noticed from the image above, some values have had their type changed in this release too. The only properties this relates to is follow_famping_value. You need to adjust its value according to the new system — see the Improved Follow Damping Logic section further down the page for more info. As the effect of the value have, for all intents and purposes, completed shifted I would recommend doing a test in one scene, feel it out, and reapply values elsewhere based on that observation.

Logic Moved to _process

This might seem insignificant, but it does have a notable impact.
It will likely affect everyone, existing as well as new addon users, so would suggest following the steps in the “What can I do about it?” section further down for how to work with this change.

TLDR

• By default, setting a camera to follow a physics-based node will highly likely result in the followed node being very jittery.
  • Again, see “What can I do about it?” section.
• Nodes that are moving in the _process or uses a Tween animation should no longer be jittery.
• This isn't a complete solution and there is still work to be done.

A big thanks to @P5ina (for the PR) and @Lasuch69 for the discussing and helping with this change.

What was it before?

In previous releases, camera movement has been happening in the _physics_process. This was initially in large part been due to playable characters, what the camera would also typically be assigned to follow, would be a physics-based node such as CharacterBody2D/3D. This meant that as the physics object moved, along with the character asset within the physics object (i.e. sprite / 3D model), the camera followed it relatively evenly as the movement should both be happening in the _physics_process.

Why has this changed?

While having the camera move in the _physics_process meant that following a physic-based node was generally fairly smooth, it did also come with a few, no-trivial, issues.
The arguably biggest issue, was that animations that were being done in the _process, such as anything using the built-in Tween method, would always result in jitter. Either when it was being followed by the camera or were moving while the camera followed something else. Since not everything is, nor should, be moving in _physics_process it highlighted an issue with the previous approach. As things stood, it was deemed not possible to solve while the camera moved in the _physics_process and so it was changed to be occurring in the _process instead.

Why is there suddenly more jitter, or jitter where there was none before?

If you're using a physics object as a follow or look at target, and it's set to move in the _physics_process then you will likely notice jitter right away — even if you apply follow damping.

A typical playable character would then often consistent of a node hierarchy like:

• CharacterBody2D/3D
  • Visual representation, e.g. Sprite2D or a MeshInstance3D
  • CollisionShape2D/3D
  • Other nodes

Assuming a developer had assigned a CharacterBody2D/3D to update in the _physics_process it would previously be running in the same process as the camera. Moving the camera to then run in the _process instead meant that they wouldn't be synchronized and run at different intervals.
The short explanation is that the _physics_process runs at a fixed interval, whereas the _process runs at a dynamic interval based on your framerate. They can sometimes run at a very similar pace, but for all intents and purposes they will not. Godot's documentation has written more on this topic.

In the case of this addon, the core issue here with jitter isn't really that the camera and its target are running in different processes, but rather that the visual representation is.
As its parent, in this example CharacerBody2D/3D, moves in the _physics_process so too does the visual representation that is nested within it. What is needed here is to control when the visual representation moves, rather than being entirely dependent on its parent moving.

What can I do about it?

There are a couple of things you can do to mitigate jitter, which is covered more extensively on the support page on the documentation site.

✨ New Features

Look At Damping

look_at_damping.mp4

PCam3D now supports rotational damping when it has an assigned target in Look At mode. The damping value aligns with the new Follow Damping system, where lower values leads to less damping and vice versa.

2D Viewfinder Support

Previously excluded to 3D scenes, the viewfinder now also supports displaying what a Camera2D sees in 2D scenes.

In-Editor Documentation

Another benefit of the property revamp, and similar to classes in Godot, the addon now has an editor documentation page that describes the available properties, functions, and signals based on the built-in documentation commenting feature. While the documentation website covers that and many other things in greater detail, the inclusion here should help with reading and exploring the available options from within the Godot script editor itself.

⬆️ Changes & Improvements

Improved Follow Damping Logic (Smooth Damp)

improved-follow-damping.mp4

The previous system used a simple linear interpolation (lerp) to move the camera for both 2D and 3D scenes. While it worked fine, it didn't feel like the right approach for the follow movement.

The new system is based on Unity's Smooth Damp, where it now uses a more complex logic that allows for velocity to also affect the camera's follow movement.

The practical difference between the lerp and smooth damp solution can be broken down into:

Lerp	Smooth Damp
Accelerates quickly and slows down as it approaches its target.	Starts slow and accelerates as velocity increases over time before slowing down as it approaches its target.

Smooth damp, in essence, feels more like what an actual camera would move like in real life.

Another addition is that the directional axis can be manually configured with different damping values. E.g. if you want vertical damping to be less than the horizontal, you can supply different values for each. The video above shows an example of this, where the x-axis damping is higher than the z-axis'.

Tip

Value-wise, and unlike the previous approach, lower numbers now means less damping. The ideal amount should be somewhere between 0-1, likely somewhere around 0.1 to 0.25.

Thanks to @voithos for suggesting the code solution and others for chiming in (#92)

Direct Property Assignment

In previous releases, grabbing and setting new property values, like priority, follow target, had to be done with their appropriate getters and setters respectively. Thanks to the property refactor, all properties can now be directly assigned. Setter and getter methods are still valid, of course.

🛠️ Minor Changes

• Added the ability to assign the quaternion value of the SpringArm3D in Third Person Follow mode. Previously limited to only rotation in radians and degrees (#190)
  • Thanks @ZenithStar for the proposal (#171)
• The Inactive Update Mode can now be changed via code, whereas it was previously limited to only be set from the inspector.
• Updated references to editor_interface to use the singleton class, EditorInterface, introduced in Godot 4.2.
• Updated 3D gizmo editor icon. Should have better contrast with the various background colours.
• Renamed Pixel Perfect property to Snap to Pixel, as the previous name incorrectly implied it fully addresses pixel perfection — which is a much tricker problem to solve in reality.
• Renamed PhantomCameraTween enum names to align with the built-in Godot Tween enum names.
• Added dead_zone_changed signal.
• Removed phantom_camera_properties.gd as all properties now live directly in their respective files.
• Fixed UI in the 2D demo scenes. Was appearing too large in recent releases.
• Added look_at_target_changed signal.
• Added resource icon for Camera3DResource.

🐛 Fixes

• An issue with limit nodes not working when exporting a project (#164)
• Fixed export error related to the viewfinder that reports: "Failed to load script "res://addons/phantom_camera/scripts/panel/viewfinder/viewfinder.gd" with error "Parse error". (#181, #164)
• Resolved an error that would occur when assigning a new Tween Ease value via code.
• Resolved an issue where assigning Third Person Follow Mode properties related to the SpringArm3D via code would cause a crash if done so on a PCam3D that wasn't set to Third Person (#257)
  • Thanks @ZenithStar for the pre-release report and PR (#258)