Creating-bot-waypoints.md

   1 Xonotic bots require waypoints to roam about the map and find items such as CTF flags, weapons and health packs. In this guide we are gonna see how to create a good network of waypoints for them.
   2
   3 ## Creating waypoints
   4
   5 #### Selecting the proper game mode
   6
   7 First of all you need to know what game modes are supported by the map you are going to waypoint and start the appropriated mode. To know this information you can right click on a map in the map list (menu / Singleplayer / Create window). For a map to appear in that list you need to put its .pk3 file in your ${xon_settings}/data/ directory.
   8
   9 * If a map supports **CTF**, you should start a CTF game since the editor automatically adds a waypoint for each flag. CTF waypoints are compatible with other modes (except Race and Assault) but keep in mind that waypoints of flags and all links from/to them will not be loaded in other modes. It's highly recommended to enable symmetrical editing on symmetrical maps as described in the [Symmetrical editing](https://gitlab.com/xonotic/xonotic/-/wikis/Creating-bot-waypoints#symmetrical-editing) section below.
  10
  11 * If a map supports **Assault**, you should start an Assault game and destroy all the objective but the last one before editing waypoints because otherwise there are doors / obstacles that block paths to other parts of the map. If you forget to do so, don't worry, you can make up by relinking all the waypoints with `wpeditor relinkall` after having destroyed all the objectives.
  12
  13 * If a map supports **Race or Race CTS and other modes** and if the map has the same layout in Race mode (some maps enable a completely different layout. e.g. Stormkeep) it's recommended to first edit and save waypoints for other modes (usually DM or CTF) so that whenever you start editing Race waypoints you can start from the existing ones. Once you save them in Race mode they become independent from the generic ones.
  14
  15 * If a map supports **only Race or Race CTS** you should start a Race game since the editor automatically adds waypoints for every check point. Saved waypoints are specific for this mode.
  16
  17 * For **all other game modes** you should start a DM game.
  18
  19 ## Configuration
  20
  21 * Commands to edit waypoints:
  22 ```
  23 wpeditor spawn               spawns a normal waypoint where you are standing
  24 wpeditor remove              removes the nearest waypoint
  25 wpeditor saveall             saves all waypoints and links
  26 wpeditor relinkall           relinks all waypoints
  27 wpeditor unreachable         determines waypoints, items and spawnpoints that can't be reached from the current position
  28 wpeditor spawn crosshair     spawns a waypoint at crosshair's position (in general useful to create special and hardwired links with ease from existing waypoints, in particular it's the only way to create custom jumppad waypoints (spawn another waypoint to create destination))
  29 wpeditor spawn jump          spawns a jump waypoint (spawn another waypoint to create destination)
  30 wpeditor spawn crouch        spawns a crouch waypoint
  31 wpeditor spawn support       spawns a support waypoint (spawn another waypoint to create destination from which all incoming links are removed), useful to replace links to problematic jumppad/teleport waypoints
  32 wpeditor hardwire            marks the nearest waypoint as origin of a new hardwired link (spawn another waypoint over an existing one to create destination)
  33 wpeditor hardwire crosshair  marks the waypoint at crosshair instead of the nearest waypoint
  34 ```
  35
  36 You can easily run all these commands and also toggle various useful settings in the waypoint editor menu (bind it to a key of your liking in the menu / Settings / Input window).
  37
  38 To your convenience I set up a config file with all the commands described in this guide (and more) bound to keys in an alternative bindmap so that your default keys won't be overriden. Save [th_waypointeditor_config.cfg](uploads/af2f46e366956e6ec336515564664d42/th_waypointeditor_config.cfg) into your data directory, open it in a text editor if you want to change keys then in the Xonotic console run `fs_rescan` and `exec th_waypointeditor_config.cfg`. From now on to enable keys and settings on the fly you can just exec `th_waypointeditor_enable` to enable the waypoint editor and `th_waypointeditor_disable` to disable it (instead of toggling the g_waypointeditor cvar).
  39
  40 #### Add / edit waypoints
  41
  42 * Waypoint types:
  43
  44 | Color | description |
  45 | ------ | ------ |
  46 | White  | normal waypoints                                                                                                       |
  47 | Yellow | autogenerated waypoint (jumppads, teleporters, warpzones, ladders)                                                     |
  48 | Red    | autogenerated waypoint for certain items that are crucial for the current game mode (e.g. CTF flags, Race checkpoints) |
  49 | Purple | waypoint with one or more hardwired (outgoing) links                                                                   |
  50 | Orange | Jump and Custom jumppad waypoints                                                                                      |
  51 | Cyan   | Crouch waypoint                                                                                                        |
  52 | Green  | Support waypoint (useful to replace incoming links of a problematic teleport / jumppad)                                |
  53
  54 |  Normal waypoint |  Support waypoint |
  55 | :------: | :------: |
  56 | ![normal_wp](uploads/9573c68889648122385609f314b1f077/normal_wp.jpg)  | ![support_wp](uploads/ffc9cef7d586de00266c20d4eeffaaf8/support_wp.jpg) |
  57 | Links to all the waypoints (except the teleporter waypoint which has a support waypoint) | Links only to the destination waypoint (the teleporter waypoint which can't have any other incoming link) |
  58
  59 | Hardwired waypoint | Crouch waypoint |
  60 | :------: | :------: |
  61 | ![hardwired_wp](uploads/80220aa4479a827e72b0a3734c9b237e/hardwired_wp.jpg) | ![crouch_wp](uploads/77207df550e8c0316e08bdd696917493/crouch_wp.jpg) |
  62 | Normal waypoint with one or more hardwired link | Links to all the waypoints within 100 qu range |
  63
  64 | Jump waypoint | Jump waypoint linked to a Crouch waypoint |
  65 | :------: | :------: |
  66 | ![jump_wp](uploads/ae680fd80bdf748fdee6d2f9186dada3/jump_wp.jpg) | ![jump_wp_to_crouch_wp](uploads/bdb424baaeff32bf3f406b43be17e5a6/jump_wp_to_crouch_wp.jpg) |
  67 | Links only to the destination waypoint(s) | Links only to the destination waypoint(s) |
  68
  69 Enable the waypoint editor with `g_waypointeditor 1` or `th_waypointeditor_enable`, start a map and become a player to be able to edit waypoints.
  70
  71 If there are no user-made waypoints you can see only the autogenerated ones (yellow and red).
  72 Start by adding normal waypoints with the command `wpeditor spawn`, the editor will then automatically generate links between them. Outgoing links are displayed as lightnings popping out from the nearest waypoint, if you want to see the incoming links you have to hold the `CROUCH` key down (default key: SHIFT).
  73
  74 A link from waypoint A to waypoint B means that a bot can theoretically safely walk from A to B (it can even jump obstacles but not gaps), even though in practice it depends on waypoint position and bot skill: bot may face some difficulties, for example if too close to a ledge or turning while approaching to A. In general to avoid bad surprises you shouldn't put waypoints too close to wall edges, gaps or dangerous places.
  75
  76 It's recommended to add waypoints near items that bots often run to such as powerups, weapons and health/armor packs. When you spawn a waypoint really close to an item it gets automatically snapped to its origin. If not desired, this behavior can be turned off on the fly by holding the `CROUCH` key down (default key: SHIFT) when you create a waypoint.
  77
  78 Bots can swim too if you put waypoints in the water or even above the water surface, which is preferable since players can move faster jumping over the water.
  79
  80 Use the command `wpeditor saveall` to save waypoints and links, preferably run this command periodically to avoid accidental loss of waypoints you have added since the last save.
  81 It will generate 3 files in your data directory:
  82 * `data/data/maps/<mapname>.waypoints` containing waypoints data
  83 * `data/data/maps/<mapname>.waypoints.cache` containing links data
  84 * `data/data/maps/<mapname>.waypoints.hardwired` containing hardwired and special links data
  85
  86 In Race or Race CTS mode, you will get these files instead:
  87 * `data/data/maps/<mapname>.race.waypoints`
  88 * `data/data/maps/<mapname>.race.waypoints.cache`
  89 * `data/data/maps/<mapname>.race.waypoints.hardwired`
  90
  91 #### Symmetrical editing:
  92
  93 The waypoint editor has a very useful editing mode that halves time required to waypoint symmetrical maps (mostly the CTF ones): every time you spawn / remove a waypoint, the same operation is repeated on its symmetrical position.
  94
  95 First of all you need to figure out the map symmetry:
  96
  97 1. **Point reflection**: the most common among Xonotic maps (Dance, Implosion, Geoplanetary), half part of the map is (horizontally) rotated by 180 degrees around a point (origin) that is the center of the map.
  98 1. **Reflectional symmetry**: less common (Runningman CTF), half part of the map is a mirror-image of the other one, the axis of symmetry is in the mirror-line.
  99 1. **Rotational symmetry** (of order 3 or greater): rarely used as it needs 3 or more flags (gasoline_3teams, gasoline_4teams). With order 3 a part of the map is rotated twice by 120 and 240 degrees around a point (origin) that is the center of the map.
 100
 101 _Automatic calculation_
 102
 103 On CTF maps that are perfectly symmetrical, if you think map symmetry is 1) or 3) use `g_waypointeditor_symmetrical 1`, if you think it's 2) use `g_waypointeditor_symmetrical 2`.
 104 Check that the symmetry settings are correct by spawning some test waypoints and checking that the symmetrical waypoints are spawned *exactly* where they should be: if they respect map symmetry then you are ready to waypoint the map.
 105
 106 _Manual calculation_
 107
 108 On non-CTF maps or if automatically calculated symmetry doesn't work well (symmetrical waypoints can't be found or are in a wrong position) it's possible to manually determine the origin or axis of symmetry with the commands `wpeditor symorigin get|set p1 p2 ... pX` and `wpeditor symaxis get|set p1 p2` where p1 p2 ... pX are positions "x y z" that you know are perfectly symmetrical. With `get` values of origin / axis are printed to the console, with `set` values of origin / axis are applied immediately (saved to the g_waypointeditor_symmetrical_* cvars).
 109
 110 To find perfectly symmetrical positions, you can go to a place of the map where you are blocked and can't move further away from origin / axis of symmetry, e.g. the corner of a room, print the origin of your player model to console for example with "say %o" or by spawning and removing a temporary waypoint, move to the symmetrical place of the map and do the same.
 111
 112 Before calculating and applying symmetry settings from those positions, make sure there is no user-made waypoint on the map, you have to manually remove them because they lack the corresponding symmetrical waypoint. To calculate and apply symmetry settings, use the appropriated `set` command with those positions as parameters.
 113
 114 Example 1:
 115 ```
 116 p1: "-700 -2000 600"
 117 p2: "700 -2000 600"
 118 wpeditor symaxis set "-700 -2000 600" "700 -2000 600"
 119 ```
 120 Output:
 121 ```
 122 Axis of symmetry based on input points: "-1400000000 2000"
 123  saved to g_waypointeditor_symmetrical_axis
 124 g_waypointeditor_symmetrical has been set to -2
 125 ```
 126
 127 Example 2:
 128 ```
 129 p1: "-500 -1000 200"
 130 p2: "500 1000 200"
 131 wpeditor symorigin set "-500 -1000 200" "500 1000 200"
 132 ```
 133
 134 Output:
 135 ```
 136 Origin of symmetry based on input points: "0 0"
 137  saved to g_waypointeditor_symmetrical_origin
 138 Order of symmetry: 2
 139  saved to g_waypointeditor_symmetrical_order
 140 g_waypointeditor_symmetrical has been set to -1
 141 ```
 142
 143 Spawn and verify some test waypoint to make sure the calculated settings are correct before proceeding waypointing the map.
 144
 145 The symmetry settings are saved to the waypoint files and automatically reloaded from there when you restart the map.
 146
 147 #### Advanced editing
 148
 149 * *Hardwired links*
 150 There are paths that bot can actually walk but the editor refuses to link due to small gaps or dangers. To link these kind of paths you can add a hardwired link with `wpeditor hardwire`: marks the nearest waypoint as origin of a new hardwired link (spawn another waypoint over an existing one to create destination).
 151
 152 * *Jump waypoint and linking*
 153 To create a jump waypoint you can use the command `wpeditor spawn jump` 60-80 qu before the edge depending on jump length then spawn a normal waypoint as destination waypoint on the other side of the gap. Note that jump waypoints (like jumppad waypoints) don't have any other normal outgoing link. Multiple jump links can be added to the same jump waypoint calling the command `wpeditor spawn jump` in the very same position of an existing jump waypoint and creating another normal waypoint as destination. You can recycle an existing destination waypoint as well by spawning a destination waypoint over an existing one.
 154
 155 * *Custom jumppad waypoint and linking*
 156 Sometimes jumppads with a vertical jump trajectory don't have any automatically generated link, you can manually make them usable by bots by adding a custom jumppad waypoint in this way: aim at a jumppad and spawn a waypoint with the command `wpeditor spawn crosshair` then spawn a normal waypoint on the desired destination point. Some testing is needed to make sure bots can really use it and reach the destination waypoint.
 157 With the same procedure it's possible to change destination waypoint of an automatically linked jumppad, for example when the destination waypoint is in a too dangerous position.
 158
 159 * *Spawn waypoint at crosshair*
 160 The command spawning a waypoint at crosshair is very handy to add more jump links to a jump waypoint: simply aim at the jump waypoint and run `wpeditor spawn crosshair`, then aim at the desired destination waypoint and run the same command. To create a new hardwire link with ease you can use the command `wpeditor hardwire crosshair` to mark the aimed waypoint as origin, then `wpeditor spawn crosshair` to mark the aimed waypoint as destination.
 161
 162 * *Crouch waypoint and linking*
 163 To create a crouch waypoint you can use the command `wpeditor spawn crouch`. They are automatically linked to other waypoints but only if really close (less than 100 qu).
 164
 165 * *Support waypoint and linking*
 166 Some teleporters and jumppads refuse to create links from waypoints that aren't in front of them, to fix them you can create a support waypoint: spawn it very close to the problematic waypoint with the command `wpeditor spawn support`, then aim at the problematic teleporter / jumppad waypoint and execute `wpeditor spawn crosshair` to create a special link that is exclusive for that teleporter / jumppad. Since the support waypoint doesn't have any other outgoing link, bots will always use it as intermediate waypoint to reach the problematic waypoint. If you used a normal waypoint instead, it would create a lot of useless outgoing links.
 167
 168
 169 ## Optimizing waypoints
 170
 171 The less links / waypoints you add, the better because in game every bot takes up quite some processing power to determine the best path for a goal.
 172 To do so check that every waypoint is linked to as many waypoints as possible and remove redundant waypoints. Sometimes moving a waypoint a few qu (quake units) away is enough to create another link while keeping other links. For fine adjustments it's useful a key that temporarily sets slowmo to 0.1.
 173 If you want to examine better links of a certain waypoint you can lock link view by aiming at it and running the command `wpeditor lock` (to unlock it run the same command again while aiming somewhere else).
 174
 175 Make sure most of the important items (weapons, health / armor packs) have a waypoint very close to them as it helps to speed up initial path search. In particular, for this optimization to work the nearest waypoint of an item should be within 50 qu from where the bot touches the item (sometimes depending on map layout an item can be reached only coming from a single direction). When possible use item waypoints as path waypoints so to keep waypoint count as low as possible.
 176
 177 Use the command `wpeditor unreachable` to reveal waypoints and items unreachable from your current position; it will also reveal spawnpoints without a nearest waypoint where bots would stand still after spawning. Unconnected waypoints/items will appear with a different color and a detailed report is printed to console too. To restore correct waypoint colors you can either (save waypoints and) restart the map or run `wpeditor relinkall`.
 178
 179
 180 ## Testing waypoints with bots
 181
 182 Recomended settings:
 183 ```
 184 bot_nofire 1
 185 bot_debug_goalstack 1
 186 skill 4
 187 bot_number 1
 188 ```
 189
 190 Check how well bot navigates the map with your waypoints: add a single bot with medium skills (`skill 4`) and spectate it (preferably in free third person view by pressing `BACKSPACE` twice so you can control camera angles with your mouse); if you notice it takes weird paths (zigzags), gets stuck, bumps into walls, falls down or can't jump an obstacle then you have to adjust waypoints to create more reliable links.
 191 It is also a good idea to test how high skilled bots behave as they can bunnyhop (skill 7 and higher) and sometimes they can lose control.