stingray.NavigationMesh object reference

Description

A navigation mesh in a level.

Constructors and accessors

stingray.Level.navigation_mesh() stingray.LevelResource.create_navigation_mesh() stingray.NavigationMesh.merge()

Other related reference items

	stingray.LevelResource.destroy_navigation_mesh()
	AI

Functions

constrain_to_polygon ( self, p, poly ) : stingray.Vector3, boolean Constrains the point p to the specified polygon, and returns the resulting position.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
p :	stingray.Vector3	The point you want to constrain.
poly :	integer	The index of the polygon.

Returns

stingray.Vector3	The resulting position.
boolean	Returns true if the starting point was outside the polygon and if it was moved in the result.

destroy ( world, mesh ) Destroys the mesh.

Parameters

world :	stingray.World	The world that owns the mesh.
mesh :	stingray.NavigationMesh	The mesh you want to destroy.

Returns

This function does not return any values.

You must only call this function for meshes that are created by NavigationMesh.merge().

Note: It is not necessary to destroy meshes. They are automatically destroyed when the world is destroyed. Only destroy them explicitly if you need the memory sooner.

Other related reference items

stingray.NavigationMesh.merge()

find_nearest_polygon ( self, p ) : integer Finds the polygon in the mesh that is closest to the point p and returns its index.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
p :	stingray.Vector3	The starting point.

Returns

integer

The index of the closest polygon.

This function returns an index even when the point p is outside the mesh.

find_polygon ( self, p ) : integer? Finds the polygon in the mesh that is closest to the point p and returns its index.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
p :	stingray.Vector3	The starting point.

Returns

integer?

The index of the closest polygon, or nil if the point is outside the mesh. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Other related reference items

stingray.NavigationMesh.search()

funnel ( self, path ) : integer[], integer[] Given a polygon path, this function returns two lists with the left and right edge vertices for that path.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
path :	table	A polygon path. For example, a path returned by NavigationMesh.search().

Returns

integer[]	A list of the edge vertices to the left of the path. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.
integer[]	A list of the edge vertices to the right the path. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

This can be used to implement the funnel algorithm. See simple stupid funnel algorithm.

Note: Vertices can be repeated in the returned lists, when the polygons in the list form a fan. The returned lists contain #path - 1 items: i.e. one item for each polygon edge crossed.

is_obstructed ( self, poly ) : boolean Indicates whether or not the node at the specified index in the mesh is obstructed.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
poly :	integer	The index of the polygon.

Returns

boolean

Returns true if the node at the specified index in the mesh is obstructed, or false otherwise.

merge ( world, meshes, merge_tolerance ) : stingray.NavigationMesh Creates a new NavigationMesh by merging all the navigation meshes provided in the meshes table.

Parameters

world :	stingray.World	The world that owns the new mesh.
meshes :	stingray.NavigationMesh[]	A table that lists the navigation meshes you want to merge. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.
merge_tolerance :	number	The maximum distance for merging two nearby vertices, in meters. For example, if merge_tolerance is set to 0.5, any navigation mesh vertices that are within 50 cm of each other are merged together.

Returns

stingray.NavigationMesh

The newly created navigation mesh.

This function call creates a new NavigationMesh that is owned by the world. It is automatically destroyed when the world is destroyed. If you want to destroy the navigation mesh before that, you can use the explicit NavigationMesh.destroy() function.

For the merge to work, all vertices must match up along the merged edges. If one edge has been split, the merge will not work. For example:

Merge will work. Vertices match.

Merge will not work.

Other related reference items

stingray.NavigationMesh.destroy()

num_polygons ( ) : integer Retrieves the number of polygons in the mesh.

Parameters

This function does not accept any parameters.

Returns

integer

The number of polygons in the mesh.

num_vertices ( ) : integer Retrieves the number of vertices in the mesh.

Parameters

This function does not accept any parameters.

Returns

integer

The number of vertices in the mesh.

partial_search ( self, start, end, focus, max_search_nodes, max_distance ) : integer[] Performs an A* search to find the closest path from a starting point or polygon to an ending point, similar to NavigationMesh.search(), but this function always returns a path, even if no path managed to reach the ending point.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
start :	any(number, stingray.Vector3)	The starting point or the index of the starting polygon for the search. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
end :	stingray.Vector3	The ending point for the search. Must be a Vector3.
focus :	number	Specifies how aggressive the search must be. Values greater than 1 mean a more aggressive search that expands fewer nodes, but that might not find the absolute shortest path. For example, with a focus of 1.2, the returned path is allowed to be 1.2 times longer than the shortest possible path.
max_search_nodes :	integer	Specifies the maximum number of graph nodes that are looked at in the search. This is a way of limiting the run time of the search. If you specify a low value, you might not be able to find a path between two nodes, even when such a path exists.
max_distance :	number	Specifies the maximum distance of the search path. If no other path shorter than this to the target is found, an empty table is returned.

Returns

integer[]

Returns the path as a table of polygon indices. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

If the ending point is not reached, the function returns the path that is closest to the end.

polygon_neighbors ( self, poly ) : any(integer, nil)+ Retrieves the indices of the polygons that are neighbours to the polygon with the specified index.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
poly :	integer	The index of the polygon.

Returns

any(integer, nil)+

Returns the indices of the polygons that are neighbours to the polygon with the index poly. Note: If an edge of the polygon does not have a neighbour, the corresponding index is returned as nil. The + notation indicates that there may be one or more instances of the specified type. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

polygon_vertices ( self, poly ) : integer+ Retrieves the indices of the vertices in the polygon with the specified index.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
poly :	integer	The index of the polygon.

Returns

integer+

Returns the indices of the polygon's vertices. The + notation indicates that there may be one or more instances of the specified type.

project_to_polygon ( self, p, poly ) : stingray.Vector3 Projects the starting point p to the plane of the specified polygon.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
p :	stingray.Vector3	The point you want to project.
poly :	integer	The index of the polygon.

Returns

stingray.Vector3

The resulting position.

search ( self, start, start_pos, end, end_pos, focus, max_search_nodes, max_distance ) : integer[] Performs an A* search to find the closest path from a starting point or polygon to an ending point or polygon, and returns the path found.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
start :	number	The index of the starting polygon for the search.
start_pos :	stingray.Vector3	The starting position, used to steer the path search.
end :	number	The index of the ending polygon for the search.
end_pos :	stingray.Vector3	The ending position, used to steer the path search.
focus :	number	Specifies how aggressive the search must be. Values greater than 1 mean a more aggressive search that expands fewer nodes, but that might not find the absolute shortest path. For example, with a focus of 1.2, the returned path is allowed to be 1.2 times longer than the shortest possible path.
max_search_nodes :	integer	Specifies the maximum number of graph nodes that are looked at in the search. This is a way of limiting the run time of the search. If you specify a low value, you might not be able to find a path between two nodes, even when such a path exists.
max_distance :	number	Specifies the maximum distance of the search path. If no other path shorter than this to the target is found, an empty table is returned.

Returns

integer[]

Returns the path as a table of polygon indices, or an empty table if no path is found. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

search ( self, start, end, focus, max_search_nodes, max_distance ) : integer[] Performs an A* search to find the closest path from a starting point or polygon to an ending point or polygon, and returns the path found.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
start :	stingray.Vector3	The starting point for the search. NavigationMesh.find_polygon() is called internally to find the starting polygon.
end :	stingray.Vector3	The ending point for the search. NavigationMesh.find_polygon() is called internally to find the starting polygon.
focus :	number	Specifies how aggressive the search must be. Values greater than 1 mean a more aggressive search that expands fewer nodes, but that might not find the absolute shortest path. For example, with a focus of 1.2, the returned path is allowed to be 1.2 times longer than the shortest possible path.
max_search_nodes :	integer	Specifies the maximum number of graph nodes that are looked at in the search. This is a way of limiting the run time of the search. If you specify a low value, you might not be able to find a path between two nodes, even when such a path exists.
max_distance :	number	Specifies the maximum distance of the search path. If no other path shorter than this to the target is found, an empty table is returned.

Returns

integer[]

Returns the path as a table of polygon indices, or an empty table if no path is found. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

search ( self, start, end, focus, max_search_nodes, max_distance ) : integer[] Performs an A* search to find the closest path from a starting point or polygon to an ending point or polygon, and returns the path found.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
start :	number	The index of the starting polygon for the search.
end :	number	The index of the ending polygon for the search.
focus :	number	Specifies how aggressive the search must be. Values greater than 1 mean a more aggressive search that expands fewer nodes, but that might not find the absolute shortest path. For example, with a focus of 1.2, the returned path is allowed to be 1.2 times longer than the shortest possible path.
max_search_nodes :	integer	Specifies the maximum number of graph nodes that are looked at in the search. This is a way of limiting the run time of the search. If you specify a low value, you might not be able to find a path between two nodes, even when such a path exists.
max_distance :	number	Specifies the maximum distance of the search path. If no other path shorter than this to the target is found, an empty table is returned.

Returns

integer[]

Returns the path as a table of polygon indices, or an empty table if no path is found. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown.

Other related reference items

stingray.NavigationMesh.funnel() stingray.NavigationMesh.partial_search()

set_obstructed ( self, poly, is_obstructed ) Sets the obstruction state for the polygon at the specified index in the mesh.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
poly :	integer	The index of the polygon.
is_obstructed :	boolean	Use true to mark the polygon as obstructed, or false otherwise.

Returns

This function does not return any values.

update_polygon ( self, p, poly ) : stingray.Vector3, stingray.Vector3, integer, boolean Used to move a character on the navigation mesh.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
p :	stingray.Vector3	The point you want to localize in the mesh.
poly :	integer	The index of the polygon occupied by the character in the previous frame.

Returns

stingray.Vector3	The new position of the character (possibly constrained to the mesh).
stingray.Vector3	The normal of the polygon the character is now on.
integer	The index of the polygon the character is now on.
boolean	Returns true if the character needed to be constrained (collided with the mesh edges), or false otherwise.

Given a new point p and the index poly of the polygon where the character was on the last frame, this function computes which polygon the character is now on, and constrains the character's position to the navigation mesh if necessary.

A typical use case is:

self.position = self.position + move_vector
self.position, self.normal, self.poly = NavigationMesh.update_polygon(self.mesh, self.position, self.poly)

vertex ( self, v ) : stingray.Vector3 Retrieves the position of the vertex with the specified index.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
v :	integer	The index of the vertex.

Returns

stingray.Vector3

The position of the vertex.

visualize_last_search ( self, lines ) Visualizes the last search using the specified LineObject for debugging purposes.

Parameters

self :	stingray.NavigationMesh	Specifies the object instance that this function will act on. You must always provide this self parameter when you call this function. You must use the dot . calling syntax, not the object-oriented colon : calling syntax.For more information, see this Stingray help topic, or this page in the Lua documentation.
lines :	stingray.LineObject	Specifies the LineObject that will be used to draw the path.

Returns

This function does not return any values.

The found path is drawn using yellow lines and the other parts of the path (nodes that were expanded, but not used) are drawn using blue lines.

This function is only available in development builds.