Add Godot's goodies functions

[NNBnh]

I miss some math functions in GdScript that I used on the daily basis:

• globalscope.wrap
• globalscope.lerp
• globalscope.inverse_lerp
• globalscope.move_toward
• globalscope.pingpong
• globalscope.snapped

These are all useful in calculation, gamedev, physical simulation, animations, AOC... If people found this fit with the project, I would love to open a PR <3.

[NicklasXYZ]

Yes, I think those could be great additions to the math library!

That said, i would suggest to use more explicit/descriptive names, for example:

• lerp -- a more explicit name would in this case would be linear_interpolation. Furthermore, it could also be valuable to implement more general versions of this function (for instance, supporting multi-point interpolation rather than just two-point interpolation).
• wrap -- Works as is, but perhaps a more descriptive name like wrap_range or range_wrap would make things clearer.
• pingpong -- Seems to be another kind of wrapping function. We could consider using a similarly descriptive name following the same naming convention as the point above, e.g. wrap_reflect?
• move_toward -- This looks conceptually related to the step_range already implemented by the library. Perhaps there is an opportunity to extend or generalize that existing implementation.
• snapped -- Reading the description of the function, maybe we could rename it to round_to_multiple to align it with the existing rounding functions.

[NNBnh]

Sorry for the super late reply. I finally remember to come back to this. Here are my API design base on your feedback:

• globalscope.wrap:
  • wrap_range(n: Float, start: Float, stop: Float)
• globalscope.pingpong
  • wrap_reflect(n: Float, start: Float, stop: Float)
• globalscope.snapped
  • round_to_multiple(x: Float, step: Float)
• globalscope.lerp:
  • linear_interpolation(weight: Float, start: Float, stop: Float)
  • multipoints_linear_interpolation(points: List(#(Float, Float))) where points is like a dict with point as key and weight as value.
• globalscope.inverse_lerp
  • inverse_linear_interpolation(weight: Float, start: Float, stop: Float)
  • multipoints_inverse_linear_interpolation(points: List(#(Float, Float))) where points is like a dict with point as key and weight as value.
• globalscope.move_toward
  • move_toward(delta: Float, start: Float, stop: Float)

I moved weight and delta arguments to the beginning to make piping easier. This is more consistent with functions that have start & stop args too. (But I'm not sure if this is a good ideal or not...)

I have thinking about dropping move_toward out when I found it to look like something step_range can do... But turnout it's not, yeah it's just related. Currently, I can't think of any way to extend or generalize step_range to make it convenient to the use case that move_toward solve. Maybe I need some more time to think about this. move_toward Should be implemented last.

[NicklasXYZ]

@NNBnh Thanks for the work and overall I think it looks solid! I do have a few small suggestions regarding the naming and API consistency.

The following looks good to me:

pub fn wrap_range(x: Float, start: Float, stop: Float)

For the reflective variant, I would probably lean into the *_with_* naming scheme to make the relationship more explicit, i.e., same behavior as wrap_range, but with reflection at the boundaries instead of wraparound:

pub fn wrap_range_with_reflection(x: Float, start: Float, stop: Float)

The rounding function also looks fine to me:

pub fn round_to_multiple(x: Float, step: Float)

Instead of delta, I would suggest increment. It reads a bit more explicit:

pub fn move_toward(increment: Float, start: Float, stop: Float)

For the interpolation functions, I think it might be worth spending a bit more time refining the API. Considering a naming scheme that could potentially be easily extended in the future (e.g. higher-degree polynomials, bilinear interpolation, etc.). Something along these lines could maybe work:

pub fn linear_1d_segment(
  x: Float,
  from: Float,
  to: Float,
) -> Result(Error, Float)

For interpolation on a single 1D segment (i.e. two points defining a line). And the following for the corresponding inverse function:

pub fn inverse_linear_1d_segment(
  y: Float,
  from: Float,
  to: Float,
) -> Result(Error, Float)

For piecewise linear interpolation (multiple points), maybe this could work:

pub fn linear_1d_piecewise(
  x: Float,
  points: List(#(Float, Float)),
) -> Result(Error, Float)

And the inverse variant:

pub fn inverse_linear_1d_piecewise(
  y: Float,
  points: List(#(Float, Float)),
) -> Result(Error, List(Float))

Since the function may be non-monotonic, a given y value can correspond to multiple x values across different segments, and returning List(Float) reflects that possibility.