Refactor FRAMED Follow Mode with Cinemachine-style Screen-Space Framing

[Mustfa-IT]

Overview

This PR refactors the FRAMED follow mode in PhantomCamera3D to use a Cinemachine-style screen-space framing approach, replacing the old offset-based system. It also adds physics interpolation support for smoother camera behavior.

Key Changes

PhantomCamera3D (phantom_camera_3d.gd)

New Framed Follow State Variables:

• _framed_depth_ref - Stable depth reference to prevent camera bobbing
• _framed_output_position - Smoothed output position for corrections
• _framed_initialized - Tracks whether framed state has been initialized
• _framed_correction_velocity - Velocity for smooth damping of corrections
• _framed_smoothed_target - Smoothed target position to filter physics jitter
• _previous_basis - For rotation change detection
• _follow_target_has_interpolation - Cached check for get_global_transform_interpolated support

New Helper Functions:

• _initialize_framed_state() - Initializes depth reference and output position
• _calculate_world_per_pixel() - Calculates world units per screen pixel at a given depth
• reset_framed_state() - Resets framed state (called on teleport, becoming active, or target change)
• _set_framed_correction_velocity() - Velocity setter for smooth damping

Refactored FRAMED Logic:

• Uses viewport visible rect for letterbox/pillarbox awareness
• Computes deadzone bounds in visible-rect local pixels
• Calculates screen-to-world correction using project_position() at stable depth
• Properly handles rotation changes by refreshing depth reference without snapping

Physics Interpolation Support:

• _get_target_position_offset() now uses get_global_transform_interpolated() when available and physics interpolation is enabled
• Reduces jitter on deadzone edges for physics-based targets

State Reset Integration:

• teleport_position() now calls reset_framed_state()
• set_is_active() resets framed state when becoming active
• set_follow_target() resets framed state when target changes
• set_follow_offset() resets framed state when offset changes in FRAMED mode
• _on_dead_zone_changed() resets framed state

PhantomCameraHost (phantom_camera_host.gd)

FRAMED-specific Interpolation Handling:

• In AUTO interpolation mode, FRAMED is forced to use _process() (IDLE) instead of _physics_process()
• Disables physics interpolation for the camera in this case to prevent fighting with the screen-space framing logic
  the camera host fix is unfortunate in my opinion but if it is not present the Camera will have a weird damping when Going toward or away from the Camera in result of weird limitation of the engine

[Mustfa-IT]

@ramokz i hope this PR can be tested bit more then normal as it replacing the entire Framed logic and it did alot in my opinion but hopefully in the better direction.

[Mustfa-IT]

Fixes:
Framed Follow can get stuck on the side or corner of the dead zone #614
3D only fix for Framed Follow target not accurately matching the node target's position at lower physics tick rates #613
Fix the issue mention in #616 for the Y axis of the camera in Framed mode

Note: make sure the follow axis lock in the 3d_framed_exmaple is set to Y in the PCam3

[Mustfa-IT]

@ramokz there were some missing Change that i did not include by mistake now it should fixed as of my last commit (sorry).

[ramokz]

Testing it briefly, and it doesn't seem to be moving in the Z-axis as you're moving away or towards it?

Stable

framed-follow-stable.mp4

PR

framed-follow-PR.mp4

[Mustfa-IT]

@ramokz Make the Follow Axis Lock to Y.

[ramokz]

Sorry, I missed that note above.

Think it has to be a default setting, or rather be applied to the mode's logic itself without changing the follow_axis_lock property. I don't expect users to not encounter this issue, leading to bug reports. Given there's no obvious reason that you would have to select an option in a different menu to make it work as intended without reading documentation, which far from everyone does.

[Mustfa-IT]

which far from everyone does.

never been more true XD.

i will be setting it to Y as a default.

[Mustfa-IT]

i just made it so that if the user changes the Follow mode and the lock is set to none it going to be set to Y (the effect can't be seen if the mode is set to Framed from the start)

[ramokz]

Testing this, I think the approach might need to be readjusted.

When testing, both the Z and Y index positions yield an unexpected result. Almost as if it pushes the camera away in the Z-axis while it's remaining the same distance away as the target is falling down or, presumably, moving upwards. The stable version is what ought to be happening, minus the camera sticking to the bottom of the dead zone.

Think the freezing of the y-axis is partially the culprit in the PR version, as the camera should also be moving vertically as the target leaves the vertical dead zone. But I'm suspecting the inability for the camera to do that means the z position is changed to compensate for the lack of the vertical (y) movement option.

Stable

framed-follow-z-offset-stable.mp4

PR

framed-follow-z-offset-PR.mp4

[Mustfa-IT]

.

Think the freezing of the y-axis is partially the culprit in the PR version, as the camera should also be moving vertically as the target leaves the vertical dead zone. But I'm suspecting the inability for the camera to do that means the z position is changed to compensate for the lack of the vertical (y) movement option.

That is correct when I implemented this was the downside of this approach
But i think we can get rid of this issue by moving on z first and then on y when needed.

I will try to test if it's possible.

[Mustfa-IT]

I don’t think this PR should be merged ever.
I’ve been working on it for the last 3 days, and while it improves the Framed follow while i got a fix for the Y follow it also introduces new problems (rotation behavior and projection/framing inconsistencies).
At this point, I think it’s safer to focus on smaller, isolated fixes to the existing framed follow logic instead of a larger refactor, since that will be less error-prone and easier to review.

i hate to say these words tbh.

[ramokz]

That's okay! You tried, and that's worth a lot still :)

The Framed feature is the most complicated feature of the addon, so it was never going to be an easy task to refactor.