Navigation

Inherits: Spatial < Node < Object

Mesh-based navigation and pathfinding node.

Description

Provides navigation and pathfinding within a collection of NavigationMeshes. By default, these will be automatically collected from child NavigationMeshInstance nodes, but they can also be added on the fly with navmesh_add. In addition to basic pathfinding, this class also assists with aligning navigation agents with the meshes they are navigating on.

Note: The current navigation system has many known issues and will not always return optimal paths as expected. These issues will be fixed in Godot 4.0.

Tutorials

• 3D Navmesh Demo

Properties

Vector3

up_vector

Vector3( 0, 1, 0 )

Methods

Vector3	get_closest_point ( Vector3 to_point )
Vector3	get_closest_point_normal ( Vector3 to_point )
Object	get_closest_point_owner ( Vector3 to_point )
Vector3	get_closest_point_to_segment ( Vector3 start, Vector3 end, bool use_collision=false )
PoolVector3Array	get_simple_path ( Vector3 start, Vector3 end, bool optimize=true )
int	navmesh_add ( NavigationMesh mesh, Transform xform, Object owner=null )
void	navmesh_remove ( int id )
void	navmesh_set_transform ( int id, Transform xform )

Property Descriptions

• Vector3 up_vector

Default	Vector3( 0, 1, 0 )
Setter	set_up_vector(value)
Getter	get_up_vector()

Defines which direction is up. By default, this is (0, 1, 0), which is the world's "up" direction.

Method Descriptions

• Vector3 get_closest_point ( Vector3 to_point )

Returns the navigation point closest to the point given. Points are in local coordinate space.

---

• Vector3 get_closest_point_normal ( Vector3 to_point )

Returns the surface normal at the navigation point closest to the point given. Useful for rotating a navigation agent according to the navigation mesh it moves on.

---

• Object get_closest_point_owner ( Vector3 to_point )

Returns the owner of the NavigationMesh which contains the navigation point closest to the point given. This is usually a NavigationMeshInstance. For meshes added via navmesh_add, returns the owner that was given (or null if the owner parameter was omitted).

---

• Vector3 get_closest_point_to_segment ( Vector3 start, Vector3 end, bool use_collision=false )

Returns the navigation point closest to the given line segment. When enabling use_collision, only considers intersection points between segment and navigation meshes. If multiple intersection points are found, the one closest to the segment start point is returned.

---

• PoolVector3Array get_simple_path ( Vector3 start, Vector3 end, bool optimize=true )

Returns the path between two given points. Points are in local coordinate space. If optimize is true (the default), the agent properties associated with each NavigationMesh (radius, height, etc.) are considered in the path calculation, otherwise they are ignored.

Note: This method has known issues and will often return non-optimal paths. These issues will be fixed in Godot 4.0.

---

• int navmesh_add ( NavigationMesh mesh, Transform xform, Object owner=null )

Adds a NavigationMesh. Returns an ID for use with navmesh_remove or navmesh_set_transform. If given, a Transform2D is applied to the polygon. The optional owner is used as return value for get_closest_point_owner.

---

• void navmesh_remove ( int id )

Removes the NavigationMesh with the given ID.

---

• void navmesh_set_transform ( int id, Transform xform )

Sets the transform applied to the NavigationMesh with the given ID.