Manual/Using mods — openarena

A "mod" is an "add-on", a "modification" that changes one or more aspects of a videogame. Quake III Arena has support for mods, and id Software released an official (and commercial) mod called Team Arena for it (and many gamers created free mods for Q3A). Q3A and Q3:TA source code is now "free" (under GNU GPL license), so ioquake3 is born... and, even more important, OpenArena is born. So, OpenArena supports mods, like the game on which it is based. They can be written specifically for OpenArena, but many mods created for the original Q3A work also with OA! (Note: some mods could have some problems, for example missing textures).

OpenArena itself includes some aspects form Team Arena (like game modes and weapons), but there is a mod studied to include more features from TA: it is called simply The Mission Pack. It is installed with OA, you can try it when you want.

To find more mods for Quake 3 or OpenArena, you can search the Internet. Here are listed some:

Mods specifically written for OpenArena
ModCompat, compatibility tests results for mods written for Q3A (and, maybe, some other compatible games derived from id Tech 3 engine).

How to install a mod

You can place every mod into its own subfolder under OpenArena directory. Under Windows, this means that if your OpenArena is placed in C:\Program files\OpenArena (just an example, you can install the game in any folder you want! See also Manual/Install), you can find the .pk3 file of the mod called "missionpack" under the folder C:\Program files\OpenArena\missionpack.

Instead of under the OpenArena installation folder (also known as your "basepath" folder), the directory of a mod may also be installed under your "homepath" folder (the folder that contains your configuration and automatic downloaded files, usually separated for each user of the machine). Mods obtained via automatic download are stored there. In this case, the mod will be accessible only for the current user (a second user may have to autodownload/install the mod again, or to manually change his homepath folder to match the one of the other user -sharing the same configuration-, or to move the folder of the mod under the installation folder of OpenArena). Remember: mod folders have to be placed at the same level of the "baseoa" folder, not inside it. Do not place pk3 files from a mod into baseoa folder, unless you are sure they contain maps or models only, or you may cause problems!

Note: in the directory of a mod you can find just few .pk3 files, or (rare, except for testing purposes) many files and subfolders (for example, modname\maps). It depends if the developer has "packed" many files into few compressed files or not... with \sv_pure 0, the game should work in both situations, but with \sv_pure 1 (the most common and highly recommended setting), the game loads only stuff (like maps and textures... configuration files are excluded) that is packed inside .pk3 files. Usually you should not need to extract anything out of the pk3 files. Automatic download works with pk3 files only, and will not download anything out of them.
Technically, a .pk3 file is just a .zip file with another extension. So, you can explore this kind of files with compression managers, but usually you don't need this (and making changes inside a pk3 could give you problems with the "pure servers"). However, you could wish to export images or sounds from the game, or learn how to make your own maps, models, or mods...

Usually, you will download a mod inside a single compressed file (like ".zip", ".rar", ".7z"...). You can manage such files with various programs, for example 7-Zip is free. You will have to extract the content of this file inside the folder of OpenArena (be careful with the path: remember that Mods need a subfolder at "OpenArena/" instead of "Quake 3 Arena/".). Sometimes you will have to download and install multiple files (patches, extra maps...)... and you may need to install them following a specific order.

Some mods could be downloaded as Microsoft Windows executable files (.exe). They could be "real" installation programs, or simply "self extracting archives": in the last case, you should also be able to "manually" open them with compression programs (like Winrar, 7-Zip, etc.), and extract them like normal .zip files (so you could be able to extract them even if you are not using Microsoft Windows).

How to launch a mod

When you want to play a mod, you can:

Launch OpenArena normally, then select "Mods" in the main menù and choose your mod from the list. Click "load". If you have many mods installed, you can scroll down the list simply using down arrow or mousewheel under the lower entry shown on screen.

or

Launch OpenArena normally, then pull down the command console and enter /game_restart <mod's subfolder name> command. E.g. /game_restart missionpack. If you enter /game_restart without parameters, you will return playing baseoa, base game. Can be used also from dedicated server binaries (oa_ded).
Warning: if you type a non-existing modfolder name, it will be automatically created under your homepath folder, with its own configuration file!
Note: this command is from ioquake3, it does not exist in the original Quake 3 Arena game.

or

Launch the mod directly from the command line. For example, in Windows, you can do it from a command prompt or creating and modifying a shortcut to OpenArena.exe. Use openarena.exe +set fs_game <mod's subfolder name>. For example, for "missionpack" the command line will be openarena.exe +set fs_game missionpack. Sometimes starting a mod this way may workaround some problems. Can be used also with dedicated server binaries (e.g. oa_ded.exe instead of openarena.exe). Also on various other OSs, you can create custom shortcuts or "sh scripts" to quickly launch the game with specific command-line options without having to type them every time.
Warning: if you type a non-existing modfolder name, it will be automatically created under your homepath folder, with its own configuration file!

Some mods will include one (or more, with various command-line options) Windows "batch file" (.bat or .cmd) that will automatically launch the mod if you execute it. Note: if the mod was designed for Quake 3 Arena, you will have to modify the batch file to replace "quake3.exe" with "openarena.exe".

Some mods may include one or more pre-set configuration files (for example, one ready to start a dedicated server with FFA gametype and one other with CTF gametype), that you could edit with an text editor, and execute with the \execute <filename> command.

You should always read "readme" files included with mods.

Tip: if you launched a mod, but it looks like you are just back to standard OA main menu, don't worry immediately! Seeing the standard main menu does not necessarily mean the mod isn't working. There are various mods that do not customize the main menu, and there are mods which do not customize the GUI at all. You may try to actually play a map, to see if at least some of the rule changes brought by the mod are in place (many rules changes are often disabled by default).

Configuration

Each mod creates some configuration (like q3config.cfg -that should be automatically placed in a subfolder under your "homepath" folder-) and log files. Check the various menus for options not present in the "base" game (for example, you could need to bind a mod-specific function to a keyboard key) for proper configuration. Refer to a mod's documentation (usually, there is an html or txt "readme" file) for informations about its specific console commands.

Many settings (for example, the player's name) will be copied from the "base" OpenArena (from "baseoa" folder) to the mod's specific confiiguration file (e.g. to "missionpack" folder) the first time you start it, and later you will have to change the settings separately. After initial creation, many settings in each mod configuration become independent from baseoa configuration; some informations, however, are still "linked" and depend on baseoa (e.g. Single Player Deathmatch unlocked tiers and earned medals).
This means also that it is advisable to check that you correctly customized your baseoa settings as you wish, before you begin using mods. If you delete or rename a mod's q3config.cfg file, it will be created again the next time you run that mod, inheriting settings from baseoa again (and obviously, discarding customizations you previously made in the mod).

Configuration files are stored in a subfolder under your "homepath" directory (e.g. <homepath>\OpenArena\<specifc_mod>).
Under Microsoft Windows, you will find a mod's q3config.cfg file under %APPDATA%\OpenArena\<specific_mod> (for example, for "missionpack", a path could be C:\Documents and settings\username\Application data\OpenArena\missionpack under Windows 2000 or Windows XP and C:\Users\username\Appdata\Roaming\OpenArena\missionpack under Windows Vista or Windows 7). See also FAQ#Where are the configuration files saved?.

Note: please keep in mind that game logic (gamecode) of mods may be based upon previous versions of OpenArena or from Quake 3 Arena, thus some settings that correctly work in baseoa may not work in the mod. Some variables may have not existed at all at the time of that mod creation (and thus, having no effect at all); other variables may now manage more values than before, resulting in they working as expected when using some values, and not working as expected when using other values (and those not managed values may be inherited from baseoa to the mod config!). New ioquake3/OpenArena features managed by the engine (contained in binary files such as openarena.exe), primarily some graphic options, are much more likely to work on mods than those managed by the game logic, even if they do not have their option shown in the menu, but few of them may not work anyway.

How to find a server which uses a mod

You can use the server browser integrated inside OpenArena to find servers (select "Multiplayer" from main menù). Some mods show their own customized gametype description (for example, "Defrag"), so you can identify them by this name. But many mods mantain the "classic" names for game modes, so you can't know if a server is using a mod unless you connect to it, in this case. However, you can use an external server browser (like Qtracker) that also shows the mod's name. See also Servers#Tools.

Be aware that the same gametype number can mean different game types in different mods (for example, in baseoa g_gametype 9 is CTF Elimination mode, and in Excessive Plus mod g_gametype 9 is Protect the Leader mode), so the gametype filter could be confusing.

If you already know the address of the server you want to connect to, you can use "Specify" button or \connect command from command console.

If you want to join an online game which uses a mod, often you can connect to it without having to manually download the mod from a website and install it: if both you and server have "automatic download" option active, your machine will download the required files. Anyway, a mod obtained this way probably will not be "complete", for example it may include only the map you played the time you connected, while it could contain more of them, so you will keep downloading map after map each time you need a new one. Remember that, in OpenArena, automatically downloaded files are stored in a separate folder for each user of the machine.
They do exist some "serverside mods" which do not need the client to download stuff. In that case, you will not get a copy of the mod gamecode in your homepath folder. You can connect to such servers also in case you have automatic download disabled.

Note: the ability to use mods created for Quake III Arena does not mean that you can use OpenArena to connect to Quake III Arena servers, even if using the same mod. OpenArena uses a different protocol version than Quake 3. You can connect to an OpenArena server that is running a certain mod.

Troubleshooting

If you have problems, check our FAQ and Troubleshooting page, search for "readme" or "help" files inside the mods' folders, and check compatibilty notes in our pages about them here and here. You can also go to the forum.

If your problem is that when you start any mod from the "Mods" menù, the sound stops working at all, please check here. Probably a \snd_restart command may be enough to get the sound back.

Starting a mod direcly from OS's command line instead of using "mod" menu may workaround some problems, for example some errors related to the maximum number of variables reached.
- Another workaround for "too many CVARs, cannot create a new one!" errors could be to start two game processes: one in dedicated server mode and one as client (start the dedicated server, load a map, then start the client and join your own server, that you will find in your "local" network. See Manual/Multiplayer if you need help to do this.).

Mods written for too old versions (PointReleases) of Quake III Arena probably will not work with OpenArena (probably you will be able to use a Mod written for Q3A v1.32, but not if it was designed for Q3A v1.17). In this case, try if you can find a more recent version of that mod somewhere, it should be designed for Quake3 version 1.27 or later.

If you try to connect to a server, but you get kicked back to the main menu and in the console log (you may have to scroll it back) you can find an "ERROR: Client/server game mismatch" or "Invalid PK3 file3" message, check if you have "Automatic downloading" (Setup -> Game options) on or off: you may need some files that are not in your PC, and your system could not be able to get them from the server. You can also enable it with \cl_allowdownload 1 command. Note: it works only if the server has its option (sv_allowdownload) enabled. Remember that automatic downloading may be enabled in your main configuration (baseoa\q3config.cfg), but not in the configuration of the single mod (modfolder\q3config.cfg), so pay attention when you check, and enable it for the mod, too.
- If you cannot connect to a certain server because you don't have autodownload on, the quickest way is to use the console to set \cl_allowdownload 1 and then entering \reconnect command, without closing OpenArena first: this way it should connect again to the same server, autodownloading the files it needs.

Please notice that OpenArena 0.8.8 added some new autoswitch weapons modes (and changed the default mode to one of these), and such additional modes are not supported by old mods (those based upon gamecode older than OA 0.8.8), that know only "always" and "never" autoswitch modes. Please read autoswitch weapons for more infos.

In general, mods may lack some features that were not available in Quake3, and that were later added by OpenArena (e.g. some graphic options and many special game options). Some features, managed by the engine, may work if enabled via console although the graphic interface does not mention them.... other OpenArena features are managed by the gamecode (game logic) instead, and each mod usually uses its own game logic, so probably such features would not work at all in mods based upon Q3 gamecode or upon previous OA versions gamecode.

You can check which mod you are currently playing by typing /fs_game in console. If that returns "", you are playing "baseoa" (the main game). If that returns something else (e.g. "alternatefire", "hunt", "NIQ3"...), then you are playing the mod contained in the folder with that name.

If you cannot later play "locally" a certain mod that you autodownloaded by playing it on a server, it may be because your local copy may not be "complete" (as autodownload only gets the pk3 files required at that point), e.g. your machine may have downloaded the client-side GUI changes only, but not the server part gamecode, if they were stored in different pk3 files on the server... or maybe the mod may search for a specific series of additional maps (there are a few mods with such requirements), and you don't own some of them.
Maybe you may try to find an installation package for that mod on the web, or may take a look to the server infos (e.g. from dpmaster website) too see if there is a visible value for sv_dlURL variable ("fast downloading"), then go to such path with a web browser to try if you can manually download additional files from there.

Notes for Server Administrators

See also: Manual/Multiplayer#Mods

You can create your own server and have it running a mod. You can put there some additional stuff (typically more maps) that will be downloaded by the clients (remember to set sv_allowdownload 1), and then such downloaded stuff will be available for them also when later playing offline: if placed in the folder of the mod, only for that mod, and if placed in "baseoa" folder, for the whole OpenArena. When adding stuff to your mod folder, think if it is better to place each file in the mod's folder (usually everything except maps) or in baseoa folder (usually only maps and maybe models). Very important: place each mod in a separate folder, and do not place mod files in baseoa folder (unless you are sure they simply contain maps or models and not gameplay-modifying stuff), or you may mess up the program in the clients that connect to your server (that may experience strange behaviors or errors when playing offline after they downloaded files from your server: in that case, they would have to locate and remove the pk3 files they autodownloaded from your server, to fix their OpenArena). In general, pk3 files containing maps, located in baseoa, are downloaded only when the map is being used... pk3 files containing maps, located in each mod folder, are ALL downloaded, even if the map is not being used, before the client is allowed to play (a few mods may have further checks to download all their own maps even if they are in baseoa and are not currenlty used, but that's rare).
Server administrators can "mix" things in a mod (for example, take an existing mod created by someone else and add "brightskins" -an hack that makes players more visible-, or change some textues with customized ones)... sometimes even to the point that it is no more compatible with the original mod (for example, some modified versions of mods originally created for Q3 work under OA only, and no more under Q3). A good thing could be to place the new stuff in separate .pk3 files (instead of modifying the original pk3s), those filenames are with an higher "pakX-....pk3" (.pk3 files are loaded alphabetically, and, if there are conflicts -like two textures with the same name in two pk3s-, the last one "wins"), so the new files should simply be ignored when connecting to a server that has sv_pure 1 (most servers) and holds the "classic" version of the mod (anyway, the user would find your customizations when playing locally... and he could like it or not...). Another thing to do could be to change the name of the folder of the mod, thus making a completely separate mod from the original (thus, the client will have to automatically download all the needed files from your server)... this is especially advisable if the "new" mod is no more compatible with the original one (after modifying a mod, it could be a nice idea to make a try to connect from another client that already has the original version of the mod installed, in order to check if everything works correctly and what happens to that client after that).
Automatic Downloading usually does not provide great speeds. It's related to \rate (client-side) -that cannot go over 25000- and \sv_maxrate (server-side) settings, that control the maximum bandwith used for the connection between a client and the server. So, if you want to allow your players to automatically download required files at high speeds, you can enable "www download" (a.k.a. "http download"), hosting the files on a web server (HTTP or FTP) that will be accessed by the OpenArena client.
If you want to develop a "real" mod (not simply mixing pk3s done by others, but writing new code and modifying game logic -e.g. to invent a new gametype-), you can try to take a look to Mod#External links and Category:Development; you may want to use a recent OAX version as starting point.

External links

How to make a Quake 3 Arena mod