Move dampening logic into PhantomCameraHost

[ZenithStar]

With the jitter introduced in moving from _physics_process to _process, I believe there needs to be a refactor moving dampening logic out of PhantomCamera2D/PhantomCamera3D and into PhantomCameraHost. This is where the tweening logic already is. Dampening parameters can still be associated with each PhantomCamera and read in by PhantomCameraHost in the same way that PhantomCameraTween parameters are currently. PhantomCamera nodes should act as the "setpoint" or the "model" that can be updated asynchronously or during a timestep of the user's choosing, similar to AnimationMixer.callback_mode_process, while Camera3D/Camera2D nodes should act as the "view" and always update in the _process/IDLE timestep.

In addition, all dampening parameters should always be exposed, possibly as a resource similar to PhantomCameraTween and with multiple dampening schemes. In the current system, the typical use-case for FollowMode.THIRD_PERSON doesn't allow for LookAt dampening to be used, because orientation is being set by user input, rather than LookAtMode logic. As for multiple dampening schemes, class_name PhantomCameraDampener3D extends Resource can provide an interface like func _dampen(input: Transform3D, delta: float) -> Transform3D and individual dampener implementations class_name PhantomCameraSmoothDamp3D extends PhantomCameraDampener3D can override this interface. (2D and 3D dampener logic will need to be separated.)

[ZenithStar]

In addition, the same goes for when implementing the camera shake feature. Offsets resulting from an impulse should only affect the change in transform for the Camera3D+PhantomCameraHost. The PhantomCameras should only contain the data for the impulse(s), possibly as class_name PhantomCameraImpulse extends RefCounted, with its transform unaffected.

[ramokz]

Jitter will gradually be mitigated as Godot introduces physics interpolation to 2D and 3D — only 2D is close to being officially supported. There's a longer discussion about this in #241 and a PR for 2D Physics interpolation in #294, which is pending changes in the dev branch for Godot 4.3 before being released. The current implementation is a necessary compromise until Godot implements those two feature variants, as it doesn't impede non-physics animations from being jittery.

The system was originally damping the movement in the PCamHost script, i.e. applying it directly to the Camera2D/3D, but was changed for a couple of reasons:

1. If you apply the damping to the Camera node directly, it can lead to tweens behaving in a weird, mechanical and, likely, undesirable manner.
   Say if the Camera, with a PCamHost, is currently attached to and follows a PCam. The Camera then updates its position based on its assigned PCam's position and then applies damping on itself on top of it — in other words, it's dragging behind the PCam. It then becomes a question of where should the camera tween to if the next PCam has a moving follow target with follow damping applied. If a tween gets triggered, it would first stop following its current target, like how it currently works, and then transition towards the newly active PCam, which is where the complication appears. The Camera would move towards where that new active PCam is based on its tween duration and transition properties. But if that new PCam has following damping set, then the tween's target is set to be precisely where it's follow target, and follow offset if applied, is because the damping isn't factored into the PCam's position. The issue with that is the moment the tween finishes, the camera would then start dragging behind, rather than tween towards a target position that already is dragging behind its target, i.e. the dampened position, to begin with. To me, that felt like a less seamless and more awkward outcome. It can't really apply both a tween with a specific duration and have damping applied at the same time, as the latter would interfere with the speed / animation ease of the tween. So it would result in a fairly abrupt transition from a tween finishing to then applying damping if applied directly to the Camera node.

2. For Third Person follow, the issue I see with having the damping applied to the Camera, or PCam3D for that matter, instead of the SpringArm3D is that it means updating the rotation would automatically apply damping without the user explicitly declaring that. Since if you rotate the SpringArm3D by using one of the Third Person rotation methods, it will also change the PCam's position, with it being a child of the SpringArm3D. Because the position changes, it will then apply damping to the camera, which means that the user has less control over how the rotation behaves as follow damping now directly interferes with it.

3. To the point about the shake/noise, there is a work-in-progress branch that has an early, but functional, implementation of this mechanic, which does apply the camera noise/shake to the Camera2D/Camera3D directly. The approach here is done for the same reasons you mention. Like with the first point, if damping was happening on the camera directly, it would mean that the shake has to effectively ignore the damping if both needed to occur at the same time. For Camera2D, this is less of an issue since it uses the Offset property, making it not reliant on any positional changes, but creating camera noise for the Camera3D is a bit more complicated. Like with its 2D counterpart, it has a V/H Offset, but conversely the shake doesn't need to just apply a positional change, but rather positional and rotational. The positional changes also need to support being applied in the z-axis, which rules out relying on the V/H Offset properties, as they don't support any changes in depth. Combine this behaviour with damping, like with the point about tween, it would essentially need to disable the damping since it would otherwise work on top of the noise pattern.

[ramokz]

To be honest, I still don't quite get what the fundamental issue is. I'm not a graphic programmer nor someone with in-depth knowledge of game physics, but I would like to understand what you're trying to explain so that I can see where you're coming from. The state of the way the addon interpolates isn't ideal, I agree. Running it with the changes coming in 4.3, and with the PR mentioned earlier, addresses the core issue I've had since forever with physics framerate affecting the camera movement and switching between moving targets that operate in _process and _physics_process.
What I would like to understand is, what is the practical issue yet to be resolved from that future change?

Is there a particular limitation keeping you from wanting to do this?

In short, time. If an existing feature already fulfils the basics needs, where a more complex overhaul would be desired to satisfy other outcomes, then that becomes a case of managing time vs. the gains of said overhaul. It's very difficult to justify spending a significant amount of time improving a particular follow mode when there are other, more fundamental, improvements to be made.

It's also worth pointing out that nothing prevents someone from making their own system on top of the base addon. The follow modes are ultimately shortcuts to behavioural solutions. One can always make their own follow system and simply make the PCam do what they want in a separate script, much like a normal camera, and keep the other parts of the system. Obviously, the intent of the project is to strip away complexity with setting that up, but equally I think it's difficult to support every possible need. Unlike Cinemachime, this is purely maintained as an outside-of-daily-work project.

[ZenithStar]

I just took a look at how the 3.6 engine physics interpolation is implemented, and it is indeed a far better solution than the smoothing addon. The smoothing add-on is a non-solution as illustrated here:

It's also worth pointing out that nothing prevents someone from making their own system on top of the base addon.

This is the problem right now. All my custom code interfacing to the SpringArm3D motion is tied to the physics rate. Mouse and gamepad inputs are polled at 125Hz which are buffered and read by the 60Hz physics, while my main monitor refreshes at 144Hz. Basically, the solution from my side would need to be to write in 125Hz -> dynamic frame rate interpolation code in order to apply rotations to the spring arm.

With the 3.6/4.3 physics interpolation active, all phantom camera code, including both PhantomCameraHost and PhantomCamera2D/3D would be required to operate in _physics_process. That's fine for when that time comes, but for now, my solution has to be to run on a 60FPS monitor or to change

phantom-camera/addons/phantom_camera/scripts/phantom_camera/phantom_camera_3d.gd

Line 548 in d8a6e24

func _process(delta: float) -> void:

back to func _physics_process(delta: float) -> void:

[ramokz]

Have you had a chance to read the posts in #241?
It discusses the _process vs. _physics_process and what the direction will be.

[ZenithStar]

In the case of 3rd person follow mode, SpringArm3D is inherently a physics object requiring a physics collision check that must happen during a physics tick. In 3rd person follow mode, the PhantomCamera3D becomes a non-top-level child of that physics object, and therefore also must move during the physics tick.

AFAIK, 3D physics interpolation is not implemented in 4.3: only 3.6, and who knows if it'll make it in, since 4.3 is already long overdue, and they're regularly talking about "the 4.3 feature freeze".(godotengine/godot#89846) In general, I agree that the "fix" for any jitter from PhantomCamera's side can simply be to move everything into _physics_process (or at least have that option available): #241 (comment)

By the way @ramokz, for any of the changes I suggest either here or any of the issues, I wasn't directly asking if you could implement them, as I have some version, if not multiple versions of most of these changes in one project or another. I just wasn't sure if it would be worth my time to format them as clean and modular PRs, since many changes are codependent and require larger-scale refactors.

[ramokz]

AFAIK, 3D physics interpolation is not implemented in 4.3: only 3.6, and who knows if it'll make it in, since 4.3 is already long overdue, and they're regularly talking about "the 4.3 feature freeze".(godotengine/godot#89846) In general, I agree that the "fix" for any jitter from PhantomCamera's side can simply be to move everything into _physics_process (or at least have that option available): #241 (comment)

3D will likely not make it to 4.3, as 2D barely did, but hard to say.

Want to point to this particular comment in that post for why moving the logic into the _physic_process isn't a good idea before the physics interpolation gets added to Godot.
Tldr; you solve one problem (jitter free physics-based nodes) but introduce another (jittery non-physics-based nodes). If you add the PCam logic to the _physics_process you will not be able to have any jitter-free animations for anything moving using a Godot Tween, AnimationPlayer or any non-physics-based animation. This is fine when you're only working with an object that's moving in the _physics_process, but is pretty bad in all other scenarios. Think cutscenes, animated in-world UI etc.
Conversely, the guidelines in the documentation site explain how to get around addressing both situations, so you can have jitter-free animations in both _physics_process and _process.

Again, that workaround is to use the smoothing-addon, or part of its underlying code. The author is also the one who added it as a built-in feature to Godot 3. The reason being is that it's something that should be in the engine core, and the smoothing-addon was initially made an external solution to fill in a gap the engine had. Where they later on then decided to make that addon effectively obsolete by making the feature built-in instead. What audeck says in the link you're referring to is correct in the context of having physics interpolation as part of the engine itself. But without it, it resurfaces the issue mentioned above. Phantom Camera will dynamically switch between _process and _physics_process, and you can see the current setup for 2D scenes in #294, depending on the assigned target for when physics interpolation is available. However, it's being limited to 2D and for Godot 4.3 and later for the moment for the same reasons mentioned above.

By the way @ramokz, for any of the changes I suggest either here or any of the issues, I wasn't directly asking if you could implement them, as I have some version, if not multiple versions of most of these changes in one project or another. I just wasn't sure if it would be worth my time to format them as clean and modular PRs, since many changes are codependent and require larger-scale refactors.

I wouldn't suggest making any PRs without bringing up either a discussion or feature issue post about the exact feature or changes proposed — as per the contribution documentation page. Larger changes need some degree of alignment about the direction and what problem a given addition would solve, or whether if the proposal even has merit. Some proposals are sound for a given project, but can be so bespoke to a particular thing that it adds more noise than benefit to the project as a whole. Like pretty much all things for all projects, features ought to be planned and agreed upon before work starts, otherwise time and energy is likely just wasted.