stingray.GwNavWorld object reference

Description

Represents a Navigation world.

Constructors and accessors

stingray.GwNavWorld.create()

Related sample code

Appkit: /app.lua

Other related reference items

stingray.GwNavAStar.create() stingray.GwNavBot.create() stingray.GwNavBoxObstacle.create() stingray.GwNavBoxObstacle.create_exclusive() stingray.GwNavCylinderObstacle.create() stingray.GwNavCylinderObstacle.create_exclusive() stingray.GwNavGeneration.add_generated_navdata_to_world() stingray.GwNavGeneration.add_navdata_file_to_world() stingray.GwNavGraph.create() stingray.GwNavQueries.diskcango() stingray.GwNavQueries.diskcast() stingray.GwNavQueries.inside_position_from_outside_position() stingray.GwNavQueries.move_on_navmesh() stingray.GwNavQueries.raycango() stingray.GwNavQueries.raycast() stingray.GwNavQueries.raycast_full_3d() stingray.GwNavQueries.tag_volumes_from_position() stingray.GwNavQueries.triangle_from_position() stingray.GwNavSmartObjectInterval.can_traverse_smartobject() stingray.GwNavSmartObjectInterval.create() stingray.GwNavTagVolume.create() stingray.GwNavTraversal.get_seed_triangle() stingray.GwNavTraverseLogicData.create()

Gameware Navigation

Related help topics

	Release Notes > Stingray 1.4 Release Notes
	Creating Gameplay > AI and pathfinding > Set up levels to use Gameware Navigation
	Creating Gameplay > AI and pathfinding > Navigation options

Functions

add_navdata ( database_or_world, navdata ) : stingray.GwNavData Adds the NavData to the specified GwNavWorld.

Parameters

database_or_world :	any(stingray.GwNavWorld, stingray.GwNavDatabase)	The GwNavDatabase the navdata will be added to. If a GwNavWorld, the default GwNavDatabase will be used. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
navdata :	string	The resource name of the NavData to add without database suffix.

Returns

stingray.GwNavData

The loaded navdata if successfully loaded, nil otherwise.

allow_smartobject ( self, smartobject_id ) Allows a smartobject to be traversed.

Parameters

self :	stingray.GwNavWorld	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.
smartobject_id :	number	The smartobject ID to allow to be traversed

Returns

This function does not return any values.

create ( transform, database_count ) : stingray.GwNavWorld Creates and returns a new GwNavWorld.

Parameters

transform :	stingray.Matrix4x4?	Specifies the transform for the new GwNavWorld in 3D space. Optional. If omitted, the GwNavWorld uses the identity matrix. The ? notation indicates that this type is optional: there may be zero or one instances of it.
database_count :	integer?	Optional. Number of database that will be used. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.GwNavWorld

The new GwNavWorld.

database ( self, database_id ) : stingray.GwNavDatabase Returns the GwNavDatabase of the given id if it exists, nil otherwise.

Parameters

self :	stingray.GwNavWorld	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.
database_id :	integer	The id of the database

Returns

stingray.GwNavDatabase

A pointer to the Kaim::Database if it exists.

database_count ( self ) : number Gives the number of Database the GwNavWorld as created with.

Parameters

self :

stingray.GwNavWorld

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.

Returns

number

The number of Database the GwNavWorld as created with.

destroy ( self ) Destroys the specified GwNavWorld.

Parameters

self :

stingray.GwNavWorld

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.

Returns

This function does not return any values.

enable_crowd_dispersion ( self ) Enables crowd dispersion for a GwNavWorld.

Parameters

self :

stingray.GwNavWorld

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.

Returns

This function does not return any values.

forbid_smartobject ( self, smartobject_id ) Forbids a smartobject to be traversed, if the cost was set via set_smartobject_cost_multiplier() it will remain if allow_smartobject() is called afterwards.

Parameters

self :	stingray.GwNavWorld	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.
smartobject_id :	number	The smartobjectID to forbid to be traversed

Returns

This function does not return any values.

init_async_update ( self ) Causes the World to create a worker thread.

Parameters

self :

stingray.GwNavWorld

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.

Returns

This function does not return any values.

important - This must be called if you intend to call kick_async_update()/join_async_update().

is_crowd_dispersion_enabled ( self ) : boolean Enables crowd dispersion for a GwNavWorld.

Parameters

self :

stingray.GwNavWorld

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.

Returns

boolean

true if stingray.GwNavWorld.enable_crowd_dispersion was called

join_async_update ( self ) Blocks until the async update started by kick_update() has finished.

Parameters

self :

stingray.GwNavWorld

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.

Returns

This function does not return any values.

important - A call to this function should map 1-to-1 to a call to kick_async_update().

kick_async_update ( self, delta_time ) causes the World to be updated on a worker thread.

Parameters

self :	stingray.GwNavWorld	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.
delta_time :	number	The time step that the GwNavWorld should use when updating, in seconds.

Returns

This function does not return any values.

important - No Navigation related functions must be called before calling join_update() (see below), otherwise crashes or other undefined behavior will occur.

register_all_navgraphedges_for_crowd_dispersion ( self, nav_graph ) Registers a GwNavGraph for Crowd Dispersion.

Parameters

self :	stingray.GwNavWorld	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.
nav_graph :	stingray.GwNavGraph	The GwNavGraph to register for Crowd Dispersion.

Returns

This function does not return any values.

register_tagvolume_for_crowd_dispersion ( self, tag_volume ) Registers a GwNavTagVolume for Crowd Dispersion.

Parameters

self :	stingray.GwNavWorld	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.
tag_volume :	stingray.GwNavTagVolume	The GwNavTagVolume to register for crowd dispersion.

Returns

This function does not return any values.

remove_navdata ( navdata ) Removes the NavData from the specified GwNavWorld.

Parameters

navdata :

stingray.GwNavData

The filename of the NavData resource to add.

Returns

This function does not return any values.

set_dynamicnavmesh_budget ( self, budget ) Sets the budget per frame, in seconds for this world.

Parameters

self :	stingray.GwNavWorld	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.
budget :	number	The budget in seconds, for the dynamic NavMesh.

Returns

This function does not return any values.

The world will not exceed the specified budget when processing the dynamic navmesh.

set_pathfinder_budget ( self, budget ) Sets the budget per frame, in seconds for this world.

Parameters

self :	stingray.GwNavWorld	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.
budget :	number	The budget in seconds, for pathfinding.

Returns

This function does not return any values.

The world will not exceed the specified budget when processing pathfinding requests.

set_smartobject_cost_multiplier ( self, smartobject_id, cost_multiplier ) Allows us to specify which cost multiplier must be used when traversing a given smartobject.

Parameters

self :	stingray.GwNavWorld	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.
smartobject_id :	number	The smartobjectID to set.
cost_multiplier :	number	The associated cost multiplier of this smartobject.

Returns

This function does not return any values.

unset_smartobject ( self, smartobject_id ) Allows to remove a smartobject from the world' smartobject table.

Parameters

self :	stingray.GwNavWorld	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.
smartobject_id :	number	The smartobjectID to unset.

Returns

This function does not return any values.

If the smartobject_id is encountered but no cost was set, it will be traversed.

update ( self, delta_time ) Updates the specified GwNavWorld.

Parameters

self :	stingray.GwNavWorld	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.
delta_time :	number	The time step that the GwNavWorld should use when updating, in seconds.

Returns

This function does not return any values.

Development only

The elements in this group are only available in development builds.

Do not use them in your final builds.

build_database_visual_geometry ( database_or_world ) Rebuilds the debug rendering representation of the database for the specified GwNavWorld.

Parameters

database_or_world :

any(stingray.GwNavWorld, stingray.GwNavDatabase)

The GwNavDatabase to use. If a GwNavWorld, the default GwNavDatabase will be used. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

This function does not return any values.

database_tile_count ( database_or_world ) : integer Returns the number of tiles in the database visual representation of the specified GwNavWorld.

Parameters

database_or_world :

any(stingray.GwNavWorld, stingray.GwNavDatabase)

The GwNavDatabase to use. If a GwNavWorld, the default GwNavDatabase will be used. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

integer

The number of tiles in the database.

database_tile_triangle_count ( database_or_world, tile_index ) : integer Returns the number of triangles in the given tile in the database visual representation of the specified GwNavWorld.

Parameters

database_or_world :	any(stingray.GwNavWorld, stingray.GwNavDatabase)	The GwNavDatabase to use. If a GwNavWorld, the default GwNavDatabase will be used. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
tile_index :	integer	The index of the tile to get the triangle count for.

Returns

integer

The number of triangles in the tile.

database_triangle ( database_or_world, tile_index, triangle_index ) : stingray.Vector3?, stingray.Vector3?, stingray.Vector3?, stingray.Quaternion? Returns the specified triangle in the specified tile in the database visual representation of the specified GwNavWorld, or nil

Parameters

database_or_world :	any(stingray.GwNavWorld, stingray.GwNavDatabase)	The GwNavDatabase to use. If a GwNavWorld, the default GwNavDatabase will be used. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
tile_index :	integer	The index of the tile in the database.
triangle_index :	integer	The index of the triangle in the tile.

Returns

stingray.Vector3?	Vertex of the triangle if found, nil otherwise. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector3?	Vertex of the triangle if found, nil otherwise. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Vector3?	Vertex of the triangle if found, nil otherwise. The ? notation indicates that this type is optional: there may be zero or one instances of it.
stingray.Quaternion?	The Color of the triangle if found, nil otherwise. The ? notation indicates that this type is optional: there may be zero or one instances of it.

init_visual_debug_server ( self, server_port ) Starts the visual debug server for the specified GwNavWorld with the specified port.

Parameters

self :	stingray.GwNavWorld	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.
server_port :	number	The port that the GwNavWorld should use when creating it's visual debug server.

Returns

This function does not return any values.

set_visual_debug_camera_transform ( self, position, look_at, up ) It is possible to control the camera in the visual debugger via this function.

Parameters

self :	stingray.GwNavWorld	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.
position :	stingray.Vector3	The wanted position of the camera.
look_at :	stingray.Vector3	The position the camera should point at.
up :	stingray.Vector3	The "up" axis of the camera.

Returns

This function does not return any values.

In this way we can see the POV of a bot or any other interesting POV.

visual_debug_draw_line ( self, display_list_name, group_name, start, end, color ) Draw a line into the NavigationLab.

Parameters

self :	stingray.GwNavWorld	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.
display_list_name :	string	Name of the display list.
group_name :	string	Group the display list belongs to.
start :	stingray.Vector3	Start position of the line.
end :	stingray.Vector3	End position of the line.
color :	stingray.Quaternion	Line color.

Returns

This function does not return any values.

visual_debug_draw_text ( self, display_list_name, group_name, text, position, color ) Draw a 3d text into the NavigationLab.

Parameters

self :	stingray.GwNavWorld	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.
display_list_name :	string	Name of the display list.
group_name :	string	Group the display list belongs to.
text :	string	Text to draw.
position :	stingray.Vector3	Position of the text.
color :	stingray.Quaternion	Text color.

Returns

This function does not return any values.