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,207 @@ 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 the closest navigation mesh polygon edge to the 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 funnelling 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**.
122
+
If the polygon corridor is already suboptimal, e.g. due to a suboptimal navigation mesh layout,
123
+
the funnel can snap to unexpected polygon corners causing detours.
124
+
125
+
- 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**.
126
+
127
+
This post-processing is usually only useful when used with strictly tile-like navigation mesh polygons that are all
128
+
evenly sized and where the expected path following is also constrained to cell centers,
129
+
e.g. typical grid game with movement constrained to grid cell centers.
130
+
131
+
- The ``PATH_POSTPROCESSING_NONE`` post-processing returns the path as is how the pathfinding travelled **inside the available polygon corridor**.
132
+
133
+
This post-processing is very useful for debug as it shows how the path search travelled from closest edge point to closet edge point and what polygons it picked.
134
+
A lot of unexpected or suboptimal path results can be immediately explained by looking at this raw path and polygon corridor.
135
+
136
+
Path simplification
137
+
-------------------
138
+
139
+
.. tip::
140
+
141
+
Path simplification can help steering agents or agents that jitter on thin polygon edges.
142
+
143
+
.. figure:: img/path_simplification_diff.webp
144
+
:align:center
145
+
:alt:Path point difference with or without path simplification
146
+
147
+
Path point difference with or without path simplification.
148
+
149
+
If ``simplify_path`` is enabled a variant of the Ramer-Douglas-Peucker path simplification algorithm is applied to the path.
150
+
This algorithm straightens paths by removing less relevant path points depending on the ``simplify_epsilon`` used.
151
+
152
+
Path simplification helps with all kinds of agent movement problems in "open fields" that are caused by having many unnecessary polygon edges.
153
+
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.
154
+
155
+
Path simplification also helps with "steering" agents because they only have more critical corner path points to aim for.
156
+
157
+
.. Warning::
158
+
159
+
Path simplification is an additional final post-processing of the path. It adds extra performance costs to the query so only enable when actually needed.
160
+
161
+
.. note::
162
+
163
+
Path simplification is exposed on the NavigationServer as a generic function. It can be used outside of navigation queries for all kinds of position arrays as well.
164
+
165
+
Path metadata
166
+
-------------
167
+
168
+
.. tip::
169
+
170
+
Disabling unneeded path metadata options can improve performance and lower memory consumption.
171
+
172
+
A path query can return additional metadata for every path point.
173
+
174
+
- The ``PATH_METADATA_INCLUDE_TYPES`` flag collects an array with the primitive information about the point owners, e.g. if a point belongs to a region or link.
175
+
- The ``PATH_METADATA_INCLUDE_RIDS`` flag collects an array with the :ref:`RIDs<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.
176
+
- The ``PATH_METADATA_INCLUDE_OWNERS`` flag 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 retrieve the node behind that object instance, e.g. a NavigationRegion or NavigationLink node.
177
+
178
+
By default all path metadata is collected as this metadata can be essential for more advanced navigation gameplay.
179
+
180
+
- E.g. to know what path point maps to what object or node owner inside the SceneTree.
181
+
- E.g. to know if a path point is the start or end of a navigation link that requires scripted takeover.
182
+
183
+
For the most basic path uses metadata is not always needed.
184
+
Path metadata collection can be selectively disabled to gain some performance and reduce memory consumption.
185
+
186
+
Excluding or including regions
187
+
------------------------------
188
+
189
+
.. tip::
190
+
191
+
Region filters can greatly help with performance on large navigation maps that are region partitioned.
192
+
193
+
Query parameters allow limiting the pathfinding to specific region navigation meshes.
194
+
195
+
If a large navigation map is well partitioned into smaller regions this can greatly help with performance as the
196
+
query can skip a large number of polygons at one of the earliest checks in the path search.
197
+
198
+
- By default and if left empty all regions of the queried navigation map are included.
199
+
- 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.
200
+
- 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.
201
+
- If a region ends up both included and excluded it is considered excluded.
202
+
203
+
Region filters are very effective for performance when paired with navigation region chunks that are aligned on a grid.
204
+
This way the filter can be set to only include the start position chunk and surrounding chunks instead of the entire navigation map.
205
+
206
+
Even if the target might be outside these surrounding chunks (can always add more "rings") the pathfinding will
207
+
try to create a path to the polygon closest to the target.
208
+
This usually creates half-paths heading in the general direction that are good enough,
209
+
all for a fraction of the performance cost of a full map search.
210
+
211
+
The following addition to the basic path query script showcases the idea how to integrate a region chunk mapping with the region filters.
212
+
This is not a full working example.
213
+
214
+
.. tabs::
215
+
.. code-tab:: gdscript 2D GDScript
216
+
217
+
extends Node2D
218
+
219
+
# ...
220
+
221
+
var chunk_id_to_region_rid: Dictionary[Vector2i, RID] = {}
0 commit comments