Implement very basic look ahead functionality

[audeck]

Compared to the old look ahead PR (#160), this has the disadvantage of being directly affected by follow_damping (though conceptually, I am completely fine with that). Otherwise, it is very reminiscent of the original, being implemented only for the 2D SIMPLE mode with a follow target (as that is the main use case for me), but the @export values are much friendlier for me to use personally.

Additionally, I've included a potentially better way of defining @export property visibilities. This approach has the advantage of less code distance (i.e. being able to define a property's visibility right where you define it), but it also has the disadvantage of needing an editor reload every time you change when it should be visible. I'm also unsure of how it'd interact with other property.usage values, but they should co-exist peacefully in the _validate_property() function. Note that this is merely a proposal.

Still a few TODOs left at the very least; opening a PR to get input on the aforementioned, how to reconcile the 2 PRs together, and nitpicks of course :^).

[ZenithStar]

(I'm not working on any 2D games at the moment, so I'm not particularly invested in this feature, so take my opinion with a grain of salt.)
I see that you implement the look-ahead offset proportional to velocity, but I'd expect the behavior to be more similar to the framed follow mode, but with the look-ahead offset state snapping to the direction the player moves after passing a threshold:

[audeck]

I definitely see what you mean. What would make the most sense to me when trying to replicate the camera in question, would be framed follow mode, with the look ahead for it acting to offset the frame as well (and, therefore, give the player some leeway before shifting the camera the other way).

Hollow Knight does something similar for the X axis, just without dead zones:

Technically, Hollow Knight's camera's X axis behavior could be replicated by allowing the offset to persist, setting the look_ahead_min_velocity.x to 1 with look_ahead_min_offset and look_ahead_max_offset being identical (albeit the current implementation doesn't handle this correctly).

As for the Mario camera, the same could be done, but with framed follow mode and checking if the frame moved instead of the follow_target.

However, I think you point out a good distinction in the sense that there is a difference between Mario and Hollow Knight's directional look ahead, and this PR's velocity based look ahead. The former is more so a "forward focus", and the latter a "velocity offset".

Might be a good idea to split the look ahead functionality into these two instead, then, as it'd allow to recreate the Mario camera, but also with an additional offset that scales with velocity when going really fast (for a more momentum-based game).

I.e.:

• Forward focus:
  • forward_focus
  • forward_focus_offset
  • forward_focus_deadzone (? - not sure if this functionality isn't completely superseded by using framed follow mode)
• Velocity offset:
  • basically what the initial commit already has, but renamed accordingly

[ramokz]

This is neat!

Please correct me if I misinterpret how the values are being set and applied to the camera position.

The challenge I see with defining min / max velocity and min offset values is that those values will, likely, need to change as the target's velocity speeds up or slows down. Whereas if it relies on time, then the velocity will dynamically change the Lookahead effect. I'm still generally leaning towards the approach from my previous comment in the other PR about having the properties provide relative rather than absolute values. I.e. the properties provide the option for the user to decide “how many seconds ahead should the camera be positioned based on the current velocity” and “how quickly should it accelerate to that”. For me, it feels like a simpler system to understand, use and change during runtime if needed. Clamping the Lookahead offset also, like you've done, definitely feels like a right choice.

The way I imagine it is that you would have the following properties:

• Lookahead (bool)
  • Toggles the feature on / off.
• Lookahead Time (Vector2)
  • Determines how many seconds ahead the follow target will be based on its velocity and updates the camera to gradually move towards that position. The Vector2 values represent the X and Y positions, which can be specified independently of one another.
• Lookahead Speed (Vector2)
  • How fast the camera should be moving to the Lookahead Time position from its current position. Like with Lookahead Time the X and Y values are being applied to each axis.
  • It could potentially be split in two, if there's a desire for a separate deceleration speed.
• Lookahead Max (Vector2)
  • A clamp to not exceed a certain distance offset, no matter the Lookahead Time or velocity.

I want to be careful about not overcomplicating the feature and being too opinionated about how it works — particularly for a first iteration. Think this is one of those things that can be done in many ways depending on the needs of a project. Can think of cases where a user would want to enable or disable the Lookahead when certain conditions are met. Take the Mario example, if the user exceeds a certain boundary, like a Framed Follow dead zone, then that could temporarily enable the look Lookahead for x number of milliseconds before disabling it again.
The Hollow Knight example is an interesting one. Wonder if that could be achieved by having a Lookahead Deceleration property that would then be set to 0, which is to say, the camera doesn't return to its original follow target position if the follow target stops moving.

About the alternative way of toggling visibility for the @export, I like the thinking of keeping the visibility checkers near the variable declaration, as it's a bit of a pain to scroll back and forth between the at the minute. That said, I am still favouring the _validate_property() approach, since it follows the conventional Godot standard and is, from my view, easier to read, which is more important as it enables others to more easily understand the codebase.

[audeck]

The Hollow Knight example is an interesting one. Wonder if that could be achieved by having a Lookahead Deceleration property that would then be set to 0, which is to say, the camera doesn't return to its original follow target position if the follow target stops moving.

I've been thinking about this one. It's technically just a follow_offset getting updated at runtime, which, in my opinion, should be left up to the games themselves.

I can think of a game where the movement and "looking" are decoupled (one using WASD, the other IJKL, for example). But then there are two options that the developer could want:

1. Have an offset toward where the character is moving, even if it's looking behind
2. Have on offset toward where the character is looking, even if it's moving in the other direction

This is also why I think naming this functionality "Lookahead" could be a bit misleading, especially for people who have no knowledge of Cinemachine, as opposed to naming this some kind of "Velocity offset".

One a side note -- in order to achieve this functionality using Framed Follow, something like a started_moving signal would be nice to have to know when to update the follow_offset.

As for time vs. min/max velocity, I like the fact that it's effectively decoupled from the follow target's speed. I've gone with min/max velocity initally because it'd be easy to use different interpolation functions (your where from interpolate(from, to, where) would be simply (max_vel - cur_vel) / (max_vel - min_vel)), which is something I wanted for my project. May be too opinionated, though.

It'd technically be possible to have a "Lookahead min" and "Lookahead max" offset and use those for the interpolation. That is, calculate the offset depending on where the follow target will be in X seconds, and use that for the interpolation calculation if interpolation isn't set to none. I don't know how interpolation would interact with smoothing/damping in general, though; will have to experiment with that.

[audeck]

I've gone with "smoothing" instead of "speed" for controlling the offset. There is a velocity_offset_smoothing_factor, which just gets input into a lerp call. It is getting applied before follow_damping, which means the velocity offset is still affected by it. I'm not sure how Cinemachine does it, nor do I have any experience using it, so additional input is welcome here:

1. Should the velocity offset be affected by follow_damping?
2. What would you expect the smoothing/speed implementation to look like in general? Mainly, what values would you expect to use with it (higher values => more smoothing -- just like follow_damping, or the other way around, perhaps)?

[ramokz]

I've been thinking about this one. It's technically just a follow_offset getting updated at runtime, which, in my opinion, should be left up to the games themselves.

There was a similar disucssion on Unity's forum about the Lookahead feature for Cinemachine. From that conversation, there is a seemingly agreed idea of allowing the Lookahead mechanic to not move back towards its targeted position based on a user defined parameter. Though as that was not included in Cinemachine, at least at this point in time, one can argue that it isn't needed for a first iteration for this feature. Just something to keep in mind if nothing else.

I can think of a game where the movement and "looking" are decoupled (one using WASD, the other IJKL, for example). But then there are two options that the developer could want:

1. Have an offset toward where the character is moving, even if it's looking behind
2. Have on offset toward where the character is looking, even if it's moving in the other direction

Think a solution to that could be a Group Follow. Where, e.g., one target being a playable character, and another being either the mouse position on the screen, or another node in the scene. That way, you're moving the camera based on both positions, which should resolve that?

This is also why I think naming this functionality "Lookahead" could be a bit misleading, especially for people who have no knowledge of Cinemachine, as opposed to naming this some kind of "Velocity offset".

I think both terms have merits. “Velocity offset” infers that the camera will change position, or be offset, due to changes in velocity. While “Lookahead” infers that the camera is looking further ahead from its current position. To my mind, the main interpretational difference is that “Lookahead” suggests that the camera is explicitly moving forward, whereas “Velocity Offset” implies that it's just being offset without a particular direction in mind. To your point, “Lookahead” in of itself doesn't necessarily tell the user what it will actually do and works more like an interpretive description rather than a technical one — similar to “damping” vs. “smoothing”. Though do think that's an easy solve with documentation or by the user enabling it themselves and trying it out. There is also an inverse risk of renaming something that people who are familiar with the feature in Cinemachine to something else that works the same way.

One a side note -- in order to achieve this functionality using Framed Follow, something like a started_moving signal would be nice to have to know when to update the follow_offset.

Not entirely sure how it would impact Framed Follow? But think an easier way to detect movement anyway would be to rely on the velocity changes, or a velocity flag if you will, as they would be set at the same time.

As for time vs. min/max velocity, I like the fact that it's effectively decoupled from the follow target's speed. I've gone with min/max velocity initally because it'd be easy to use different interpolation functions (your where from interpolate(from, to, where) would be simply (max_vel - cur_vel) / (max_vel - min_vel)), which is something I wanted for my project. May be too opinionated, though.

Not sure if a min_velocity is needed? If it had a minimum value, then it would always teleport that minimum distance, which I can't imagine would ever be desirable? The max velocity, on the other hand, would mean that the user would have to guess what an ideal max velocity is. As that property is effectively a limit to, likely, avoid the camera flying off screen. That said, max_velocity might be a solid alternative to my proposal of having a Vector2 with lookahead_max. Potentially, one could also offer both options and clamp both the velocity and positional offset respectively.

I've gone with "smoothing" instead of "speed" for controlling the offset. There is a velocity_offset_smoothing_factor, which just gets input into a lerp call. It is getting applied before follow_damping, which means the velocity offset is still affected by it. I'm not sure how Cinemachine does it, nor do I have any experience using it, so additional input is welcome here:

1. Should the velocity offset be affected by follow_damping?
2. What would you expect the smoothing/speed implementation to look like in general? Mainly, what values would you expect to use with it (higher values => more smoothing -- just like follow_damping, or the other way around, perhaps)?

1. Short answer, yes. Think follow_damping and lookahead_smoothing aren't mutually exclusive and should work alongside one another. Ultimately, the lookahead feature just offsets the follow_target position. Where the lookahead_smoothing merely interpolates that offset value. Whereas follow_damping changes the movement velocity of the camera itself.
   If the lookahead doesn't have any lookahead_smoothing applied, but has follow_damping, then the camera will just behave as if the follow_target has teleported that lookahead distance away.
2. Think keeping it consistent with follow_damping where 0 = no smoothing, and higher values applies more, makes the most sense.

The above was based on some tests in the latest Cinemachine release in Unity 6. It also made me realize that follow_damping and lookahead are technically opposites of one another and yet work in tandem. follow_damping causes the camera to lag behind the target, whereas lookahead causes the camera to move ahead of the target. If both are enabled then Cinemachine will balance out the velocity drivers of both features. I.e. it can in theory be following a spot in-between the lookahead position and the follow_target. Which I have nothing against, as you would then just need to adjust the follow_damping and lookahead values to work well together.

For the smoothing operation itself, instead of the lerp function, would also suggest trying out the internal _smooth_damp function that is used for follow_damping. That should mirror the smoothing behaviour from the follow logic and allow for using a smoothing parameter value where 0 = no smoothing - not to mention feel a bit nicer too.

[audeck]

Not sure if a min_velocity is needed? If it had a minimum value, then it would always teleport that minimum distance, which I can't imagine would ever be desirable?

The equation is wrong, but the original idea was to not have any look ahead if the player is moving purely from user input, and then, when they get sped up by something for example, start applying look ahead (i.e. min_v would be the player's maximum running speed).

Ideally, I, as a plugin user, would like to supply the Phantom/Cinemachine camera with a custom function that takes in the velocity of the follow target and outputs the look ahead offset, but I have no idea what that entails from the plugin side of things. Will look into that out of curiosity, at the very least. Going with time will be simpler for the time being.

Not entirely sure how it would impact Framed Follow? But think an easier way to detect movement anyway would be to rely on the velocity changes, or a velocity flag if you will, as they would be set at the same time.

Completely unrelated to look ahead; since Framed Follow's camera has conditions during which it is stationary, there might be things the user wants to do when it starts moving (such as set a frame offset of some sort, depending on which direction it's moving). The idea came about when thinking about replicating the aforementioned Mario camera, but I'm not sure if Framed Follow is even the correct mode to choose.

Think a solution to that could be a Group Follow. Where, e.g., one target being a playable character, and another being either the mouse position on the screen, or another node in the scene.

I was thinking about this afterwards as well, and I completely agree. Though, I do think this sort of underlines the objectivity of what "looking" means.

“Velocity Offset” implies that it's just being offset without a particular direction in mind.

I agree that "look ahead" conveys more meaning as to what direction the offset is getting applied in. While there are probably better names, such as "Forward offset" for an example, at that point it might as well be called just look ahead offset. After all, "coyote time" isn't time for coyotes either, is it?

Will try to finish up and turn this into a proper pr in the near future.

[ramokz]

The equation is wrong, but the original idea was to not have any look ahead if the player is moving purely from user input, and then, when they get sped up by something for example, start applying look ahead (i.e. min_v would be the player's maximum running speed).

My understanding of max_velocity is that the camera would be clamped to a maximum velocity and then never exceed a certain distance away from the follow target, no matter how fast the follow target is moving. So min_velocity would then be a case of defining “how fast should the target move before the lookahead offset goes into effect”? My initial assumption when reading it was that the camera would always have that specified minimum velocity applied whenever the lookahead functionality was triggered.

Since the idea behind lookahead is that it would look further and further ahead as the follow target's velocity gradually increases. If you then prevent the camera from looking ahead while a min_velocity is in effect, wouldn't that then mean the camera would then rapidly move ahead to catch up to where it would have been had a min_velocity not been applied? Might be wrong, but that would be my hypnosis.

If it's a case of enabling or disabling lookahead, then there's also an option for the user to toggle the lookahead functionality and only enable it when, e.g., running. Or just switch between PCams as needed — Cinemachine's sample scenes, for example, do this a lot.

Ideally, I, as a plugin user, would like to supply the Phantom/Cinemachine camera with a custom function that takes in the velocity of the follow target and outputs the look ahead offset, but I have no idea what that entails from the plugin side of things. Will look into that out of curiosity, at the very least. Going with time will be simpler for the time being.

Isn't that effectively how the lookahead system in Cinemachine does it? I.e. calculating the velocity of a follow target and applies an offset, interpolated if smoothing is enabled by the user, to the position of the camera. Think it would be a fairly easy system to use and, from quick tinkering, implement.

Would definitely suggest checking out the Cinemachine sample scenes that come with the latest package version, or some of the online videos showing how it functions in practice.

Completely unrelated to look ahead; since Framed Follow's camera has conditions during which it is stationary, there might be things the user wants to do when it starts moving (such as set a frame offset of some sort, depending on which direction it's moving). The idea came about when thinking about replicating the aforementioned Mario camera, but I'm not sure if Framed Follow is even the correct mode to choose.

There could be a signal for detecting when a target touches the dead_zone called dead_zone_triggered, which the user could then make use of.

For the Mario example, one approach would be to tween from a PCam that follows the playable character to another PCam that is firmly attached to the playable character once the dead_zone_triggered is emitted.

If we're talking about detecting character movement in general, then it feels like it would make more sense for the user to make their own movement flag, kinda like _is_grounded, within their movement script. The user can then compare that flag with a PCam's dead_zone_triggered signal and perform the appropriate action from there.

I was thinking about this afterwards as well, and I completely agree. Though, I do think this sort of underlines the objectivity of what "looking" means.

“Looking” is technically an impossibility in 2D environments, as all you can do is pan the camera in different directions. Think the key part of the phrase in “lookahead” is “ahead” given the directional connotation of the word. But you're right in that the exact meaning is nonsense the more you think about it.

I agree that "look ahead" conveys more meaning as to what direction the offset is getting applied in. While there are probably better names, such as "Forward offset" for an example, at that point it might as well be called just look ahead offset. After all, "coyote time" isn't time for coyotes either, is it?

Tech terminologies are funny. It's always about finding a balance between accuracy and comprehension. Sometimes, you just can't have both :D

I'm generally leaning more towards comprehension even at the cost of technical accuracy, as ultimately the goal is to be as easily discoverable and understandable for others as possible. The main thing is to just ensure it doesn't obfuscate or mislead its purpose and functionality.

The same applies to “physics interpolation”, which is apparently more accurate to refer to as “fixed timestep interpolation”. Though “physics interpolation” is probably still a bit of a vague term to many, “fixed timestep interpolation” is likely even more confusing in spite of being more accurate.

[audeck]

As far as min_velocity goes, the concept is that the player moves at a velocity of, say, v (let's take into account only one axis for this). While abs(v) < min_velocity, min_offset gets applied (which would be 0 in many cases). While min_velocity < abs(v) < max_velocity, the offset starts getting applied from min_offset at min_velocity to max_offset at max_velocity. Then, while abs(v) > max_velocity, max_offset gets applied.

This lets me control the camera in a way where I can start applying the look-ahead offset at some velocity threshold. The time-based look-ahead doesn't allow me to do this in a way where I don't have to update a camera's properties at runtime, as far as I'm aware.

As an example, I don't see an easy way of implementing a camera that:

1. Follows a target with no offset while target_velocity <= target_running_speed
2. Starts applying offset if the target gets sped up by an item they picked up or used some ability (i.e. target_velocity > target_running_speed)

This is conceptually a perfect fit for look-ahead offset, but impossible to implement using only look-ahead time, as the target could already have a considerable amount of velocity when it crosses over target_running_speed (and we tween to a camera with look-ahead time, for example).

Again, the ideal solution to user defined look-ahead would be to allow the user to provide a function f(target_velocity) = look_ahead_offset. This would allow the user to control the offset to a much higher degree than just specifying look-ahead time and tweening between different cameras.

On a side note; the only way of specifying look-ahead in the Cinemachine docs that I've found was using time (namely in the Composer and Framing Transposer modules).

There could be a signal for detecting when a target touches the dead_zone called dead_zone_triggered, which the user could then make use of.

Exactly what I had in mind!

[ramokz]

To me, min_velocityread as if it would be the equivalent of disabling and enabling the lookahead once the follow_target's velocity reaches a certain value.

So, wonder if a simpler alternative to achieve what you describe, at least to start with, would be to expose the follow_target's velocity as a read-only property. Where the user can then enable/disable the lookahead system and refine the lookahead_time and lookahead_smoothing based on that velocity value.

In any case, would prefer to keep the feature simple to start with, rather than adding everything to it for a first iteration. So limiting it to just an on/off toggle (lookahead), lookahead_time and lookahead_smoothing would set the groundwork for enhancements to come.
Don't want perfection to be the enemy of good.

Adding a min_velocity and max_velocity can then be considered an enhancement for a follow-up release. Think there's a bit more to the discussion than I think is worth addressing in a first stab at a new feature.