Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Using NavigationPathQueryObjects

NavigationPathQueryObjects can be used together with NavigationServer.query_path() to obtain a heavily customized navigation path including optional meta data about the path.

This requires more setup compared to obtaining a normal NavigationPath but lets you tailor the pathfinding and provided path data to the different needs of a project.

NavigationPathQueryObjects consist of a pair of objects, a NavigationPathQueryParameters object holding the customization options for the query and a NavigationPathQueryResult that receives (regular) updates with the resulting path and meta data from the query.

2D and 3D versions of NavigationPathQueryParameters are available as NavigationPathQueryParameters2D and NavigationPathQueryParameters3D respectively.

2D and 3D versions of NavigationPathQueryResult are available as NavigationPathQuerResult2D and NavigationPathQueryResult3D respectively.

Both parameters and result are used as a pair with the NavigationServer.query_path() function.

For the available customization options and their use see the class doc of the parameters.

While not a strict requirement, both objects are intended to be created once in advance, stored in a persistent variable for the agent and reused for every followup path query with updated parameters. This reuse avoids performance implications from frequent object creation if a project has a large quantity of simultaneous agents that regularly update their paths.

GDScript

  1. # prepare query objects
  2. var query_parameters = NavigationPathQueryParameters2D.new()
  3. var query_result  = NavigationPathQueryResult2D.new()
  5. # update parameters object
  6. query_parameters.map = get_world_2d().get_navigation_map()
  7. query_parameters.start_position = agent2d_current_global_position
  8. query_parameters.target_position = agent2d_target_global_position
  10. # update result object
  11. NavigationServer2D.query_path(query_parameters, query_result)
  12. var path: PackedVector2Array = query_result.get_path()

GDScript

  1. # prepare query objects
  2. var query_parameters = NavigationPathQueryParameters3D.new()
  3. var query_result  = NavigationPathQueryResult3D.new()
  5. # update parameters object
  6. query_parameters.map = get_world_3d().get_navigation_map()
  7. query_parameters.start_position = agent3d_current_global_position
  8. query_parameters.target_position = agent3d_target_global_position
  10. # update result object
  11. NavigationServer3D.query_path(query_parameters, query_result)
  12. var path: PackedVector3Array = query_result.get_path()