Using NavigationLayers

NavigationLayers are an optional feature to further control which navigation meshes are considered in a path query. They work similar to how physics layers control collision between collision objects or how visual layers control what is rendered to the Viewport.

NavigationLayers can be named in the ProjectSettings the same as physics layers or visual layers.

../../_images/navigationlayers_naming.png

If a region has not a single compatible navigation layer with the navigation_layers parameter of a path query this regions navigation mesh will be skipped in pathfinding. See Using NavigationPaths for more information on querying the NavigationServer for paths.

NavigationLayers are a single int value that is used as a bitmask. Many navigation related nodes have set_navigation_layer_value() and get_navigation_layer_value() functions to set and get a layer number directly without the need for more complex bitwise operations.

In scripts the following helper functions can be used to work with the navigation_layers bitmask.

2D GDScript3D GDScript

  1. func change_layers():
  2.     var region: NavigationRegion2D = get_node("NavigationRegion2D")
  3.     # enables 4-th layer for this region
  4.     region.navigation_layers = enable_bitmask_inx(region.navigation_layers, 4)
  5.     # disables 1-rst layer for this region
  6.     region.navigation_layers = disable_bitmask_inx(region.navigation_layers, 1)
  8.     var agent: NavigationAgent2D = get_node("NavigationAgent2D")
  9.     # make future path queries of this agent ignore regions with 4-th layer
  10.     agent.navigation_layers = disable_bitmask_inx(agent.navigation_layers, 4)
  12.     var path_query_navigation_layers: int = 0
  13.     path_query_navigation_layers = enable_bitmask_inx(path_query_navigation_layers, 2)
  14.     # get a path that only considers 2-nd layer regions
  15.     var path: PoolVector2Array = NavigationServer2D.map_get_path(
  16.         map,
  17.         start_position,
  18.         target_position,
  19.         true,
  20.         path_query_navigation_layers
  21.         )
  23. static func is_bitmask_inx_enabled(_bitmask: int, _index: int) -> bool:
  24.     return _bitmask & (1 << _index) != 0
  26. static func enable_bitmask_inx(_bitmask: int, _index: int) -> int:
  27.     return _bitmask | (1 << _index)
  29. static func disable_bitmask_inx(_bitmask: int, _index: int) -> int:
  30.     return _bitmask & ~(1 << _index)
  1. func change_layers():
  2.     var region: NavigationRegion3D = get_node("NavigationRegion3D")
  3.     # enables 4-th layer for this region
  4.     region.navigation_layers = enable_bitmask_inx(region.navigation_layers, 4)
  5.     # disables 1-rst layer for this region
  6.     region.navigation_layers = disable_bitmask_inx(region.navigation_layers, 1)
  8.     var agent: NavigationAgent3D = get_node("NavigationAgent3D")
  9.     # make future path queries of this agent ignore regions with 4-th layer
  10.     agent.navigation_layers = disable_bitmask_inx(agent.navigation_layers, 4)
  12.     var path_query_navigation_layers: int = 0
  13.     path_query_navigation_layers = enable_bitmask_inx(path_query_navigation_layers, 2)
  14.     # get a path that only considers 2-nd layer regions
  15.     var path: PoolVector3Array = NavigationServer3D.map_get_path(
  16.         map,
  17.         start_position,
  18.         target_position,
  19.         true,
  20.         path_query_navigation_layers
  21.         )
  23. static func is_bitmask_inx_enabled(_bitmask: int, _index: int) -> bool:
  24.     return _bitmask & (1 << _index) != 0
  26. static func enable_bitmask_inx(_bitmask: int, _index: int) -> int:
  27.     return _bitmask | (1 << _index)
  29. static func disable_bitmask_inx(_bitmask: int, _index: int) -> int:
  30.     return _bitmask & ~(1 << _index)

Changing navigation layers for path queries is a performance friendly alternative to enabling / disabling entire navigation regions. Compared to region changes a navigation path query with different navigation layers does not trigger large scale updates on the NavigationServer.

Changing the navigation layers of NavigationAgent nodes will have an immediate effect on the next path query. Changing the navigation layers of regions will have an effect after the next NavigationServer sync.

User-contributed notes

Please read the User-contributed notes policy before submitting a comment.

Previous Next