Add navigation path query parameter limits

[smix8]

Adds navigation path query parameter limits.

Also implements proposal godotengine/godot-proposals#5978
Bugsquad edit: Closes godotengine/godot-proposals#5978

New path query properties

This adds new properties path_return_max_length and path_return_max_radius to NavigationAgent2D/3D and NavigationPathQueryParameters2D/3D.

The new properties can be used to clip the navigation path to a specific path length or radius from the start position ON navmesh. A common request for all kinds of more tactical games with a movement limit.

Also adds get_path_length() function that returns the length of the currently loaded path.

Polygon search limit

This also adds path_search_max_polygons as a maxiumum polygon search cap.
This is set to a similar default as in some other engines that also have a node search cap of 4096.

If this polygon search cap is reached the pathfinding will reset the search and instead build a path from the start position to the polygon that was found the closest to the target position polygon so far.

This prevents path querys from running forever on badly optimized navigation maps with too many polygons. E.g. a target polygon can not be reached and the path search runs over all available polygons to confirm this, causing performance issues. As such this PR can be considered a performance boost for such projects, even if the actual cause of the problem lies elsewhere.

[JekSun97]

Sounds very similar to my proposal - New pathfinding method for huge worlds

[kiroxas]

Maybe I'm not reading this correctly, but it seems like the path and radius limits are only here to clamp the result at the end. We could instead use this to limit iterations during the search path, because it seems like if we have a huge navmesh, this won't help on the performance side, as the whole map will be searched, and then we clamp. We should use it to limit the A* search.

[smix8]

Maybe I'm not reading this correctly, but it seems like the path and radius limits are only here to clamp the result at the end. We could instead use this to limit iterations during the search path, because it seems like if we have a huge navmesh, this won't help on the performance side, as the whole map will be searched, and then we clamp. We should use it to limit the A* search.

It is mostly a postprocessing yes, not a performance optimization. We don't have a hierarchical structure yet that we could use so we would at least need to work with a very big margin to the search.

The problem what else ends up happening when you just stop the path search after the limit is that you will get nonsensical paths all the time with no direction stability should the path update. The paths will commonly go into the completely wrong direction as soon as any navmesh layout is even slighty more complex, and that is unwanted. E.g. Detour pathfinding with cap suffers greatly from this with the search and the only saving grace that it has is the tilemesh as the tilemesh hierarchical connections allows it to at least somehow head into a reasonable direction, and we dont have something similar yet.

[MJacred]

Disclaimer: No comment on the code itself.

---

Note: this PR makes the difference between "navigation finished" and "destination reached" more than ever clearer

---

Tested for 3D:

It's not a bug, but more of a limitation that would require further refinement to fix:
When so. uses max length or max radius, an agent can stop in the middle of a navigation link:

(Agent walking from right-to-left)

Which is by no means wrong.

A problem will occur, though, if the path limit is smaller than your navigation link, because the system only looks at the navigation link start and end position: So it needs to go back to travel along the link.
The required refinement would need to find the nearest point on that line and start from there instead. (I managed to get an agent stuck on a navigation link with this edge case by decreasing the navigation length a bit more than what's depicted below.)

To make this case clearer, I didn't place the start and end position of the navigation link optimally:
(Agent walking from bottom-to-top)

[smix8]

When so. uses max length or max radius, an agent can stop in the middle of a navigation link

Navigation links are all supposed to be script handled that facilitate the agent movement through a link. Outside of the most naive cases links do not function without a script as any map or path update would make it go back to the closest real navmesh polygon.

[AThousandShips]

LGTM

[akien-mga]

Thanks!