Navigation Cvars and commands

Introduction

The tables below contains console variables and console commands used to configure the Recast's navigation meshes, debug draw and pathfinding. Note, that some of these are intended for development and testing purposes only.
See also Navigation settings for details about configuring the navigation meshbuilding process.

General

Name	Type	Arguments/Limits	Description
wh_ai_OverrideMNM	integer	0,1	Turns on/off the MNM override (i.e. Recast and Detour is used instead of Cry's MNM and pathfinding). By default the override is turned on.
wh_ai_AllowPathFollowShorcuting	integer	0,1	Allows smart path follower to shortcut the path using the nav mesh. The default value is 1 (shortcuts are allowed), since it is Cry's default behavior. Note: this cvar applies only when wh_ai_OverrideMNM is se to 1.

Navmesh build

Building of navmesh is mostly controlled by the Navigation settings set in the Scripts/AI/Navigation.xml file. 

Name	Type	Arguments/Limits	Description
wh_ai_AdvancedNavMeshSpanMerge	integer	0,1	Turns off modified merging of voxel spans during the geometry rasterization into voxels. Introduced to solve the issues of small planks, logs and similar objects placed on the terrain that are by themselves unwalkable. In certain tiles causes the nav mesh build to be slower. By default the cvar is set to 1.

Recast debug draw

Debug draw locator

If there is an entity named "RecastDebugLocator" present in the level, its positon is used in debug draw:

• It marks the tile that can be debugged in detail (see wh_ai_RecastTileDebugDraw cvar)
• The tile corresponding with the position of RecastDebugLocator can be manually rebuilt by command wh_ai_RebuildDebugTile

Name	Type	Arguments/limits	Description
wh_ai_RecastDebugDraw	integer	Id of the navigation agent that is debug draw.	When set to a valid ID of a navigation agent type, navigation mesh for this agent type is drawn. With the default value 0 the debug draw is turned off (since 0 is not valid navigation agent type ID). Use values 1,2 ... to display navigation mesh for different agents.
wh_ai_RecastTileDebugDraw	integer	Type of debug draw that is used for the debug tile.	When set to nonzero value, corresponding debug draw for a single tile is used. Which tile is drawn is controlled by a position of entity named "RecastDebugLocator". The value is used in cooperation wh_ai_RecastDebugDraw (which controls the agent type that is debug drawn). Use the following values of wh_ai_RecastTileDebugDraw for different nav mesh generation stages: - tile debug draw is turned of - displays raw voxels with colors encoding areas (materials) - displays raw voxels with colors encoding walkable/unwalkable voxels - compacted voxels with colors encoding areas (materials) - compacted voxels with colors encoding walkable/unwalkable voxels - tile cache layer set - only the voxels saved in tile cache are displayed. Each layer has different color. - tile cache layer areas - the voxels in tile cache with colors encoding the areas (materials) - tile cache layer regions - the continuous regions formed by the voxels in tile cache (it is a preprocess stage before creating nav mesh polygons) - tile cache layer regions with connections and portal information - same as above, but information about neighbouring voxels (or voxels forming portals to neighbouring tiles) - tile cache layer contours - countours extracted from the regions (these contours are split into polygons) - tile cache layer mesh - final mesh for the tile
wh_ai_RecastDebugDrawSegmentSize	float	Size of the nav mesh segment that is drawn.	Value determines the size of the segment of the navigation mesh that is drawn. The drawn is centered around the entity with name "RecastDebugLocator" or if the entity is not found, around camera. If the value is negative, the whole mesh is drawn. Use for large meshes when it is not possible to draw the whole mesh.
wh_ai_RecastDebugDrawMemory	int		0 -turned off. 1 - displays the memory consumed by navigation mesh and tile cache.
wh_ai_RecastDebugDrawZOffset	float		The vertical offset that is added to the nav mesh polygons for debug draw (use to prevent Z-fight and clearly see the navigation mesh)
wh_ai_RecastDebugDrawOpenList	integer		The polygons that have been searched in the testing path find (see below) are highlighted. 0-turned off, 1-turned on
wh_ai_RecastDebugDrawOpenListCosts	integer		0 - turned off. 1 - when open list is draw, for each polygon included in open list, the cost of this polygon is displayed.
wh_ai_RecastDebugDrawPolyLinks	float	lenght of the drawn poly links	0 - turned offf, normal boundary contrours for nav mesh polygons are drawn >0 - draws color coded poly boundaries and poly links (red), the lenght of the drawn links is controlled by the value of the cvar Collor coded poly boundaries/edges: White - normal inner edge between two polygons of the same tile Yellow - border edge, that is not connected to any polygon Orange - portal edge that may be connected to polygon from other tile
wh_ai_AreaToNSOMappingDebugDraw	int	Nav agent id to draw	Draws the areas that are linked to NSO. Above each object there is a list of areas printed
wh_ai_AreaToNSOMappingDebugDrawDistance	float	Distance	Distance from camera in which the area to NSO mapping is drawn

Pathfinding

Name	Type	Arguments/Limis	Description
wh_ai_PathFinderEnabled	integer	0,1	Turns on/off the processing of path finding requests. When disabled the requests are queued but not processed. Used to simulate the situation when path finder is overflown with requests and can't keep up.
wh_ai_PathFinderDebugDraw	integer	0,1,2,3	Debug draw for path finder: 0 - debug draw is off 1 - displays currently processed requests 2 - displays requests waiting in queue 3 - displays both processed and queued requests
wh_ai_PathFinderDebugDrawDetails	integer	Pathfinding request ID	Draws details of selected path finding request. Displays the type of the request and most important information (e.g. start pos, end pos, element include flags, ...) Also draws debug spheres at the locations. The colors are: green - start pos, yellow - end pos, red - flee center, in case of flee pathfinding.
wh_ai_UseEdgeCrossingPrediction	integer	0,1	Turns on/off the edge crossing prediction heuristic when finding the crossing point between two polygons. By default is turned on.
wh_ai_UseLinkIndexInOpenList	integer	0.1	Turn on/off the heuristic that includes the polygon edges into the A* open list. By default is turned off and it is recommended ot keep it that way. Though the path finding results are slightly better, the increase in open list size is rather dramatic.
wh_ai_PathfindingAutoAllowedSmartObjects	integer	0,1	Turn on/off the usage of only allowed smart objects - the ones connected to the start and end hierarchy.
wh_ai_FillPathFindingGapWithHistory	integer	0,1	The gap caused by movement of NPC during path finding (i.e. the path finding starts from one point, but when finished, the NPC starts moving from other point) is filled with the points from NPC's movement history.
wh_ai_FindPathGeneratedNSOFleeCostMultiplier	float	Greater than 1.0	The multipler used for generated NSO (if allowed) during flee path finding. This allows for little avoiding of the generated NSOs (ledges) when there is a way without the ledge nearby. Use large values to allow longer detours without using the generated NSOs. Default value is 5.

Testing path find

To debug path finding there is a way to execute single pathfind and display results (using the debug draw). To execute path find use "wh_ai_FindPath" command. The argument format is:

wh_ai_FindPath sX sY sZ eX eY eZ

where [sX, sY, sZ] is the starting position and [eX, eY, eZ] is end position of the path find.

Alternatively you can use two entities named "DetourStart" and "DetourEnd" which mark the starting and ending position of the path find. When the position of the entity changes the path is automatically recomputed. To recompute the path without moving the entities, use wh_ai_FindPath command with no parameters.

Name	Type	Arguments/limits	Description
wh_ai_FindPathAgent	integer	Id of the navigation agetn	Determines the navigation agent that is used for the testing pathfind. Use values 1,2... to switch between different navigation agents. The default value of 0 is not a valid navigation agent type ID.
wh_ai_FindPathDraw	integer	0,1,2	Determines how is the testing path find visualized: - highlights the polygons that form the path - draws the smoothed path from iterative string pulling (not used in the game) - draw the smoothed path produced by a single string pull (such paths will be used in game)
wh_ai_FindPathUseMaterials	integer	0,1	Turn on/off the material information for testing path finding. Default is 0
wh_ai_FindPathHeuristicMultiplier	float	positive floats	Sets the heuristic multiplier used in testing path find. Default value is 0.999. Note that for correct results (i.e. path finding finds the shortest path), the value must be lower than 1.0. Otherwise the heuristic cost may be greater than the actual cost and the A* will try to avoid this path (even though it is infact the shortest path). On the other hand, greater values can be used for more aggresive, fast searches (if you can sacrifice the precision)
wh_ai_FindPathDrawShortcutted	integer	0,1,2	Turns on/off the draw of nav mesh shortcutting for nav mesh path points found between DetourStart and DetourEnd. 0 - off 1 - on (shortcut path is drawn) 2 - both original path and shortcut paths are drawn (shortcut path is orange)
wh_ai_FindPathDrawShortcuttedStraightLineThreshold	float	0.95	Angle threshold used in debug of the shortcutting. The value is cosine of angle.

Testing sliced path find

The testing path find can be executed in the sliced mode - requiring multiple updates, in each update few iterations of A* algorithm are done. Usually sliced path finding is used to balance the load and prevent stalling when one path find takes too long. However, it can be used for visual debugging of the path find - you can nicely see the order in which the polygons are processed. To use sliced find path there are three commands:

• wh_ai_FindPathSliced - starts the sliced path find. The parameters are the same as for wh_ai_FindPath. Or you can used no parameters to start path find between DetourStart and DetourEnd entities.
• wh_ai_UpdateFindPathSliced - updates the sliced path find by a number of iterations given by wh_ai_FindPathSlicedIterations cvar
• wh_ai_CancelFindPathSliced - cancels the sliced find path. You must cancel the sliced find path before you execute a non sliced path find.

Name	Type	Arguments/Limits	Description
wh_ai_FindPathSlicedIterations	integer	positive integer values	Controls the number of iterations done in one wh_ai_UpdateFindPathSliced command. Use value 1 for real detailed debugging.

Testing global path find

Similar to testing path find, more complex path find that includes the paths to the search can be executed. It is once again controlled by a pair of entities names "PathStart" and "PathEnd". When the position of the entities changes the global path is automatically recomputed.

Testing flee path finding

Special path finds that are used to get away from certain position (most typically to get away from player) can be debug using a pair of tagpoints (or other entities) named "FleeCenter" and "FleeStart". FleeCenter marks the point to get away from, FleeStart is used as the starting position or the path find. The following cvars are used to configure the flee path find.

Name	Type	Arguments/limites	Description
wh_ai_FindPathFleeUseRaycasted	int	0 - use path finding flee, 1 - use ray casted flee	Chooses the method used for the debug flee path find.
wh_ai_FindPathFleeTargetDistance	float	Positive	Target distance of the flee path find
wh_ai_FindPathFleeMinDistance	float	Positive	For raycasted it is used as forbidden angle For non ray casted, it is used as minimal distance that should be kept away from the center point.

Obstacles

Name	Type	Arguments/limits	Description
wh_ai_FindPathUseObstacles	int	0/1	Turns on/off the usage of obstacles in MNM pathfidning. By default turned on.
wh_ai_FindPathObstaclesMultiplier	float	number larger than 1.0	Penalty cost multipler used for MNM polygons that are intersected by the obstacles. Default value 3
wh_ai_ObstaclesDebugDraw	int	0/1	Debug draw of the obstacles (drawn as lime green cylinders)
wh_ai_ObstaclesListenersGridDebugDraw	int	0/1	Debug draw of the listeners registered in the obstacle system (i.e. move nodes)
wh_ai_ObstaclesAddToCollisionAvoidance	int	0/1 (default 1)	Adds obstacle (from dialog, reading,...) to collision avoidance system.
wh_ai_AddObstacle	Command	posX posY posZ radius height	Adds an obstacle - for testing only!!!
wh_ai_RemoveAllObstacles	Command	node	Removes all obstacles - for testing only!!!

Movement system modofactions/debug

Name	Type	Argument	Description
wh_ai_MovementTeleportWhenStuck	int	0/1/2	Controls the system that teleports stuck movement actors further along the way 0 - off 1 - immediate teleport when stuck 2 - wait until the actor and the teleport target are not visible, then teleport.
wh_ai_MovementSystemDebugEntity	string	entity name	Debug draws errors reported by chosen entity from Cry movement system.

Smart area to navigation smart object mapping

Mapping between smart areas and navigation smart object is a system that allows us to control which smart objects are used in pathfinding. Effectively it prevents a NPC from going through a house if the NPC does not want to go inside the house or is already inside the house.

Name	Type	Default	Description
wh_ai_RebuildAreaToNavSOMapping	Commant		Rebuilds the mapping between areas and nav smart objects. Normally the rebuild occurs when starting the game mode. However to debug the pathfinding we need this mapping. This command provide option to have the mapping ready even in editor mode. Note: the rebuild uses the entity links and not the parsed linked that are used by graph search
wh_ai_AreaToNavSOAllowedLinkNames	Comma separated list		List of link names that are included when building smart area to navigation smart object mapping.