Back to tutorial index page

Compiling the map

Throughout this series of tutorials mention has been made of compiling the map or creating the bot file. In order to play a map in Q3 it is necessary to compile it (meaning the computer performs a series of number crunching activities to convert the .map file, which is basically a .txt file, into a format which can be used by Q3). The resulting compiled .map file is known as the .bsp, the .map file is not required to play the level, just the .bsp. The program used to compile a map is Q3map2.exe, developed from the original Q3map used by id software by Ydnar.  The latest, and probably final build of Q3map2 is available here. Locate the version of Q3map2 that was distributed with GTK, and replace it with the newer version. Examine the readme.txt file and place the textures and shaders that are distributed with Q3map2 in their relevant folders.

Compilation of the map involves 3 stages: BSP, VIS and Light. We will return to this a little later. The bot file, or .aas, is compiled using the bspc.exe. The .aas is compiled from the .bsp, therefore it is necessary to compile the .map first. Any changes made to the map, and hence the .bsp will require you to recompile the bspc, or else the bot file will not function. Without a functioning .aas file bot play will not take place.

So how are Q3map2 and the bspc used? Well, you have 3 options: The most simple is to locate the bsp menu from the GTK tool bar, then select the options you want to use. You can use batch files to run the programs externally of GTK, or if you choose to use an easier and more effective method, grab yourself a front end compiler with a handy user interface which automates all the complicated parts of the process. The main 2 front end compilers are Q3map2toolz and Quake Toolkit.

The next stage is to have a good look at the Q3Map2 Handbook. For Each stage of compiling the .map file it is possible to set a number of switches and values that will influence the way the map looks and plays.

Below is a copy of my q3map.bat, for compiling with Q3map2 and the bspc, with the switches I wanted set for both programs:

"C:\Program Files\Quake III Arena\GtkRadiant\q3map_2.5.16_win32_x86\q3map2.exe" -meta -fs_basepath "C:\Program Files\Quake III Arena" "C:\Program Files\Quake III Arena\baseq3\maps\"
"C:\Program Files\Quake III Arena\GtkRadiant\q3map_2.5.16_win32_x86\q3map2.exe" -vis -saveprt -fs_basepath "C:\Program Files\Quake III Arena" "C:\Program Files\Quake III Arena\baseq3\maps\"
"C:\Program Files\Quake III Arena\GtkRadiant\q3map_2.5.16_win32_x86\q3map2.exe" -light -fast -faster -patchshadows -gamma 1.4 -samples 2 -fs_basepath "C:\Program Files\Quake III Arena" "C:\Program Files\Quake III Arena\baseq3\maps\"
"C:\Program Files\Quake III Arena\GtkRadiant\bspc.exe" -optimize -forcesidesvisible -bsp2aas "C:\Program Files\Quake III Arena\baseq3\maps\"
@echo off

The paths will need to be edited for your installation, switches and your map name.

To run the compiled map in Q3, drop the console and type: /sv_pure 0, press enter, then type, /map or /devmap followed by yourmapname, where yourmapname is the name of your map. You should not add the .bsp extension to the map name.

So what do all these confusing switches and options do? Once again, take a look at the Q3Map2 Handbook, which explains in far more depth than is possible here. Only the most important and often used features will be covered in this tutorial.

Let's start with the bsp process. In order to avoid max visibility errors and the process failing, always compile with the option -meta set.

Next, is the Vis stage. Never set -fast, this is no longer necessary if you build your levels using structural and detail brushes correctly. In the past Vis could take a very long time to calculate, so the  -fast option (where the map is divided into the default blocksize and no further calculations are made) offered a quick alternative for test compiles. Now, even with a very large map, Vis should not take long to compile. No further switches need to be set.

The final stage of the process is the compiling of light, where the lightmap is calculated. Depending on the map and the switches you choose, this can take no time at all, or many hours. Always set -fast, this speeds up the process and seems to have no detrimental effect upon the final result. Another good idea is to set -patchshadows, which allows patches to cast shadows, and also improves the look of shadows that they receive. Setting -gamma with a value of somewhere between 1 and 2.2 helps increase the overall brightness of the level. If there are any over bright spots try setting -compensate 4 as well. The -samples switch helps tidy up the edges of shadows, in the above example the value of 2 has been set. Compiling the light stage with these options is fairly quick. Setting the -bounce switch with a high value, say of 8 will seriously slow things down. By using the -bounce option you enable radiosity, this has the effect of smoothing light that strikes surfaces and blending shadow. The effects achieved through using -bounce can be remarkable, but the pay off is the massively increased compile times.

The best way to learn about the different options offered by Q3map2, apart from research, is to use it. Experiment and find a look that you feel suits your level.

Finally, let's look at the bspc options. Generally these are far fewer than the options available for Q3map2. If you compile the BSP stage with -meta, which you should always do, you must set the -forcesidesvisible, or else the bots will hardly play at all. Set the -bsp2aas switch so that the .bsp is used to generate an .aas file, and always set the -optimize switch or else the .aas file could outstrip the size of the .bsp file.

That's about it. If the map has a leak, this will be reported during the compile stage. In GTK, go to File, then select pointfile..., this generates a red line that leads to the leak spot that requires fixing.

There are many, many errors that can be generated during compile, some of which cause a problem, and some of which do not. Generally speaking, errors that are reported during the .bspc stage can be ignored. If you get stuck visit for support.


Finishing the level, creating the .pk3 and tying up loose ends


So what else is there to do before the map making process is complete? Some finishing touches would include adding a message that gets shown on the screen as the map loads and adding some music to the level itself. A starting position is required for spectators and for the final scoreboard. If the level is intended for team play some location identifying messages are needed to keep track of your team.

Let's discuss each of the above in turn. To display a start up message and add music to the level it is necessary to add more  keys and values to worldspawn (fig.1). The key music and a value that points to the music file adds the level music. To create a start up message add the key message where the value is the message you want shown.


The location messages are done by placing target_location entities (fig.2). Try to position the entity centrally in an area, players location will be identified by the target_location to which they are closest. It is possible, if desired, to set the colour of the printed message, using the key count and a value as described in the entity's notes. One word of caution, over use of this entity increases the information sent and received by computers when playing online or over a network. Judicial use is recommended.


The spectator spawn point and end level position is indicated by an info_player_intermission entity (fig.3). A map can only contain a single info_player_intermission. Rotate using the angle and angles keys as required and try to position in a particularly interesting setting.




For distribution compiled levels, and all the custom content that they require, are placed inside a .pk3 file. This is simply a .zip file that has been renamed. Make sure that in your computer settings you have not hidden file extensions, as this will result in problems renaming files. The zip contains folders, the exact same name as those found in the baseq3 folder (maps, scripts, textures, etc). Into these folders go the compiled map, the bot file and any custom content. When placed in the baseq3 folder, Q3 will read the map directly from the .pk3. To avoid confusion, when it comes to paking up a map it is often easier to create a folder named after your map (personally I usually place it on the desktop, but that's up to you). Inside the folder create the folders needed, these will always include: maps, scripts and levelshots. More on what goes in these folders in a moment. If you have used custom content that too must be included in its base folder (e.g. textures, with a folder inside named mymapname, or models/mapobjects/mymapmodels). Only include content that is required for the map, as mentioned previously, models get 'baked' into the .bsp, so do not need to be included, but their textures and any shaders do. The .pk3 containing the sample maps have to following folder structure:




Models, with a folder inside named mapobjects


These folders are added to a zip files and then renamed as a .pk3. As a matter of choice I use Winzip to create zip files, but any compression utility that can create .zip files will do.

Let's discuss what exactly goes in each folder in turn:

In the maps folder are placed the .bsp and .aas files. In the sample .pk3 the .bsp and .aas for both the FFA and CTF versions have been included. The source .map files are not normally required, but because they support this series of tutorials their inclusion is essential in this case. There are also 2 folders containing a number of .tga art files. These folders were generated by Q3map2 as part of its computation of dynamic lighting effects. In order for in game textures effected by dynamic lights to be shown, these folders must be included.

The scripts folder contains a .txt file, giving information about the levels and thanking those people who have assisted. The folder also contains the shader scripts used by the level or required for custom models. Remember if you pulled the shader from another map or source, you must include the entire script, not just the portion of it that may be applicable to this level. In short, if you use somebody else's shader, DO NOT EDIT IT! When writing shaders to use, cutting and pasting to another shader script is fine as long as credit is given, but changing the content of an existing script will effect the way the shader works in other levels that use the same script. Also contained in the scripts folder are 2 .arena files. An .arena file is a renamed .txt file. For the level or levels to appear in the Skirmish Menu in Q3, each must have its own .arena file named mymapname.arena, where my map name is the EXACT name of the .bsp for that level. The sample text from the dk_lmtutctf.arena follows:

///killer pandas/////////
///by dONKEY///////

map "dk_lmtutctf"
bots "major grunt doom bones visor razor"
longname "killer pandas-ctf"
capturelimit "8"
type "ctf"

The dk_lmtutffa.arena contains the following text:

map "dk_lmtutffa"
bots "major grunt doom bones"
longname "killer pandas-FFA"
fraglimit 25
type "ffa tourney team"

The .arena files give required information, regarding bots to be loaded, map name, frag or capture limit, and game type to be set.

Into the textures folder go any custom textures used, placed in side their folders. A common mistake is to fail to include textures from the mapmedia.pk3, which came with GTK and was not distributed with the original game. The confusion arises because the textures in the mapmedia.pk3 will be included in the standard id texture sets. The importance of testing the level in a clean install of Q3 can not be stressed enough.

The Models folder contains any custom model textures, as already mentioned, in a normal .pk3 do not include the .md3 or .ase files. The sample .pk3 does contain the actual models as they are required by the editor. Normally models go inside a mapobjects folder inside the models folder. Inside the mapobjects folder each model or relating texture should be placed into its own folder.

The image shown as the map loads is placed into the levelshots folder. Do not make the image too large. A 512 by 512 pixel .jpg is normal. If the image is excessively big the over all size of the .pk3 increases with little benefit and the skirmish menu can start to lag. A useful trick for taking good screen shots is to turn off the gun and all 2d in game icons, /cg_drawgun 0 and  /cg_draw2d 0 entered in the console will have the desired result. The same commands followed by 1 will restore the gun and icons.

There are some packing utilities available that automate the process of creating a .pk3. The most commonly used is probably mapacker, available from Equims Emporium, be sure to download the GUI as well so that the utility works from a handy, user friendly check box window. Be sure you do not include your common.shader in the .pk3, this is not required under normal circumstances. At the time of writing the mapacker utility does not find .ase model textures, so if necessary these must be added by hand.

Most mappers have 2 installs of Q3. One contains all the collected custom content, the other only the original .pk3 files that came with the game and its subsequent updates. Always run the new .pk3 in the clean version of quake. If you have missed any textures or shaders out of the .pk3, this will highlight the problem. The console reports errors. Drop the console and type /condump mymapname.txt, locate the mymapname.txt file in your Q3 directory and open it. The console read out that you have just saved will inform you of what the game can not find. Add the missing files to the .pk3.

In order to distribute the .pk3 it is common practice to place the file inside a zip file. Not only will this help reduce the upload/download times by shrinking the file size a little, but will avoid the problem of some hosts considering the .pk3 a suspect file type.

Before a level is considered final it is normal to under go a series of beta testing. Make the level available for testing, either to friends or posted at a level making forum, such as Consider and act on feed back received before releasing a final, completed level. If alpha testing of the level was done correctly, feed back arising from the beta testing stage should be concerned with minor game play, item distribution, lighting or detail issues, rather than complicated rebuilding of entire areas of the map.