[2021 Re-Release] Bot waypointing guide

Teaches you how to use the navigation editor and how to place nodes / waypoints in the level.

This guide

This guide will try to explain everything I know about the bots, waypoints and navigation systems in the 2021 Rerelease version of the game. The guide will most likely be updated several times as new information comes to light.

Introduction

The bots in the 2021 remastered version seem quite adept and probably much better than anything else we've had before.

The bots are geared towards deathmatch-only capabilities, with some limited co-op capabilities.

The game features a built-in waypoint editor which lets you easily create and modify the waypoints of a level.

The navigation system is waypoint-based (nodes), although they have configurable radius which can make it look a bit like a navmesh at sometimes. There's certainly pros & cons to this.

Cooperative Bots

The bots will work in cooperative, but in limited capacity. They will engage enemies and pickup weapons, ammo, etc.. and generally try to follow the player or even venture on their own to pick up some items.
Unfortunately lack of features in the waypoint and navigation system means that the bots aren't able to complete most singleplayer maps by themselves. The biggest issue they have is being unable to deal with key locked doors. They do not appear to have any concept of this and will just merely try to walk through the door.

Navigation Editor

The waypoint editor (in-game called Navigation Editor) is where you will be doing all the waypoint editing.

Opening

1. Open the console
   
2. Change the map to the one you wish to waypoint:

   map <mapname>

3. Enable cheats:

   sv_cheats 1

4. Enable the editor:

   nav_edit 1

You should now be greeted with the navigation editor:

Closing

1. Open the console
   
2. Disable the editor:

   nav_edit 0

Toggling

You can alternatively toggle the editor with

toggle nav_edit

Saving

To save, type

nav_save

in the console.

WARNING: If you close the nav_editor without saving, you will lose all your changes.

Things to keep in mind

• You will be granted notarget, god (Godmode) and noclip.
  
• By default, when leaving the editor, you will spawn at the current location and your notarget, god, noclip will be removed. You can disable this behavior by using the navEdit_removeGodModeOnExit and navEdit_removeNotargetOnExit cvars.
  
• Remember to press 'TAB' to view all entities, so don't be scared if suddenly everything looks a bit empty.
  
• Remember to save before closing the editor.

Working with the navigation editor

It'll take some getting used to, but once you know how to handle it you can very quickly and easily edit waypoints.

Luckily for us, the whole editor is very well documented and always displaying the keys + what they do.

Tip #1: Always look at the legend in the bottom right, and read.
Tip #2: It's quite easy to get lost in the menus so make sure you look at the legend to know what mode you're on.
Tip #3: I'd recommend disabling error checking by pressing F1 while in the editor. It can be annoying because you're unable to save your progress.

NOTE: Some part of the legend might be cut off. You can raise it by using the command: 'nav_legend_ypos 0.6'. If you still don't see it, decrease the number until you're satisfied.
You can also move the whole UI around using 'nav_properties_xpos', 'nav_properties_ypos', 'nav_legend_xpos', 'nav_legend_ypos'.

Moving

You now have noclip which means you fly and can go through walls. Use WASD + Mouse look (or whatever keys you have bound to movement) to navigate.

Nodes (Waypoints)

Waypoints are called 'Nodes'. These represent areas in space where the bot is able to walk.

In this picture, the blue line represents the 'center' point.

The green circle is the 'radius'. It usually indicates that any point inside this circle is floor and can be walked upon and that any properties the node contains, also affect this area. It also tells the bot when they should consider as having arrived at the node. So a smaller radius effectively means they'll stay closer to the center of the node, whereas a bigger radius they'll stay further away before aiming towards the next node.

The number above the blue line indicates the Node ID and will sequentially increase as you add more nodes.

Placing down a node

Make sure you don't have any node currently selected, and just press LMB (Left Mouse Button). If your crosshair was red then it'll mean that it's not possible to place down a waypoint at that location.

Deleting a node

1. Select the node you wish to delete
   
2. Press 'DELETE'

Moving a node

If you placed the node incorrectly or you wish to make it hover (for example, underwater), use the Move tool.

1. Select the node you wish to move
   
2. Press 'SHIFT'
   
3. Move / Place the node by moving the mouse.
   
4. Raise / Lower it by using the scroll wheel.
   
5. RMB (Right mouse button) to 'drop it to the floor'

Types

Nodes can have types. These usually indicate a special function.

Teleporter: It indicates that when you move here, you'll be teleported. Automatically set if placed inside a trigger_teleport.
Pusher: Used for wind tunnels, basically something that moves the bot without being itself.
Elevator Top: Indicates the highest level of an elevator plus how the bot should leave the lift.
Elevator Bottom: Indicates the lowest level of an elevator.
UnderWater: Liquids. Automatically set if placed inside a liquid.
CheckForHazard: Mostly used for traps. It will disable pathing if there's lava or slime underneath or if it's completely inside a solid.
CheckForFloor: It will disable pathing if there's no floor underneath. Used to check for open bridges for example.
CheckForSolid: It will disable pathing if there's any kind of solid within a specific radius. Used to check for closed gates for example.

Tip: You can see if a node is enabled or disabled after you save them by using the console variable: nav_drawNavNodes 1. If they're disabled, they will show up red.

Area of effect

Generally specially you don't need to cover all items with a node, as the bots are smart enough to walk and fetch items that are close to the node.

The radius of a node works mostly as an indicator for the bot when it has arrived at the node. So for big rooms don't add just a single node but multiple in a diamond shape pattern, this will allow a fluid movement pattern while covering most ground.

You can change the default node radius using the following console variable:

navEdit_defaultNodeRadius <value>

Links

Nodes by themselves will not do much. You need to link them together in order to create paths.

How to see them

In general, here's how to identify them in the editor:

No link

These waypoints are not linked, thus they cannot be walked from and to each other.

Two-way link

Note the white line + yellow arrows at the ends.

These waypoints are linked both ways. You can walk from 0 to 1, and 1 to 0.
There are 2 individual connections (one going each way)

One-way link

Note the blue line + blue arrow at the end.

These waypoints are linked one way. You can only walk from 1 to 0.

Linking waypoints

1. Select the starting node
   
2. Select the ending node (without deselecting the first one)

This will create a link. Two-way if possible, one-way if it thinks it's a ledge.
If you mouse over the nodes, you'll be able to see the connections listed in the bottom-left window.

Changing the link settings

To select an individual link, it's a bit more complicated. Keep in mind that a two-way connection is effectively 2 links.

1. Select the starting node
   
2. Press 'CTRL' to enter link selection mode

Now you are in link selection mode:

Each cylinder represents an end node of a connection that starts at the selected node. Select the cylinder to select the connection from the start node to that node.

Settings

Here's a list of the settings each link can be:

Walk: Default. It means you can walk...
Long Jump: There's a chasm of some kind that the bot needs to perform a long jump. Depending on the situation, bots might fall down.
Teleport: This link indicates that it'll teleport you to another node instantly.
Walk Off Ledge: Drop from a ledge.
Pusher: All outgoing connections from a Pusher node will have this. Indicates that the bot shouldn't do anything as it will be pushed. For example a wind tunnel.
Barrier Jump: There's a small obstacle in the way that can be traversed by jumping.
Elevator: This is a special link. Should only be used between Elevator Bottom and Top nodes.
Train: Moving platforms
Manual Jump: The bot should jump no matter what.
Unknown: Unknown type. You will encounter this when linking nodes that can't be seen from each other.

Edicts

Edicts are level entities which have some relation to this link. They're usually meant to indicate buttons, lifts and doors. You can see their use in the Scenarios section.

But just know that to set an edict, press CTRL while having a link selected, and then select the target entity which will be highlighted with a yellow box. You'll know that you're in edict selection mode when you see doors, buttons, lifts highlighted with a white box around them.

Useful options

Two of the editor toggle options affect links.

Pressing CAPSLOCK toggles between being able to see 'All Links' or only 'One Way Links'.
Pressing SPACE toggles between 'Chain Connections' and 'Keep Source'.

Chain Connections: When linking a node to another, the end done with will become the newly selected node.
Keep Source: Opposite of 'Chain Connections', in which the starting node remains selected.

Bot Movement

It's important to understand how the bots move, and you'll exploit the way they calculate paths when handling some complex obstacles in maps.

Bots will generally wander towards items, weapons and power-ups they can pickup. They also have some limited enemy tracking capabilities but generally only if they see them first (I think).

They'll always pick the fastest route (in distance) toward the target. Teleport links are considered 0 distance for calculation purposes. This fact in particular is very useful as we can exploit this to introduce "custom logic" into movement. Don't worry about it for now, you'll see it being used later in some complex scenarios.

Handling some scenarios

The best way to learn how to handle certain things, is to think about the same scenario in official maps or some custom map that contains waypoints and going to see how it was done. But here's a quick explanation of some of the scenarios you'll face in different levels.

Teleports

1. Place a node at the teleport destination (node 2 in the picture)
   
2. Place a node at the teleport. It should look a bit different with a tiny circle (node 1 in the picture)
   
3. Link the teleport node to the destination node. It will automatically be set one-way and with teleport tag, represented by a purple line.
   
4. Connect the entry node to the teleport (node 0 in the picture)

Doors

Part 1:

1. Place a node on each side of the door
   
2. Link both nodes in both ways (if applicable). NOTE that if the door obstructs the view, the link will be red and only one-way. So make sure you link it both ways (picture below)

Part2:

1. If the links were red, manually edit the links and set their type to 'Walk'.
   
2. If the door triggers with a button, edit the links and set their Edict (CTRL key) to the button that triggers them.

(Door not visible, but it's there)

Secret Doors (Shootable)

Bots do not automatically shoot secret doors. But it's just an extra step from the 'Door' scenario.

1. Do the same as the 'Door' scenario
   
2. Set the link edicts as the door itself. It indicates to the bot that it should shoot it in order to pass.

Lifts

They're probably the most complicated setup you'll do. This is for a lift that starts at the bottom and raises when you step on it.

1. Place a node in the middle of the lift at the bottom.
   
2. Set the node type to 'Elevator Bottom'
   
3. Place a node at the top of lift, on the side where you'll leave the lift.
   
4. Set the node type to 'Elevator Top'
   
5. Create a link from the 'Elevator Bottom' node to the 'Elevator Top' node.
   
6. Edit the link and set the Edict (CTRL key) to be the lift itself.
   
7. (Optional) Finish off by adding a Fall Off Edge link if appropriate.

NOTE: If the lift bottom and top are too far away, you might not be able to select the top node since it disappears.

Lifts with buttons

But what if there's a lift that you need to trigger with a button? No problem (for the most part).

E1M1-style calling a lift

1. Do the regular lift setup
   
2. Add an edict when moving towards the 'Elevator Bottom' node to trigger the button.

NOTE: This works on E1M1 because the lift will not crush you when coming down. Bots will not wait for the lift to come down before attempting to board it.

Button inside the lift

1. Do the same setup as above

Basically, instead of the button being outside, it'll be inside and the bots will trigger it.

Wind tunnels

Pretty easy to handle. For the most part you'll only use one node.

1. Place a node at the entrance (but inside) the wind tunnel. You'll know if it's correct as the node type will be set to Pusher.
   
2. Link it to where you're going to end up.

Here's a picture from a custom map called 'zed'. I've blurred everything that's not wind tunnel related so you can understand it better:


For long wind tunnels, for example those with turns, you might have to use multiple pusher nodes. I'll update the guide if I encounter such need. Although I've seen it in use in some official map.

Ladders

These are a bit tricky. It's going to depend a bit on context, but for straight ladders here's what I found that works best:

1. Have a node at the bottom of the ladder and another at the top (see picture)
   
2. Change the connection type from the bottom to the top to be "Barrier Jump"
   
3. Change the connection type from the top to the bottom to be "Walk off edge"

Both connection types being "Walk off edge" might work too, however if your map is complex the barrier jump works best. Of course it means the bots will attempt to jump every time even though it's not needed.

Other scenarios

This section contains some more miscellaneous scenarios

Trains / Moving platforms

These are suprisingly easy to deal with, as long as you have 1 train only.

1. Place 2 nodes on each destination of the train.
   
2. Link the 2 nodes together with a 'Train' link.
   
3. Set the edict on both links to the moving train / platform.

It's very important that you test it, as some trains / moving platforms are not compatible due to the place where they stop.

Use trigger if needed

Sometimes the a door doesn't open when you approach it. So you want the bots to open it with a button if they have to walk through it. Now assume you can toggle the door open and close via a button on each side. If you set an edict on the links, every time the bots want to walk though the door, they'll move to the trigger before moving to the target. Even if the door is already open, they'll close it.

This is the exact case in E1M6 (deathmatch)

You can solve this by exploiting the fact they'll always take the shortest path that's available.

1. Create the same setup as 'Open later scenario' (You can find it in the Passages scenarios section)
   
2. Add an extra small node, which we'll call it the 'Trigger node'. Place it above the door (see picture).
   
3. Link this node to the node on each side of the door. Link type 'Walk off Ledge' or 'Walk'
   
4. Add the edict button they should press when going from each side towards the door (see picture above and below)

I'll try to break down how this works:
If the door is open, the bots will prioritize going through the CheckForSolid node. This is because that's the fastest route available. However, if that node is disabled, they'll take the second best option, which happens to be through the 'Trigger node'. Since those links contain an edict, they'll press them before moving on.

Openable bridges

Say you want the bot to path through a bridge when it's open, but not when it's closed. This is very simple.

1. Open the bridge
   
2. Place nodes on top of the bridge as you would any other floor
   
3. Set the node type to 'CheckForFloor'

The 'CheckForFloor' nodes will be disabled if there's no floor underneath, so only when the bridge is open is that they'll consider pathing through.

Slime / Acid / Lava

Currently the bots don't understand that these types of environment are damaging to them, so the best way to deal with it is to basically provide them a one-way out.

Passage scenarios

This section contains some scenarios that relate to passages that open later. You'll typically not encounter these in deathmatch maps.

Open later passages

It's relatively common in single player maps to have a door that opens up whenever you press a far away button or go through some trigger. However in some cases, it's not practical to define the path they need to take in order to activate it. However you stil want them to use it if it has been triggered. It's quite easy to check for this using a CheckForSolid node.

If you consider the scenario in E1M5, where there's a door that opens up whenever you fall from the hole in the ceiling:


Here's how you can do this:

1. Place 2 nodes on each side of the door
   
2. Place a single node right next to the door, either side is fine.
   
3. Set this node to 'CheckForSolid' type.
   
4. Connect the nodes in a sequence like regular

TIP: Always verify that the node is disabled when the door is closed, and enabled when it's open. You can do this using "bot_navdrawnodes 1" and it will show up red if it's disabled.


The 'CheckForSolid' node will make it so if the door is closed, the node is disabled so bots don't even consider it when looking for a path.

NOTE: If the passage is small, the CheckForSolid node might be disabled at all times. In which case, use the next scenario.

Tiny open later passages

In some cases the CheckForSolid has a checking radius that's too big and it will always be disabled, even if the door is open. For this you can use a 'CheckForHazard' node, although the setup positioning of the nodes is slightly different.

1. Place 3 nodes like the scenario above.
   
2. Set the middle node to 'CheckForHazard'.
   
3. Trigger the door so that it's open
   
4. Move the node to the middle of the original position of door

TIP: Like before, make sure that the node is disabled. If it's enabled even if the door is closed, try moving it up and down until it works.

Double-shotgun secret door in E1M1:

Open later passages (One-way)

These are the cases where you have a door or a bridge but it only opens from one side, so if you're on the other side and you want to cross.. you can't. If you just tell the bot that it can walk, if it's a bridge it'll just fall or if it's a door it'll just run into it until it opens. Not good.

You can solve these using an extended 'Use trigger if needed' scenario.

Door

We'll the exact same as 'Use trigger if needed', but linking the trigger node one-way. Consider the E1M2 scenario with the secret door that only opens when coming from the water tunnel (and stays open afterwards)

Here's how you can do this:

1. Setup the same as 'Use trigger if needed' scenario.
   
2. Make sure the links toward the trigger node are one-way, from the trigger side towards the outside.

It works exactly the same way as the 'Use trigger if needed' scenario, but since the trigger node is connected one way, the bots will initially only consider the path one-way.

It's very important to test this type of setup to make sure everything works properly!

Bridge

This one is similar to the door but with some extra steps. Consider the E1M1 scenario where you have the acid bridge, but the button is only on one of the side.


Here's how you can do this:

1. Trigger the bridge so that it's open.
   
2. Setup the same as the one-way door scenario above.
   
3. Create as many nodes as you need to navigate on top of the bridge when it's open. Set them to 'CheckForFloor' type.
   
4. Link everything together as you would do regularly.

So, as you can see it works exactly the same way as the door scenario. However instead of 'CheckForSolid' nodes, we're using 'CheckForFloor' nodes.

Going for a test ride

If you want to try the waypoints with actual bots, it's quite easy to do.

Trying with actual bots

1. If you're already inside the map, save your waypoints and type

   disconnect

   to go back to the main menu
   
2. Type

   maxplayers 8

3. Type

   map <mapname>

   to go back to your level
   
4. Now you can add bots via

   addbot

Some things to keep in mind:

• If you open the navigation editor, bots will stop triggering things. That includes lifts, door triggers, teleporters... Just close the editor and everything will be back to normal.
  
• Editing nodes while bots are roaming around will not update them. However once you save your nodes, the bots will start using your changes.

Observing

If you want to observe bots fighting each other, activate: god, notarget and noclip.

Debug bot

There's a bunch of helpful commands to help debug the bot behavior.

bot_showPaths 1: Shows the current paths of each bot
bot_showBots 1: Shows where all bots are, even through walls.
bot_drawNavNodes 1: Draw all the navigation nodes even if outside the editor.
bot_navNodeGoal <Node ID>: Will make all bots beeline directly to that node. They will ignore monsters and each other. Set to -1 to disable.
bot_debugsystem 1: Enables the bot debug view. You can see everything related to the bot and it's behavior. Also very useful is the ability to select different bots and teleport them to wherever you're aiming.

There are a bunch of other commands, but I didn't personally find them useful yet.

Pressing BACKSPACE in the navigation editor (without any node selected), will put you in Path Test mode. You can easily test path connectivity between two nodes.

bot_debugsystem

This is the most powerful debugging tool at your disposal. It directly hooks into the bot programming and shows you all the different values and states. It's a bit hard to read if you're not used to programming or don't know what you're looking for.

But ignoring those things, it has 2 tools that are quite useful: Suggesting the bot where to go and Teleport the bot.

There's a bunch of different windows, which you can access by pressing 1 through 6.


While using window #4, pressing LMB will make a green sphere wherever you're aiming. This is the bot's "goal". It will still collect ammo, weapons and so on but whenever it doesn't have anything else to do, it will head towards this.

In this window you can also see the bot current planned path, and in the left side you can also see the bot current movement logic. It can be useful to understand what the hell is it doing when running against a wall.

Limitations

There are a bunch of limitations you should be aware of:

• Maximum number of nodes: 1024
  
• Maximum number of outgoing connections per node: 12

These aren't too restrictive. I could see the maximum node count being hit in a HUGE map, but it would definitely have to be a single-player map as deathmatch maps are usually not that big. But if you hit it, I'm sure you can optimize and shave off nodes somewhere else in the map.

Save files

Your navigation files are saved under mod folder, inside a sub-folder called bots/navigation. Here you will find the .nav files.

If you include these .nav files with your mod (zip or pak), it will automatically import the nav files in-game.

Bugs & Quirks

Here's a compilation of quirks & bugs that you might encounter. If you find weird behaviour that's not present here, try to debug it yourself using the bot_debugsystem command.

Bots just walking into the wall

This could be due to a bunch of different things.

Case 1: Item

Let's start with the bot trying to reach an item. Here's it happening in e1m1:

The bot thinks it can reach that item, but it can't so it just keeps running into the wall. The way to fix this is by making sure there's another node closer to the item, as then the bot tries to find a path to that node instead. Even if the item is not reachable you should add a node so it'll know it can't reach it.

---

Case 2: Missed a trigger

This can happen if you have like a door that you need to shoot something or trigger it somewhere in order to open, but the bot failed to do this trigger but kept going. It'll keep trying to move until some other stimuli or someone triggers the door.

E1M1 - Shotgun secret

---

Case 3: Bot is trying to press a button through the wall

If there's a button on the path that the bot needs to press on and it thinks that it can press it before traversing the link that contains the edict, it will try to do so. Unfortunately for us, the bot might also think that it can reach the button through the walls.


To fix this, place a node closer to the button, a bit like case #1.
See picture below. Node 133 was added, it is linked "Walk" two way to Node 28.

Far away / out of view shootable trigger

This is almost related to the previous scenario (in particular the E1M1 shotgun secret). If you have a door where the shootable trigger is not in plain sight, this is a problem for the bots. When the bots have a path with a shootable trigger, they'll shoot it whenever they see it and will not seek a position where they can shoot from.

Drive by shooting

Usually the easier solution is to have a link in view of the trigger that contains the shootable trigger. So whenever a bot walks past it, they'll shot it. Consider the secret teleporter in E4M1:


If you have an edict on the waypoint that moves towards the secret door, the bots will get stuck, just like the 'Missed Trigger' case. What you can do depends on a lot of variables like how far away is it, is it a permanent trigger, how long it takes to close, etc..

In this case I found that adding an edict when someone is moving down the stairs next to the button should be sufficient:


Anyone walking there will shoot it and since the trigger is permanent it'll just as be as the door isn't there.

--

Actual positionining

If you really want the bot to be able to trigger it whenever it wants to, it's actually not that hard. You do it like the one-way passage scenario, but the 'trigger node' is linked from the node where the trigger is visible. Here's how E1M1 can be solved:


The bots know that to reach behind the blocked door they need to go this node, and just by "coincidence" they'll see the shootable button, so they'll shoot it and open the door.

Keys

As mentioned before in the Cooperative section, bots will not handle keys and locked doors. Unless you can ensure that the bot picks them up every time they spawn there is currently no way of handling them.

Currently you can check if the door is open with a Hazard node like in the 'Open Later Passage' scenario.

Bot is just spinning in place

This usually indicates that something is wrong with your nodes or links. Make sure the nodes aren't too far apart. Make sure the link types are correct.

It can also happen if the bot locks onto a node that's in another Z level and they're trying to reach it through the floor or ceiling.

So, take a look at the area and see if there's anything odd with the nodes or links and add more nodes in between if needed.

Bots shoots already shot buttons

If you have a link pointing to an edict, they bot will always activate it regardless of the state. So, it will always shoot the button even though it's already been shot. Look into 'Use trigger if needed' scenario.

Places that you need a suit or invulnerability to reach

Bots will not consider health or if they have any powerup before jumping into lava / slime. If there's a good chance they'll die if they jump in, you'll have to skip it for now.

Extra stuff

I'll take the opportunity to plug some stuff from me related to the bots:

If you want to see me waypointing some maps, check out my Twitch streams / VODs[www.twitch.tv]. There's already a collection with 18h of content.. I waypoint too much :')

I've released a pack of waypoints for 10 custom deathmatch maps. Find it here along with the trailer.

I've launched Quake Nav Depot[github.com], which is a Github repository where you can find .nav for different maps and the community can submit their own (or improve existing ones) via Pull Requests.

If you need help doing navs or have questions, you can find me and others at the Quake Mapping Discord[discord.gg] as well as the Quake Bot Waypointers steam group.

Check out some of my other Quake guides or follow me on Twitter where I usually post some updates of what I'm up to and so on.

Credits

JPiolho - Guide
Maleficus - Clarifying some technical details

[rsb]

Thank you so much for this guide. In one evening, I added bot support to a custom map. Brilliant!

[Dakteris Māja]

Thank you. Good guide.

[Hardwater]

Great guide, thanks a lot!

[StoneCold]

@Jpiolho - I see you shared Twitch videos of you waypointing. This is awesome, going to watch them and see how you do it. Want to do some 3wctf maps in the next few days.

[JPiolho]

@StoneCold thanks. Yeah I keep updating it as I figure out something while doing my own waypoints, so check it out once in a while

[StoneCold]

Exceptional guide! I see you updated it with even more explanations. Really great job, will definitely make those of us who enjoy bots get extra mileage out of the new rerelease :)

[Ian Dancy]

genius work well done

[djartemis99]

this rocks, granted i now have to add .nav files to my mods