GMod Navmesh and AI Nodes: Differences and Setup

The navmesh and AI nodes are two separate navigation systems in the Source Engine. Nextbots move on the navmesh (a .nav file), while classic NPCs such as npc_combine_s or npc_zombie use a node graph built from info_node entities (an .ain file). If your map should work with both kinds of NPC, it needs both.

Navmesh and AI nodes compared

The two systems know nothing about each other. A Nextbot cannot use even a perfect node graph, and an npc_combine_s ignores the navmesh completely.

When you need which

• Players only, no NPCs: Technically you need neither system. Many servers add NPC addons later, so preparing the map still pays off.
• Fights with Half-Life 2 NPCs: You need AI nodes. Without them the NPCs can aim, shoot and walk short distances in a straight line, but they cannot plan a route around obstacles.
• Nextbot addons: You need a navmesh. Nextbots calculate the path to their target on it.
• Maps you publish or sell: Ship both. Buyers rarely know in advance which addons they will run, and missing navigation only shows up in live use.

Placing AI nodes in Hammer

1. Place info_node on walkable ground wherever NPCs should go: in corridors, in front of and behind doors, at corners, at the top and bottom of stairs.
2. Keep a clear connection in mind. The engine only links two nodes if the path between them is free and walkable and they are not too far apart; the Valve wiki gives 720 units as the maximum. Put nodes closer together in tight spots and further apart in open areas.
3. Flying NPCs use info_node_air. With info_node_hint you mark special spots such as cover.
4. Compile the map and load it in game. On first load the engine builds the node graph and saves it as an .ain file in the maps/graphs folder.
5. Check the result with sv_cheats 1 enabled: the console command ai_nodes displays the nodes and ai_show_connect the links between them, so you can spot gaps in the network.

Place nodes deliberately instead of covering the floor in a dense grid. The engine only handles a limited number of nodes, and an overcrowded network makes the graph take longer to build. The article on Source Engine map limits covers ceilings like this in more detail.

Generating and editing the navmesh

The navmesh is not created in Hammer but in the running game.

1. Load the compiled map in single player and enable sv_cheats 1.
2. Enter nav_generate. The engine samples the walkable floor starting from a player spawn point and reloads the map when it is done. On large maps this takes a noticeable amount of time.
3. Areas that cannot be reached on foot from the spawn stay empty. Stand in such an area, aim at the floor, enter nav_mark_walkable and run nav_generate again.
4. nav_edit 1 displays the mesh and lets you edit it. There are dedicated commands for deleting, splitting, merging and connecting areas, for example nav_delete, nav_split, nav_merge and nav_connect.
5. Save the result with nav_save and leave edit mode with nav_edit 0. The file is then stored as <mapname>.nav in the maps folder.

An automatically generated mesh is rarely flawless. Check doors, stairs, narrow passages and roofs in particular, as well as places where areas reach into walls or over empty space.

Shipping both files with the map

Neither file is created by the compile, and neither ends up in the BSP by itself. You have to ship both explicitly:

• maps/<mapname>.nav
• maps/graphs/<mapname>.ain

The file name must match the BSP name exactly. If you rename the map, you have to rename both files as well.

The order matters. The engine rebuilds a node graph when the .ain is older than the BSP or was built for a different map version. If you recompile the map or modify the BSP afterwards, for example when packing custom content, load it in game once more, let the graph rebuild and ship that fresh .ain. The navmesh only needs changes when the walkable geometry has changed.

How files reach servers and clients is explained in the article on FastDL and Workshop. The Map Scanner checks the structure, entities and pakfile of a BSP. The .nav and .ain are separate files, so they belong on your own pre-release checklist.

Common problems

The message "Node Graph out of Date" is not an error in itself. The engine simply rebuilds the graph, which costs loading time. According to the Valve wiki, this can also happen once with a freshly downloaded .ain, because the game regards it as outdated. It only becomes a problem when the message appears on every start.

FAQ

Does every GMod map need a navmesh?

No. A navmesh is only required if Nextbots should work on the map. For maps you publish it is still a good idea, because many servers install Nextbot addons later.

Can I create the navmesh in Hammer?

No. The navmesh is calculated in game with nav_generate and refined with nav_edit. In Hammer you only place the info_node entities for the node graph.

Why does "Node Graph out of Date" appear on every map start?

The engine regards the stored .ain as outdated. This happens, for example, when the BSP was modified again after the graph was created. Load the final BSP in game once and ship the file that gets generated in the process.

Do Nextbots work with AI nodes as well?

No. Nextbots use the navmesh only, and classic NPCs use the node graph only. A map that should support both kinds of NPC needs both files.