Docs: Update AStar3D examples

[tetrapod00]

Closes godotengine/godot-docs#10230

The examples for custom distance calculations were comparing the IDs of the points, which doesn't really make sense. I updated the examples to use Manhattan distance as an example of non-Euclidean distance. class_name/[GlobalClass] is used here because MyAStar3D needs to be referenced from another class to be used.

Also changed _estimate_cost() to simply use the actual cost. The current example was not very instructive, since it was more expensive than calculating the real cost. This change I'm not 100% sure about.

Alternate names for Manhattan distance are "Taxicab distance" or "city block distance". Godot already uses "Manhattan distance" in a few places:

godot/modules/noise/doc_classes/FastNoiseLite.xml

Line 117 in e65a237

<constant name="DISTANCE_MANHATTAN" value="2" enum="CellularDistanceFunction">

godot/doc/classes/AStarGrid2D.xml

Lines 212 to 213 in e65a237

	<constant name="HEURISTIC_MANHATTAN" value="1" enum="Heuristic">
	The [url=https://en.wikipedia.org/wiki/Taxicab_geometry]Manhattan heuristic[/url] to be used for the pathfinding using the following formula:

[Mickeon]

Can't this just be...?

Suggested change

	return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
	return abs(u_pos - v_pos)

or, also:

Suggested change

	return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
	return (u_pos - v_pos).abs()

Potentially same for C# example.

[tetrapod00]

I don't think that is valid code :). You're taking the absolute value of the difference of two vectors and returning it from a function that returns a float.

If you meant to suggest return (u_pos - v_pos).length() or similar, then that would be calculating the Euclidean distance. It's a fine example of using the API but it should also be the default implementation of A*, and is not an example of overriding these functions for Non-Euclidean purposes. My example finds Manhattan/Taxicab distance, in which the distance is the sum of the difference of each cartesian coordinate.

I can see the reasoning for using Euclidean distance as the example, since it's simpler. Would just need to change some of the previous description.

[Mickeon]

In that case this could be shortened to:

Suggested change

	return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
	var absolute = (u_pos - v_pos).abs()
	return absolute.x + absolute.y + absolute.z

But no, it somehow feels more complex than it actually is. My concern is mainly about the length of a single line.

[tetrapod00]

Line length is even more of a problem in the C# example because C# names are more verbose. Despite that, I think these make more sense as single lines

[Mickeon]

Needs a damn good name for the variable, or just a or vec as last resort.

[tetrapod00]

I think the C# example is reasonably idiomatic for the docs already:

• The Mathf namespace is usually inline, most examples don't do using Mathf;.
• toPosition and fromPosition seem idiomatic. toPos and fromPos might be fine too, but the docs seem to prefer spelling out the whole name.

I guess I could split into the two lines like your suggestion just for the sake of making the line length shorter. IDK, the line already seems as concise as it can be given how verbose C# is. I don't see an obvious improvement here.

[tetrapod00]

I shortened toPosition and fromPosition to toPoint and fromPoint.

[Mickeon]

Note that you changed the names only for C#. If that's the intention, it's okay, but the examples need to be consistent.

[tetrapod00]

I think it's okay in this case. We are getting the values from get_point_position()/GetPointPosition(). So either "point" or "position" are reasonable names. u_pos is an idiomatic GDScript name (short for u_position), and toPoint is an idiomatic C# name. Note that the parameters for _compute_cost() are u and v for GDScript but fromID and toID for C#, so there is already some difference in naming built into Godot already.

I could change u_pos to u_point but I don't think that serves anyone, it's longer for no reason. And I'd like to avoid toPos and fromPos because the current C# examples in other classes tend to spell out the full name, and it's more instructive to use the full name.