You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -70,3 +99,197 @@ has a large quantity of simultaneous agents that regularly update their paths.
70
99
var path: PackedVector3Array = query_result.get_path()
71
100
72
101
return path
102
+
103
+
Path postprocessing options
104
+
---------------------------
105
+
106
+
.. figure:: img/path_postprocess_diff.webp
107
+
:align:center
108
+
:alt:Path post-processing differences depending on navigation mesh polygon layout
109
+
110
+
Path post-processing differences depending on navigation mesh polygon layout.
111
+
112
+
A path query search travels from closest navigation mesh polygon edge to closest edge along the available polygons.
113
+
If possible it builds a polygon corridor towards the target position polygon.
114
+
115
+
This raw "search" polygon corridor path is not very optimized and usually a bad fit for agents to travel along.
116
+
E.g. the closest edge point on a navigation mesh polygon might cause a huge detour for agents on larger polygons.
117
+
In order to improve the quality of paths returned by the query various ``path_postprocessing`` options exist.
118
+
119
+
- The ``PATH_POSTPROCESSING_CORRIDORFUNNEL`` post processing shortens paths by funneling paths around corners **inside the available polygon corridor**.
120
+
121
+
This is the default post processing and usually also the most useful as it gives the shortest path result **inside the available polygon corridor**. If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout, the funnel can snap to unexpected polygon corners causing detours.
122
+
123
+
- The ``PATH_POSTPROCESSING_EDGECENTERED`` post processing forces all path points to be placed in the middle of the crossed polygon edges **inside the available polygon corridor**.
124
+
125
+
This post processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all evenly sized and where the excepted path following is also constrained to cell centers, e.g. typical grid game with movement constrained to grid cell centers.
126
+
127
+
- The ``PATH_POSTPROCESSING_NONE`` post processing returns the path as is how the pathfinding traveled **inside the available polygon corridor**.
128
+
129
+
This post processing is very useful for debug as it shows how the path search traveled from closest edge point to closet edge point and what polygons it picked.
130
+
A lot of unexpected or suboptimal path results can be immediately explained by looking at this raw path and polygon corridor.
131
+
132
+
Path simplification
133
+
-------------------
134
+
135
+
.. tip::
136
+
137
+
Path simplification can help steering agents or agents that jitter on thin polygon edges.
138
+
139
+
.. figure:: img/path_simplification_diff.webp
140
+
:align:center
141
+
:alt:Path point difference with or without path simplification
142
+
143
+
Path point difference with or without path simplification.
144
+
145
+
If ``simplify_path`` is enabled a variant of the Ramer-Douglas-Peucker path simplification algorithm is applied to the path.
146
+
This algorithm straightens paths by removing less relevant path points depending on the used ``simplify_epsilon``.
147
+
148
+
Path simplification helps with all kinds of agent movement problems in "open fields" that are caused by having many unnecessary polygon edges.
149
+
E.g. a terrain mesh when baked to a navigation mesh can cause an excessive polygon count due to all the small (but for pathfinding almost meaningless) height variations in the terrain.
150
+
151
+
Path simplification also helps with "steering" agents because they only have more critical corner path points to aim for.
152
+
153
+
.. Warning::
154
+
155
+
Path simplification is an additional final post-processing of the path. It adds extra performance cost the query so only enabled the simplification when actually needed.
156
+
157
+
.. note::
158
+
159
+
Path simplification is exposed on the NavigationServer as a generic function. It can be used outside of navigation queries for all kinds of position holding arrays as well.
160
+
161
+
Path meta data
162
+
--------------
163
+
164
+
.. tip::
165
+
166
+
Disabling unneeded path meta data options can improve performance and lower memory consumption.
167
+
168
+
A path query can return additional meta data for every path point.
169
+
170
+
- Flag ``PATH_METADATA_INCLUDE_TYPES`` collects an array with the primitive information about the point owners, e.g. if a point belongs to a region or link.
171
+
- Flag ``PATH_METADATA_INCLUDE_RIDS`` collects an array with the :ref:`RID<class_RID>` of the point owners. Depending on point owner primitive, these RIDs can be used with the various NavigationServer functions related to regions or links.
172
+
- Flag ``PATH_METADATA_INCLUDE_RIDS`` collects an array with the ``ObjectIDs`` of the point owners. These object ids can be used with :ref:`@GlobalScope.instance_from_id()<class_@GlobalScope_method_instance_from_id>` to receive the node behind that object instance, e.g. a NavigationRegion or NavigationLink node.
173
+
174
+
By default all path meta data is collected as this meta data can be essential for more advanced navigation gameplay.
175
+
176
+
- E.g. to know what path point maps to what object or node owner inside the SceneTree.
177
+
- E.g. to know if a path point is the start or end of a navigation link that requires scripted takeover.
178
+
179
+
For the most basic path uses meta data is not always needed.
180
+
Path meta data collection can be selectively disabled to gain some performance and reduce memory consumption.
181
+
182
+
Excluding or including regions
183
+
------------------------------
184
+
185
+
.. tip::
186
+
187
+
Region filters can greatly help with performance on large navigation maps that are region partitioned.
188
+
189
+
Query parameters allow to limit the pathfinding to specific region navigation meshes.
190
+
191
+
If a large navigation map is well partitioned into smaller regions this can greatly help with performance as the query can skip a large amount of polygons at one of the earliest checks in the path search.
192
+
193
+
- By default and if left empty all regions of the queried navigation map are included.
194
+
- If a region :ref:`RID<class_RID>` is added to the ``excluded_regions`` array the region's navigation mesh will be ignored in the path search.
195
+
- If a region :ref:`RID<class_RID>` is added to the ``included_regions`` array the region's navigation mesh will be considered in the path search and also all other regions not included will be ignored as well.
196
+
- If a region ends up both included and excluded it is considered excluded.
197
+
198
+
Region filters are very effective for performance when paired with navigation region chunks that are aligned on a grid.
199
+
This way the filter can be set to only include the start position chunk and surrounding chunks instead of the entire navigation map.
200
+
201
+
Even if the target might be outside these surrounding chunks (can always add more "rings") the pathfinding will try to create a path to the polygon closest to the target.
202
+
This usually creates half-paths heading in the general direction that are good enough, all for a fraction of the performance that a full map search would cost.
203
+
204
+
The following addition to the basic path query script showcases the idea how to integrate a region chunk mapping with the region filters. This is not a full working example.
205
+
206
+
.. tabs::
207
+
.. code-tab:: gdscript 2D GDScript
208
+
209
+
extends Node2D
210
+
211
+
# ...
212
+
213
+
var chunk_id_to_region_rid: Dictionary[Vector2i, RID] = {}
Sensible set limits can greatly help with performance on large navigation maps, especially when targets end up as not reachable.
270
+
271
+
.. figure:: img/path_clip_and_limits.gif
272
+
:align:center
273
+
:alt:Clipping returned paths to specific distances
274
+
275
+
Clipping returned paths to specific distances.
276
+
277
+
Query parameters allow to clip returned paths to specific lengths.
278
+
These options clip the path as a post-processing. The path is still searched as if at full length, so will have the same quality as if returned at full length.
279
+
Path length clips can be helpful to create paths that better fit constrained gameplay, e.g. tactical games with limited movement ranges.
280
+
281
+
- Property ``path_return_max_length`` can be used to clip the returned path to a specific max length.
282
+
- Property ``path_return_max_radius`` can be used to clip the returned path inside a circle (2D) or sphere (3D) radius around the start position.
283
+
284
+
Query parameters allow to limit the path search to only searched up to a specific distance or a specific amount of searched polygons.
285
+
These options are for performance and affect the path search directly.
286
+
287
+
- Property ``path_search_max_distance`` can be used to stop the path search when going over this distance from the start position.
288
+
- Property ``path_search_max_polygons`` can be used to stop the path search when going over this searched polygon amount.
289
+
290
+
When the path search is stopped by reaching a limit the path resets and creates a path from the start position polygon to the so far found polygon that is closest to the target position.
291
+
292
+
.. warning::
293
+
294
+
While good for performance, if path search limit values are set too low they can affect the path quality very negatively.
295
+
Depending on polygon layout and search pattern the returned paths might go into completely wrong directions instead of the direction of the target.
0 commit comments