A map rotation script is a series of commands which server admins pre-configure to have the game cycle between different maps automatically. Map change happens after match end, or in case players successfully vote for nextmap (/callvote nextmap unless that's disabled in g_votenames), or in case server admin enters /vstr nextmap command.

Map rotation scripts are supported since the original Q3A, and should work with most mods.

How-to

A map rotation script is made of a series of user-generated cvars (variables), and each one contains a few commands: each one loads a map and then sets the "nextmap" variable telling it has to "run" another user-generated cvar next. The last one sets the first one as next. Then there is a commad which "runs" the first one, starting the loop. You usually write down those user generated variables in a cfg file, then you "exec" it, and the rotation starts.

A classic rotation script is structured as follows:

set <first_variable> "map <first_map>; set nextmap vstr <second_variable>"
set <second_variable> "map <second_map>; set nextmap vstr <third_variable>"
...
set <last_variable> "map <last_map>; set nextmap vstr <first_variable>"
vstr <first_variable>

Let's translate into an example with real maps:

// Map rotation script
set m1 "map aggressor; set nextmap vstr m2"
set m2 "map oa_dm1; set nextmap vstr m3"
set m3 "map wrackdm17; set nextmap vstr m1" 
vstr m1 // start loop at m1

This would play aggressor, then oa_dm1, then wrackdm17, then aggressor, then oa_dm1 and so on...

"Vstr" is the command which "executes" a cvar like its content was typed directly in command console. "m1", "m2", "m3" are the names of the user-generated cvars we are using: you can name them as you wish (a1, a2, a3... loop1, loop2, loop3... d1, d2, d3..., etc.), as long as you don't use the names of existing variables or commands. The quotes mark the beginning and the end of the content of each cvar. The ; separates commands within the same line. Whatever follows // is considered a "comment" and not parsed.

You may type the script directly in console... but the most common behavior is to prepare the rotation script externally, using a text editor to create a plain text file to be placed under your baseoa (or current mod) folder^[1] (e.g. myrotation.cfg), then start OpenArena (full game or dedicated server binaries) and use the command console to run the configuration file which contains the rotation script, such as /exec myrotation or /exec myrotation.cfg

It is possible for the server admin to "jump" directly to a step of the loop, after the configuration file has been executed once, by typing /vstr <variablename> in console (where <variablename> is one of the variables you used in your rotation script, such as "m2" or "loop3" or "a1"... it depends from the names you choose!). Then the cycle will continue normally from there onwards.

Changing game options between matches

See also: Basic game options, Special game options, Configuration examples.

Map rotation scripts can be used to change A LOT of things between matches! Not only map, but also fraglimit, timelimit, capturelimit, players' speed, dmflags, instant-gib option, etc. etc. etc. You may even use it to just change settings between matches, while loading the same map every time.

What you need to do is to add the settings you wish to change, followed by ";", usually before the "map <mapname>" commands in the script.

Let's modify the previous example this way:

// Map rotation script
set m1 "timelimit 10; map aggressor; set nextmap vstr m2"
set m2 "timelimit 8; map oa_dm1; set nextmap vstr m3"
set m3 "timelimit 5; map wrackdm17; set nextmap vstr m1" 
vstr m1 // start loop at m1

This script would make the match last 10 minutes when playing in aggressor map, 8 minutes when playing in oa_dm1, 5 minutes in wrackdm17, 10 minutes in aggressor, 8 minutes in oa_dm1 and so on...

This example shows how to manage changing multiple settings:

// Map rotation script
set m1 "g_knockback 1000; g_instantgib 1; map aggressor; set nextmap vstr m2" // 1000 is default knockback (the "push" you receive by weapons)
set m2 "g_instantgib 0; g_rockets 1; g_gravitymodifier 0.8; map oa_dm1; set nextmap vstr m3"
set m3 "g_rockets 0; g_gravitymodifier 1.0; g_knockback 1200; map wrackdm17; set nextmap vstr m1" // 1.0 is default gravitymodifier
vstr m1 // start loop at m1

This would play aggressor map in instantgib mode, then oa_dm1 in all rockets mode and low gravity modifier, then wrackdm17 with higher knockback, then aggressor in instantgib mode, then oa_dm1 in all rockets mode and low gravity modifier and so on.

As you can see, each step first cares about "undoing" the settings from the previous step that it doesn't need. As the whole script is a loop, the last step acts as "previous" for the fist one, so the first step "undoes" the settings of the last one which it doesn't need.

Keep in mind

• IMPORTANT: be aware that changing gametype directly through admin console or through callvote seems to completely break map rotation scripts, resulting in the game playing the same map over and over again (then requiring server admin to manually start the cycle again, by using either /exec <rotationfile.cfg> or /vstr <one_of_the_cvars_of_the script>). It looks like it is this way since the original Q3A. Hence, you may consider to do not allow voting for gametype (through editing g_votenames variable), or to use g_autonextmap (random map change) instead of classic map rotation script. Or one may set up custom votes to give players the chance to vote for "start map rotation" (to execute the rotation script again): although that doesn't seem too intuitive (MOTD may help), it may still be an option. Changing gametype directly through the rotation script works correctly.
  • The server admin may type /g_gametype <n>; vstr nextmap in the same line, in order to change gametype and go to the next map without breaking the script (replace <n> with desired gametype number). Other possibilities include /g_gametype <n>; exec <rotationfile.cfg> to change gametype and restart the script at the same time, or /g_gametype <n>; vstr <one_of_the_cvars_of_the script> to change gametype and jump to a specific step of the loop, without breaking the script.
• Callvoting for a different map, even not included in the rotation script, does not seem to be a problem: when the match on the player-selected map will end (or if they will callvote for nextmap), the rotation script should resume normally.
  • Changing map directly (the server admin typing the "map" command in console), instead, breaks the map rotation script as it sets nextmap to map_restart 0. The same happens in case the map is changed by g_autonextmap.
• Each map rotation script follows a pre-defined cycle. You can of course prepare different .cfg files to fit different needs and exec them when needed.
• To give some more variation to the players, you may prepare different rotation scripts in different configuration files, then set up custom votes to allow players to vote for running a script or another one (e.g. a vote for "small maps rotation" and one for "large maps rotation"), with each custom vote option doing a different "exec <rotationfile>" command. You may use message of the day to inform players about such opportunity. Custom votes are allowed since OA 0.8.5 gamecode (they are not supported by older mods).
• If you want your rotation to be started as soon as you open the game, you may either:
  • Use a text file file named autoexec.cfg, either by writing the script directly there or by having your autoxec.cfg invoking your rotation file (e.g. ending with exec myrotation.cfg line).
  • Create a shortcut^[2] or batch file/shell script in your OS (or simply type in your OS command prompt/shell console each time) which would launch the game and execute the script. Example: "C:\games\openarena\openarena.exe" +exec myrotation.cfg. This can be expanded to loading a mod and starting a script, such as "C:\games\openarena\openarena.exe" +set fs_game modfolder +exec myrotation.cfg.
• It is possible to use "auto change map" feature (g_autonextmap) as an alternative to map rotation scripts. In that case, the next map will be picked up randomly instead of following a fixed cycle (you can customize the "mappools" by editing apposite lists to decide which maps will be available). This feature is supported since OA 0.8.8 gamecode (it's not supported by older mods).
  • In order to have classic map rotation scripts working as expected, you need to have g_autonextmap disabled (set to 0).
• As it looks like in Tournament (1v1) mode there is no "match ending", using/callvoting "nextmap" may be the only way to proceed to the next step of the loop. The same may apply to other gametypes in case no timelimit and fraglimit/capturelimit are set.
• nextmap is an important cvar. Server admin can "execute" its content with /vstr nextmap, and the game will do it automatically after match end. In case you don't change its content with the map rotation script, the game will usually set its value to "map_restart 0" (0 are the seconds before map restart, meaning the map will be restarted immediately if you do vstr nextmap).
  • Pay attention, in case you incorrectly set nextmap variable (e.g. set it empty), the game would not start a new match after the end of the current one! Typing "/reset nextmap" would make it empty! Manually loading a map with "/map <mapname>" command will set nextmap to "map_restart 0".
• The same cfg files containing a map rotation script may contain also other commands/variables not strictly related to the map rotation script itself.
• It is possible to use wait <number> to add a delay before the next command is executed (example: g_gametype 5; wait 1000; map wrackdm17 would add a short delay before proceding to load the map). Pay attention to do not use excessively long times, as also further commands typed directly in the console will be queued! Even quitting from the main menu will have to wait for the "wait" time to end.

Notes

See also

• G_autonextmap
• Configuration examples
• Manual/Multiplayer
  • Manual/Multiplayer/Advanced
• Servers
• Command console
• Basic game options
• Special game options
• Disabling and replacing items