Navigation Mesh Editing

...

← Nav Mesh

This page is about creating and editing the NAV file for a map in-game.

For a list of commands, see Navigation Mesh Commands.

Automatic Navigation Mesh Generation

A new navigation mesh <game>/maps/<mapname>.nav for a map can be generated by using the nav_generate command while the map is loaded which requires sv_cheats 1. Depending on the size and complexity of the map, this may take a few minutes to a few hours, but mostly about 5 minutes. Large forests however are examples for structures that might take a long time to compute a .nav for. You can then upload the created .nav file to your server.

It is recommended that map creators create navigation meshes before releasing their map to the public.

Note:

If bots are added on a map with no .nav file, the game will nav_generate automatically. This affects custom maps particularly. If the .nav generation takes too long, this automatic process can be avoided by making sure that bots will not join the game e.g. by invoking bot_kick before choosing a team.

What is computed during generation

The following steps occur during Navigation Mesh generation:

Starting at a player spawn point, walkable space is sampled by "flood-filling" outwards from that spot, searching for adjacent walkable points
Rectangular Navigation Areas are constructed from the sampled data
Hiding and Sniper spots are computed
Encounter Spots and Approach Points are computed (this can take awhile)
Initial Encounter areas are computed

Viewing the Navigation Mesh

To see the current navigation mesh, type nav_edit 1. To turn the mesh editor off, type nav_edit 0. You will need to have sv_cheats 1 to be able to view the navigation mesh.

Explicitly marking walkable areas (i.e: "There's no mesh upstairs")

Some maps that have very steep stairs, ramps, or hills may confuse the generation system, resulting in the Navigation Mesh not covering the entire map. To solve this, you can manually place additional walkable markers that tell the generator to search outwards from that point during its sampling phase.

To add one or more walkable markers, first aim your view towards a known walkable spot in your map, then type nav_mark_walkable in the console. When you are finished placing markers, type nav_generate_incremental (followed by nav_clear_selected_set) or nav_generate to re-generate the mesh.

You can remove all previously placed walkable markers using the nav_clear_walkable_marks command.

Quickly generating meshes for testing

The analysis phase of the generator can be quite time consuming. To skip it, type nav_quicksave 1 in the console.

Note: "Quicksaving" skips the analysis phase, and the resultant nav mesh will be missing important data required by the CS Bots and Hostages higher-level planning and attention systems. While useful for testing, editing, and tuning a nav mesh, be sure to do a full analyze (ie: nav_analyze with nav_quicksave 0) before publishing your nav file to others.

Editing the Navigation Mesh

Enabling the Navigation Mesh editor in de_dust

The automated Navigation Mesh generator does a reasonable job of constructing a mesh, allowing you to start using Bots and Hostages on custom maps easily.

However, careful hand-tuning of the Navigation Mesh can noticeably improve the performance of Bots. In addition, manually decorating the mesh with Place Names allows the Bots to tell others where events occur, enhances the Counter-Strike radar and includes Place Names in all radio messages.

To enable the editor, type nav_edit 1 in the console (type nav_edit 0 to disable it).

The white cross in the center of your view is the cursor.
The navigation area you are pointing at is the selected area or highlighted area and is shown with a yellow outline.
Navigation areas that can be reached from the selected area are shown in red.
The white line in the selected area denotes where the area will be split if the nav_split command is executed.
Exactly one area can be marked (or unmarked) by pointing at it and invoking nav_mark and is shown with a cyan outline. This is used for many other commands that need two operands, being the marked and the selected area.

Warning: Editing the nav mesh while bots are active can crash the game, especially deleting, splitting and merging areas. For safety, execute bot_kick first. If you're done editing, nav_save your work and reload the map before adding bots again.

Save

Currently, there is no "undo" command in the Navigation Mesh editing system. Therefore, it is very important to save your work often via the nav_save command.

Creating a new area

This can be done with the commands nav_begin_area and nav_end_area.

Place your cursor at where a corner of the new area should be and execute nav_begin_area.

Move your cursor to drag out the area's extent.

Place your cursor at where the opposite corner of the new area should be and execute nav_end_area.

Note: Areas created like this have no connection to the existing nav mesh by default. It will bidirectionally connect to a marked area upon nav_end_area being executed.

Tip: Use nav_snap_to_grid 1 to get consistent rectangle sizes.

Tip: The 4 corners of the resulting area will be on the same height. If the ground is not even, begin new areas with the highest corner to prevent it from being created under the floor. A floating area can easily be shifted down to the ground using nav_corner_place_on_ground while aiming at it.

Tip: Instead of creating a lot of small areas, one could instead create one huge area, if possible, and nav_split it down to the needs. If it is too large, redundant areas can be deleted.

Delete

To delete an area, aim your cursor at it so that it is highlighted and execute nav_delete. Alternatively you can mark an area or select a set of areas to delete multiple areas.

Connect two areas

One-way connections (marked with dark blue lines) are usually used for "jump-down" links from a ledge to the ground.

Bidirectional (two-way) connections (marked with light blue lines at the area edges) allow bots to freely move between the two areas.

The connections between areas define whether one can move from one area to another.

Usually these connections are bidirectional, meaning one can move back and forth between two areas at will. However, sometimes the connection is one way, as in the case of ledges that can be jumped down, but not back up. One-way links can also be useful for forcing bots to travel a specific direction, perhaps to set up for a tricky jump.

To make a one-way connection from area A to area B (meaning you can move from A to B):

Mark area A: Place your cursor on it and execute nav_mark.
Aim at area B and execute nav_connect.

To make a bidirectional connection, repeat the above steps reversing the roles of A and B.

Tip: In a selected set, nav_connect will try to bidirectionally connect the first selected area and every subsequently selected area. Use nav_connect and selected sets to quickly make bidirectional connections.

Disconnect two areas

To remove all connections between the areas A and B:

Mark area A: Place your cursor on it and execute nav_mark.
Aim at area B and execute nav_disconnect.

Tip: When ran with a selected set, nav_disconnect will try to remove connections between the first selected area and every subsequently selected area.

Tip: Use nav_disconnect_outgoing_oneways to quickly disconnect all one-way connections. This command also works in a selected set.

Split

Splitting divides an area into two bidirectionally connected areas.

Position yourself and the cursor so that the white split line is where you want the area to be split.

Execute nav_split to get two adjacent, inter-connected areas.

Merge

Merging two areas reduces the area count.

Both areas must be the same size along the edge to be merged. It is not required that the two areas are adjacent.

The resulting area will retain all of the connections of the original two areas, and inherit properties (i.e: Place Names, etc) from the marked area.

Tip: While moving from point A to point B, bots tend to prefer routes with less areas to travel through, so a route can in theory be made more attractive to bots by merging some areas.

Aim your cursor at the first area and execute nav_mark.

Aim at second area.

Execute nav_merge.

Splice

Splicing creates a new area between two existing areas. Splicing is a powerful tool, and can be used to easily create sloped areas, as shown in the example below.

Tip: It is not required that the two areas have the same width. The width of the resulting area will be the smaller of the two.

Aim your cursor at the first area and execute nav_mark.

Aim your cursor at the second area.

Execute nav_splice.

Area Attributes

A jump area and a no_jump area.

Crouch areas.

Area attributes influence the behavior of bots to act in specific ways. Each area can have any combination of attributes. Most area attributes are required to be set manually, but a portion of attributes are set automatically and cannot be set manually.

Note: Games may implement their own set of area attributes, or in a few cases, implement attributes through a different system which is the case in

Left 4 Dead,

Left 4 Dead 2 and

Team Fortress 2. So even though the following base attributes exist in all games that support navigation meshes, the AI may not take them into account. In the aforementioned games, only the precise area attribute is considered.

Base attributes

These are the attributes that exist since Counter-Strike: Source. To toggle an attribute for an area, aim at it and execute the corresponding command, e.g. nav_jump.

Type	Mark	Effect
Jump	green X	Tells bots to jump in order to reach the higher connected area and that this area is not usable as a hiding/sniping spot.
Crouch	blue diagonal slash	Forces bots to crouch when moving through this area.
No jump	red rhombus	Forces bots not to jump. This is useful to prevent excessive jumping. However, bots can get stuck if jumping is required to keep going. This attribute will not prevent an explicit `action_jump` in behavior trees.
Precise	green +	Prevents bots from skipping this area and stops bots from avoiding obstacles. The precise attribute can help in places where bots can easily fall off, like catwalks with no railing, or when setting up specific routes for a jump.
Stop	red octagon	Tells bots to stand still for a short moment when entering this area. Useful to slow bots down to line up tricky jumps more accurately.
Run	two blue arrows	Tells bots explicitly to run in this area.
Walk	one green arrow	Tells bots explicitly to walk silently in this area.
Avoid	two red triangles	Tells bots not to use this area if possible.
Don't hide	no mark	Tells bots not to use this area as a hiding spot.
Stand	no mark	Tells bots not to crouch while hiding in this area. Idea: If you want bots to crouch only in specific places, apply this to the whole mesh and remove it where needed.
No hostages	no mark	Tells hostage NPCs not to use this area. Only effective in .
Transient	dashed outline	To do: Effect? Description from : Toggles the 'area is transient and may become blocked' flag used by the AI system.
Blocked	blue rectangle	Tells bots not to use this area. This attribute is only set automatically by the game in certain cases when bots can't or shouldn't use a nav area. Example cases include: Blocking `func_nav_blocker` entities (in all games since ) (cyan rectangle in ) Closed `func_door` entities Spawn room exit doors Enabled `trigger_hurt` and locked `prop_door_rotating` entities. Furthermore, there are the related console commands `nav_debug_blocked, nav_update_blocked, nav_check_floor, nav_select_blocked_areas`.

Left 4 Dead 1&2

Main article: List of L4D Series Nav Mesh Attributes

In Left 4 Dead and Left 4 Dead 2, an alternate set of area attributes named "Spawn Attributes" is available with a very different implementation. Spawn Attributes are identified not by shapes but color, and their attribute names use the color white rather than yellow. The attributes's roles are also different, commonly assisting the "Director" over player AI decision-making.

z_debug 1 is required to view Spawn Attributes.

Team Fortress 2

To do: A "main article" for all the TF attributes.

Team Fortress 2 has fittingly named "TF attributes", a simpler implementation of "Spawn Attributes" from and which tends to assist the game logic in a general sense, such as blocking nav areas when a capture point is captured.

Use tf_show_mesh_decoration 1 to display all TF attributes at once, coloring all nav areas with a specific color even if not hovered over.

Bug: Multiple TF attributes in one nav area will display overlapping text.

Note: Areas can be blocked for only specific teams in

in different ways (which can cause confusion). Use the tf_show_blocked_areas to get the full context.

Using Mesh Editing Binds

Although all of the mesh editing commands can be typed in the console, in practice it is far easier to bind these commands to keys. With bind del nav_delete for example, pressing Del will delete the nav area under your cursor (in nav editing mode).

You can temporarily bind many commands at once by using a CFG file. This is useful for bot navigation editing, because there are many commands, and you will probably not want them to be permanently attached to your keys. See Editing Bot Navigation CFG File for a pre-made file and instructions on its use.

See Navigation Mesh Console Command Reference for a list of all commands related to bot navigation.

Place Names

Once a nav mesh is generated, Place Names can be assigned to nav areas to label regions of the map. For instance, if there is a prominent house in the map, all of the nav areas in the house can be tagged with the House place name.

Place names have multiple uses:

In the top left of the screen, each player sees his current place, which is the place name of the closest nav area.
The chat displays the place of players using a radio command. This is also the case when they throw grenades. Example:
ChicagoTed @ Apartment (RADIO): Fire in the hole!
Bots use them to announce from where they are reporting in.
When using the ping tool, the place name is shown with it.

Warning:

If the closest nav area to the center of a func_bomb_target has any place name, then the bomb target will be bombsite A if that place name is Bombsite or BombsiteA, otherwise it will be bombsite B. If you don't pay attention, two bombsites can get the same labeling, causing the radar to show just one!

Adding Place Names

Place Name Editor
Nav Area Color	Nav Area...
red	has no place name
green	has the current place name
blue	has a place name, but not the current

To add or change the name of a location, you need to turn on the place name editor. Make sure nav_edit is set to 1, then type

nav_toggle_place_mode.

When the place name editor is enabled for the first time, all nav areas should turn red. To select a place name that should be assigned to some areas, type

nav_use_place <place name>,

for example nav_use_place Bedroom. For a list of all available place names, execute nav_use_place with no argument. See also: Standard Place Names for CS:S, Standard Place Names for CS:GO.

Next, aim your cursor at an area you want to label with that place name and toggle the Place Painting Mode by executing

nav_toggle_place_painting.

Look around carefully! While Place Painting is active, each area that you point at with your crosshair will be tagged with the current place name that you selected and turn green in color. To stop painting, invoke the same command again.

You can change the place name you are painting with by typing nav_use_place <new place name>. Notice that after changing the place name, all areas that are already painted with a different name will turn blue and areas painted with the name you just changed to will turn green.

Tip:

To select the place name that is assigned to a specific nav area, point at it and invoke nav_place_pick.
Bind nav_toggle_place_painting and/or nav_place_pick to mouse buttons.

When you are finished editing place names, exit the place mode with nav_toggle_place_mode.

Important: Remember to nav_save your work!

There are several additional commands that provide tools for picking, flood-filling, replacing, and so on. For a complete reference, see Place Name Commands.

Common mesh problems and solutions

Extraneous areas on stairs and ramps

The automatic generation system tends to build areas that hang off the side of stairs and ramps. These should be removed to force the bots to take the stairs or ramp straight-on.

Railings

Railings can be a problem for the current bot navigation system, this includes jump-down links that must pass over railings, they should be avoided unless necessary. The bots will eventually make these jumps, but they are not terribly elegant while doing so.

Preventing excessive jumping

Use the nav_no_jump command to flag the area to disable jumping.

Dealing with rotating doors

Clip off the nav area to leave an empty space in the nav mesh to allow for the rotating door. You may have to remake the nav square if deleting part of an existing one doesn't work.

Bots will sometimes try to walk through the opened door brush from one nav area to another and get stuck. Either removing the adjacent nav area or configuring the areas and connections so the bots have to walk around the opened door should prevent this.

Advanced editing techniques

Ladders

For ladders, there is a slightly different type of nav area that must be built manually on climbable surfaces. Your editing cursor will turn green when pointing at one. But once created, nav areas on ladders behave the same as every other nav area in terms of selecting and connecting.

Creation using nav_build_ladder

Point at a climbable surface. Note the green cursor.

Execute nav_build_ladder. The game might also create connections at the top and bottom.

Creation using nav_begin_area and nav_end_area

If nav_build_ladder isn't what you need, you can manually create a ladder. This can be useful to get bots to start going up the ladder, and jump off halfway up, onto the crate:

Aim at the first corner and execute nav_begin_area.

Move your cursor to drag out the ladder's extent.

Execute nav_end_area.

Reversing Ladders

Sometimes a ladder will be created facing the wrong way and show up red. The ladder is drawn in green if it is facing you. To change its orientation, simply point at it and use nav_ladder_flip.

Ladder facing into the wall (incorrect)

Ladder facing away from the wall (correct)

Obstacle avoidance and precision movement

Use nav_precise, nav_walk, and nav_stop to disable local obstacle avoidance behaviors and control bot movement.

The WALK and STOP attributes are only used in .

Marking areas to avoid

Use nav_avoid or nav_mark_attribute AVOID to tell bots to avoid the area unless the normal route has become too dangerous.

Controlling where bots can hide

Use nav_dont_hide or nav_mark_attribute DONT_HIDE to prevent bots from hiding in certain areas. This can be used to force the creation of hiding spots during the analysis phase.

Setting up sniper spots

Mark an area using nav_walk and execute nav_make_sniper_spots. This will break the area into small sub-areas which are used internally by the navigation mesh to encourage sniping.

Important:

Hiding spots only determine where TFBot Spies lurk; Sniper spots can be marked with func_tfbot_hint, but they are only used by Snipers in Mann vs. Machine; otherwise the game uses theater and vantage points as sniper spot replacements.

Highest possible crouchjump

Lining up tricky jumps and narrow doorways

Arranging nav areas to force specific paths.

If the bots are getting hung up on the sides of a door or window, you can carve out a narrow path through the middle of the opening.
The highest a bot will try to jump is 58 units. If the top of a jump is 59 or more units above the bottom, bots will give up as soon as they jump. If this happens in a spot that the bots can actually jump up to, use nav_corner_lower to lower the upper nav area slightly.

Import and Export areas

Nav areas can be imported and exported through nav_save_selected and nav_merge_mesh respectively. nav_save_selected exports nav areas in a selected set to a KeyValues file, while nav_merge_mesh imports nav areas from the selected file and selects them.

The KV file used by these commands can be edited to force custom nav area shapes and connections that otherwise would be impossible to make.

Warning: Degenerate areas are hard to select and (by proxy) remove, so try not to make them!

To do: Describe file syntax and info.

These commands can be useful for:

Creating connections that are difficult or impossible to make manually with nav_connect, such as a bidirectional connection between two areas in areaportals.
Fit areas on to skewed surfaces.

External Links

Official forums for the bot system (down) - Archived version.
Waypointing for CS:S Bots/Hostages (Edit Life)