Add rotate_toward and angle_difference methods.

[ettiSurreal]

Closes: godotengine/godot-proposals#2074
Supersedes: #69081

Adds:

• angle_difference, gets the difference between two angles in radians.
• rotate_toward, an angular analog of move_toward. Moves from to to by an increment specified by delta, similarly to lerp_angle wrapping around after TAU and picking the shortest path. Passing in a negative value moves toward the exact opposite angle.
  Called move_toward_angle in the old PR.

Additionally lerp_angle is internally modified to utilize angle_difference in order to avoid code repetition.
Implemented for GDScript and C#.

Current implementation based on:
#69081 (comment)

[AThousandShips]

I'd suggest adding tests to ensure correct behaviour of these new functions

[ettiSurreal]

I'd suggest adding tests to ensure correct behaviour of these new functions

Haven't tried setting up tests myself yet, would it be okay if someone else could do it when possible?

[aaronfranke]

This PR should have unit tests for these new methods. It looks like there are already unit tests for lerp_angle, and angle_difference is simpler, so fewer unit tests are needed for angle_difference than lerp_angle, but there should still be some. rotate_toward should have a similar number of unit tests as lerp_angle.

[ettiSurreal]

This PR should have unit tests for these new methods. It looks like there are already unit tests for lerp_angle, and angle_difference is simpler, so fewer unit tests are needed for angle_difference than lerp_angle, but there should still be some. rotate_toward should have a similar number of unit tests as lerp_angle.

Tried it out (probably not the best).
The first two tests under // Rotate away. will most likely fail, as i discovered an issue that if you try moving away from the exact same from and to, the value will be locked at from, and i couldn't find a way to fix this reliably. @kleonc since you wrote the implementation that's currently used, can you try helping with this?

[kleonc]

Approving the code/behavior (but I've suggested the current implementation so yeah... 🙃).

I'm not sure/convinced about the rotate_toward naming, personally I liked move_toward_angle more. But if rotate_toward is what people like more then I'm fine with it. Not having "angle" anywhere could possibly be bad for discoverability though so maybe e.g. rotate_toward_angle should be considered as an alternative. 🤔 Either way I'm fine with any of these.

AFAICT the methods being added are desired/used quite often (and they seem easy to implement incorrectly). Proposal (godotengine/godot-proposals#2074) has positive feedback, also personally in the last ~2 monts I've redirected users ~5 times to take a look at this PR for how to implement such functions (which they were directly/indirectly asking/looking for).

cc @akien-mga as not sure who to poke here. 🙂 If overall we're fine with adding such functions then I think resolving this for 4.2 makes sense.

[fire]

@akien-mga Can you do a production team review and merge?

@kleonc and @aaronfranke maintain some of the math codes

[ettiSurreal]

Sorry, still have trouble with using git so i took a while to squash commits.

[aaronfranke]

I am in favor of having this method, I reviewed the code, test cases, and docs. It looks good to me 👍

[ettiSurreal]

I'm not sure/convinced about the rotate_toward naming, personally I liked move_toward_angle more. But if rotate_toward is what people like more then I'm fine with it. Not having "angle" anywhere could possibly be bad for discoverability though so maybe e.g. rotate_toward_angle should be considered as an alternative. 🤔 Either way I'm fine with any of these.

Main thing that motivated me to rename this to rotate_toward is the idea of adding a rotate_toward function for Vectors, Quaternions and such, which this would definitely be a more fitting name for.
Though now thinking about it, shouldn't angle_difference be called angle_to, for consistency with these?

[aaronfranke]

Both angle_to and angle_difference make sense to me. People often think of subtraction when they hear "difference", which is also the case with this function, but also it's more complex than that. The only thing about angle_to is that vector_a.angle_to(vector_b) has the benefit of being nicely readable as "a angle to b", but angle_to(a, b) is not quite in the nice form of "a angle to b", so by this logic this is slightly in favor of angle_difference.

As for move_toward_angle vs rotate_toward, again both make sense to me. I think I like rotate_toward better, because "move" is usually associated with translation, while this is an angle, and angles represent rotation. But also, it has the same level of readability as angle_to mentioned earlier, so... ¯\_(ツ)_/¯

[akien-mga]

Thanks! And congrats for your first merged Godot contribution 🎉

[Zireael07]

Finally I don't have to write my own clunky stuff to rotate my NPCs to target... 🎉

[adamscott]

Thanks, and welcome @ettiSurreal !