Interpolation tutorial omits important info on lerp()

[verity147]

Godot 4.3:

Issue description:
The description and example for Vector2.lerp() makes it seem like the function automatically stops once the weight parameter hits or exceeds 1 or the target parameter is reached, mostly due to the looping gif and the minimalist code example.

I'd suggest at least mentioning that the user needs to actively limit their weight property or otherwise stop the lerp manually.

Suggested changes to the code example:

var t = 0.0

func _physics_process(delta):
	clamp(t += delta * 0.4, 0, 1)

	$Sprite2D.position = $A.position.lerp($B.position, t)

or checking if the target position is reached etc. But I feel like clamping t is the most universally applicable way to solve this.

I feel like a lot of the issue stems from the gif with the line "It will produce the following motion:" above it suggesting that there is some kind of automatic stop to the lerp.

This has been mentioned before in #9674 but the person reporting closed it themselves on the same day.

URL to the documentation page (if already existing):
https://docs.godotengine.org/en/stable/tutorials/math/interpolation.html

[AThousandShips]

The method documentation says to limit the weight to the [0, 1] range

Also did you see this line in the text?

For example, if t is 0, then the state is A. If t is 1, then the state is B. Anything in-between is an interpolation.

This to me speaks very strongly to the fact that interpolation is in this range

[verity147]

What you linked says :

weight is on the range of 0.0 to 1.0

It does not say that the function actually allows for weight go past 1. In fact I would argue that the description you linked is pretty ambiguous. I feel like it should be "weight has to be in the range of 0.0 to 1.0, representing the amount of interpolation, otherwise the function produces unexpected results". (emphasis on suggested changes)

To your second point, I understand that interpolation happens between 0 and 1, it's essentially like % of the way between A and B.

What I am suggesting is that the combination of wording and gif shown in the tutorial make it seem like lerp() knows to stop once it reaches 1 automatically and that since the article is a tutorial it should advise the reader to take care of either limiting the variable they are feeding into the weight property so it can never exceed 1 or otherwise end the lerp at the desired target themselves.

Or maybe lerp() should throw a warning if it recognizes that a value it is getting for weight is not between 0 and 1, but that would maybe go a little far in terms of handholding.

Backstory: I used Unity before and got fooled by the gif, believing it showed the literal behaviour of lerp() since the ending of the animation shows quite a pronounced stop that must be more that just the gif looping. I thought Godot's implementation of lerp() was just that fancy that it stopped on its own once it reached 1.

[tetrapod00]

Yeah, it seems like the class reference and the tutorial could be clearer in this case. The documentation for the global scope lerp()
is already quite good IMO. So maybe we should copy elements of that, or link to it, for the Vector2.lerp() description (and the similar ones for the other vector lerps).

The tutorial page has needed a rewrite for a while anyway.

As for adding a warning, or clamping, or similar: it is not desirable for a general purpose lerp() function to clamp, since lerp() is a mathematical function and using values outside the range is valid. The docs for global scope lerp even mention that.