Hosted by M5 Hosting
Valid XHTML 1.0!

debian_logo.png radiant_logo.png urbanterror_logo.png

Debian Linux + GtkRadiant + Urban Terror Mapping HOW-TO

This guide will explain how to install GtkRadiant 1.6 (also known as "ZeroRadiant") on Debian Linux 5.0 (Lenny) and on Debian Linux 6.0 (Squeeze). This guide will also show you how to create your first map for Urban Terror. Linux is an excellent platform for making maps. Debian was chosen as the operating system for this tutorial because the author believes that Debian is a very polished Linux distribution that is well-suited for novice Linux users. Also, Ubuntu Linux derives from Debian, so this guide will work for Ubuntu users with few [if any] modifications to the instructions.

This guide is divided into 5 main sections:

If you see mistakes in this HOW-TO or any room for improvements, please don't hesitate to contact me at . You may also email me if you find serious bugs in GtkRadiant, because I am helping to maintain the GtkRadiant code.

This tutorial is under SVN source control. To obtain the latest version of this tutorial via SVN and/or to browse its history:

user@debian:~$ svn checkout svn://

Section 1: Compiling and Installing GtkRadiant

GtkRadiant does not need graphics hardware acceleration (3D acceleration) to compile or run. However, it will run much better with graphics hardware acceleration. If you have an NVIDIA or ATI graphics card, you should install and configure the proprietary graphics driver for your card at this point (before compiling GtkRadiant). There are detailed instructions on how to do this on the Debian Wiki pages, both for NVIDIA and ATI cards.

Step A: Install Dependencies

The first step is to install some extra packages that are required to compile/run GtkRadiant. Each of the commands below may automatically install a number of additional packages in order to meet package dependencies.

As the root user, run the following commands:

root# apt-get install subversion
root# apt-get install git
root# apt-get install scons
root# apt-get install libxml2-dev
root# apt-get install libglib2.0-dev
root# apt-get install libgtk2.0-dev
root# apt-get install libgtkglext1-dev
root# apt-get install libjpeg62-dev
root# apt-get install zip

If these steps succeeded without errors, you can proceed to Step B.

You may have gotten the following problem when trying to install these packages:

Media change: please insert the disc labeled
 'Debian GNU/Linux 5.0.2 _Lenny_ - Official i386 CD Binary-1 20090628-14:43'
in the drive '/cdrom/' and press enter

If so, then you should open the file /etc/apt/sources.list as root and edit it. Completely delete the line that is the bold text below:

# deb cdrom:[Debian GNU/Linux 5.0.2 _Lenny_ - Official i386 CD Binary-1 20090628-14:43]/ lenny main

deb cdrom:[Debian GNU/Linux 5.0.2 _Lenny_ - Official i386 CD Binary-1 20090628-14:43]/ lenny main

deb lenny main
deb-src lenny main

deb lenny/updates main
deb-src lenny/updates main

deb lenny/volatile main
deb-src lenny/volatile main

After removing that line, run the apt-get commands above again to install the extra packages.

If you have the proprietary NVIDIA driver installed using the "Debian package way", you may need to install one extra package to get GtkRadiant to compile. You can try compiling GtkRadiant without this extra package, but if it fails to compile you will need to return here and follow these instructions. (There will be a link taking you back here.) First, figure out which version of the NVIDIA drivers you have installed via Debian packages:

root# dpkg --get-selections | grep nvidia-glx

Then, install the corresponding -dev package. Execute only one of the commands below, depending on your version of nvidia-glx :

root# apt-get install nvidia-glx-dev
root# apt-get install nvidia-glx-legacy-96xx-dev
root# apt-get install nvidia-glx-legacy-173xx-dev

Step B: Compile GtkRadiant

All of the following steps should be executed as a normal user, not root.

Change directory to your home directory:

user@debian:~$ cd

Next, we will get the source code for GtkRadiant:

user@debian:~$ git clone ./GtkRadiant-src

Now the next step will download extra data needed to do mapping for specific games such as Urban Terror:

user@debian:~$ cd GtkRadiant-src/
user@debian:~/GtkRadiant-src$ scons target=setup

We are now ready to compile GtkRadiant! Execute the step below; this is the main build target to compile GtkRadiant:

user@debian:~/GtkRadiant-src$ scons target=radiant,q3map2 config=release

If you have the proprietary NVIDIA driver installed and you get the following error when executing the build target above:

/usr/bin/ld: cannot find -lGL
collect2: ld returned 1 exit status
scons: *** [build/release/radiant/radiant.bin] Error 1
scons: building terminated because of errors.

then you should install one of the nvidia-glx-dev* packages as mentioned above in Step A, then try to execute the main build target to compile GtkRadiant again.

If you get other errors, you may try asking for help in the GtkRadiant IRC channel, which is #radiant on QuakeNet (

Assuming the main compile target was successful, we can now relocate the install directory. While still in the ~/GtkRadiant-src directory, execute the following:

user@debian:~/GtkRadiant-src$ mv install/ ~/GtkRadiant

GtkRadiant is now installed in the GtkRadiant folder in your home directory. Now let's clean up the build directory:

user@debian:~/GtkRadiant-src$ cd
user@debian:~$ rm -rf GtkRadiant-src/

You can also clean up the install directory by removing SVN-related files (from the game packs) that are no longer needed. These files just take up extra space and serve no further purpose:

user@debian:~$ find GtkRadiant/ -type d -name '\.svn' -print0 | xargs -0 rm -rf

Congratulations, you now have GtkRadiant installed! Let's wait until you complete the next section before launching GtkRadiant for the first time.

GtkRadiant depends on having write access to the install folder (in our case ~/GtkRadiant). Therefore, you should probably leave it in your home directory instead of trying to install it on a read-only system level.

Section 2: Installing Urban Terror

Even if you don't plan on running Urban Terror from your mapping computer, you do need to install Urban Terror if you are going to make maps for Urban Terror.

In this HOW-TO we will install Urban Terror into ~/UrbanTerror .

The Urban Terror installation that GtkRadiant is going to use needs write access by the GtkRadiant program. It is therefore suggested that you install Urban Terror to a separate location just for GtkRadiant to use, even if you already have Urban Terror installed on your computer. If you already have Urban Terror installed somewhere, you can just copy the entire contents of the installation folder (usually UrbanTerror) to ~/UrbanTerror . Otherwise, download the file from one of the mirrors listed on the downloads page or from this torrent, and place that file in your home directory. Then,

user@debian:~$ unzip

Which will create the UrbanTerror folder when unzippped. Now the maintainers of Urban Terror made a small mistake when they created this .zip file. They forgot to make the ioUrbanTerror binary programs executable. So we're going to do that now:

user@debian:~$ cd UrbanTerror/
user@debian:~/UrbanTerror$ chmod +x ioUrbanTerror.* ioUrTded.*

Note that if you are running a very modern version of 64 bit Debian or Ubuntu, chances are high that the stock ioUrbanTerror binaries won't work on your system. You will need to find a more recent version of the ioquake3 client. A good choice for that would be mitsubishi's ioq3-urt (link dead?). I would advise choosing the "vanilla renderer version", not the "bumpy" version of ioq3-urt.

Section 3: Configuring GtkRadiant

We are now ready to launch GtkRadiant for the first time! As a normal user, type the following:

user@debian:~$ ~/GtkRadiant/radiant.bin

You should fill out the initial screen as follows, with the exception of replacing /home/user with your actual home directory.


After hitting "OK", you will come to a dialog like this one:


You can check the "Auto load selected game on startup" checkbox if you like. Hit "OK" again.

You should now have GtkRadiant on your desktop. Congratulations! Before we do anything with it, close the application and continue on to the next section of this HOW-TO.

Section 4: Separating Mapping from Playing in Urban Terror

A lot of novice mappers fail to realize the importance of separating their auto-downloaded maps from their mapping environment. When you play Urban Terror online, you will likely come across servers that have custom maps on them. When you connect to such a server, that custom map will be downloaded and placed into the folder ~/.q3a/q3ut4 . Third party maps sitting in this folder are very likely to interfere with the mapping process. Many maps made by novice mappers have plenty of missing textures and other issues because of the mapper's failure to separate the mapping environment from the gaming environment. In this section we go over a correct way of separating your gaming from your mapping.

Urban Terror, which is an ioquake3-based game, uses the .q3a directory structure in your home directory to store all of its persistent data, such as maps and configs. Likewise, GtkRadiant searches for maps and textures in this same directory. It is fairly tricky to convince GtkRadiant to use a folder other than .q3a for the map data, so instead of trying to modify the behavior of GtkRadiant, we will modify the behavior of the Urban Terror game that you play on public servers. We will tell Urban Terror to use the directory ~/.urt instead of ~/.q3a to save all of the configs and maps in.

Step A: Use ~/.urt for Pubbing

First, since we will be using ~/.urt for our non-mapping game data from now on, if you have already been playing Urban Terror on your computer, then you should rename your existing ~/.q3a folder to .urt like so:

user@debian:~$ cd
user@debian:~$ mv .q3a/ .urt

The above step assumes that the ~/.urt directory does not exist already. If that is not the case for some reason, you can simply move .q3a out of the way by renaming it to .q3a-bak or something.

Now that we have moved our existing game data folder to the new location, it is time to convince Urban Terror to use the new location for loading and saving game data. The trick to this is to use the +set fs_homepath ~/.urt arguments to ioUrbanTerror. It's best to write an Urban Terror startup script and place it in your ~/bin directory. Create a file ~/bin/urt like so:

user@debian:~$ mkdir -p ~/bin
user@debian:~$ touch ~/bin/urt
user@debian:~$ chmod +x ~/bin/urt

Put the following text into the file ~/bin/urt :


# Change the path of the binary to whatever you use to launch the game.
# This should be set to whatever you've been using to start Urban Terror
# in the past.  For example (2 examples):
# URBAN_TERROR_EXECUTABLE="/usr/local/games/UrbanTerror/ioUrbanTerror.i386"
# URBAN_TERROR_EXECUTABLE="/usr/local/games/UrbanTerror/ioUrbanTerror.x86_64"


"$URBAN_TERROR_EXECUTABLE" +set fs_homepath ~/.urt $*

You will need to modify the value of URBAN_TERROR_EXECUTABLE in the script as stated in the comment.

From now on you'll be using ~/bin/urt to launch Urban Terror when you play in public servers. Try it now like this:

user@debian:~$ ~/bin/urt

All of your binds, settings, and custom downloaded maps should still be present because you renamed the .q3a directory to .urt .

Please note that it is relatively simple to compile a special version of ioUrbanTerror which uses ~/.urt instead of ~/.q3a , avoiding the need for the ~/bin/urt script. However, that is beyond the scope of this HOW-TO.

Step B: Use ~/.q3a for Map Testing

We will use the plain vanilla ioUrbanTerror (without overriding fs_homepath) for purposes of testing maps that we create. Although not necessary, I suggest that you take a couple of minutes to write some scripts that will help you quickly launch your test maps, so that you don't have to remember what arguments you have to pass to ioUrbanTerror each time you want to test one of your new creations.

I would suggest the following scripts, starting with ~/bin/maptest-ffa :


# Change the path of the binary to whatever you use to launch the game.
# This can be the executable you specified in the script ~/bin/urt .
# Or, if you like, it can be the executable in your mapping Urban Terror
# installation (/home/user/UrbanTerror/ioUrbanTerror.i386 or
# /home/user/UrbanTerror/ioUrbanTerror.x86_64 in these examples).
# Just remember to "chmod +x" the executable so that you can actually
# execute it.

"$URBAN_TERROR_EXECUTABLE" +set sv_pure 0 +set g_gametype 0 +devmap $*

Make the script executable:

user@debian:~$ chmod +x ~/bin/maptest-ffa

You can then create new scripts for each gamemode if you like, for example a script ~/bin/maptest-ctf :



"$URBAN_TERROR_EXECUTABLE" +set sv_pure 0 +set g_gametype 7 +devmap $*

Once you create your first map, you would use the script(s) as follows:

user@debian:~$ ~/bin/maptest-ffa ut4_mymapname

Try the following now, just to make sure that it works. You should be able to /noclip and use the other cheats once Abbey is loaded:

user@debian:~$ ~/bin/maptest-ffa ut4_abbey

Note that this will not use the old configuration files from your pubbing Urban Terror folder (now ~/.urt). So, you will have to configure the map-testing Urban Terror and/or copy configs over from ~/.urt .

Since you will be accessing the ~/.q3a/q3ut4 directory frequently while you are mapping, I would suggest creating a symlink with a name that does not start with a dot. For example:

user@debian:~$ ln -s ~/.q3a/q3ut4/ ~/mapping

Now you can access all of your mapping files through ~/mapping .

Section 5: W00t! Creating Your First Map

In this section we will create, compile, and package (into a .pk3) a very simple map that consists of a single room, a sofa, one spawn point, and one light entity. In addition, we will write our own custom shader in order to create a surface which does no falling damage. Since a lot of people have questions about creating custom shaders, I decided to include a simple case in this HOW-TO.

Step A: Create a Simple Shader

I will not describe how shaders work or what you can do with a shader. I will limit this tutorial to simply creating one custom shader, and you will have to RTFM (Read Teh F*****g Manual) to figure out what more you can do with shaders. To find the shader manual online, do a Google search for "q3map2 shader manual".

Create the following directories if they do not already exist:

user@debian:~$ mkdir -p ~/.q3a/q3ut4/scripts
user@debian:~$ mkdir -p ~/.q3a/q3ut4/textures/tutorial

Now, put the following into a file named ~/.q3a/q3ut4/scripts/tutorial.shader :

    surfaceparm nodamage
        map $lightmap
        map textures/tutorial/tile.tga
        blendFunc filter

Next, we need the texture tile.tga that's specified in the shader above. In the long run, you will benefit from learning how to create your own texture images. GIMP is an excellent tool for creating textures, and it comes pre-installed on Debian. In the meantime, you should download this TGA image and save it as ~/.q3a/q3ut4/textures/tutorial/tile.tga . The shader you wrote above depends on this image and its relative location in your filesystem (textures/tutorial/tile.tga).

Step B: Become Aquainted With shaderlist.txt

If you have not already run GtkRadiant and configured it with Urban Terror (see Section 3), please do so now, and then close GtkRadiant and continue with these instructions.

We will be modifying the file ~/UrbanTerror/q3ut4/scripts/shaderlist.txt . You will see that it has many lines of shaders. The shaders listed here are shaders that come with Urban Terror. You may in fact choose to use some of these shaders. However, for simplicity, we will remove most of the lines of text from this file. That way, our GtkRadiant application will not be cluttered with shaders that we are not going to use in this tutorial. First, make a backup of the existing shaderlist.txt in case you want to revert back to it (or extract lines from it) at a later time:

user@debian:~$ cd ~/UrbanTerror/q3ut4/scripts/
user@debian:~/UrbanTerror/q3ut4/scripts$ cp shaderlist.txt shaderlist.txt.orig

Now, open shaderlist.txt in a text editor and remove every line except for "common", and add a line "tutorial" right after it. The file should consist of 2 lines now and should look like this:


NOTE: If you plan on using textures and shaders from Urban Terror, then don't delete any lines from shaderlist.txt , just append lines to the end of it. Personally, I delete all shaderlist lines that I do not use, and for my maps, I don't use any of the textures/shaders that come with Urban Terror; I create my own.

When you create a new shader file (a file ending in suffix ".shader" and residing in ~/.q3a/q3ut4/scripts), you should add the basename of that shader file to shaderlist.txt if you plan on using that shader, just as we have now done for the "tutorial" shader.

Step C: Load "common" Shader

We are now ready to open GtkRadiant again for purposes of creating our first map:

user@debian:~$ ~/GtkRadiant/radiant.bin

With GtkRadiant open, under the "Textures" menu, make sure that the checkbox next to "shaderlist.txt only" is checked. Now go to the "Textures" menu one more time, and select "common" from the very bottom. You should see some shaders loaded in the bottom right window. It should look like this:


A very important shader to use is caulk (the top row, third from left in screenshot above). Every non-visible face should be textured with caulk in order to improve performance of rendering in Urban Terror.

Step D: Make Hollow Box

Go over to the grid view in GtkRadiant (on the left). Press the Insert key on your keyboard a couple of times to zoom out (Delete, right below Insert, is to zoom in). If you need to scroll in the grid view, hold down the right mouse button and drag your mouse. Now we will draw a square in the grid view, from X,Y coordinates (-256,-256) to (256,256). To do this:

  1. Left click on the grid view at X,Y location (-256,-256).
  2. With the left mouse button depressed, drag the mouse on the grid view until you arrive at (256,256).

With the new brush still selected (outlined in red on the grid view), we will stretch it vertically until it is as high as it is wide and long (forming a perfect cube):

  1. In the grid view, Ctrl+Tab until you get to the X,Z or Y,Z view (looking at the new brush from the side, it will appear the be very thin).
  2. Left click somewhere above the brush in the grid view. Drag the mouse up until the top face of the brush reaches a Z value of 512.

Now you can Ctrl+Tab in the grid view a few times just to make sure that the new brush you created is square when viewed from every axis.

With the brush still selected (outlined in red in the grid view), press the caulk texture in the textures window (screenshot of texture window above). Simply clicking a texture icon while a brush (or brushes) is (are) selected will apply that texture to every face of the selected brush(es).

You can navigate in 3 dimensions in the 3D window. Right click in the 3D window, which is above the textures window. Now you can move the mouse to freelook around. Use the arrow keys to go forwards, backwards, and side to side. If your camera is currently inside the brush you created, the brush will not appear. You'll have to move outside the brush to see it. When you are finished using the 3D window, right click on that window again to regain control of your desktop mouse pointer.

With the brush still selected, press the "Hollow" button:


You should now unselect the selected brushes. Press Esc to unselect all brushes. There should now be 6 brushes (walls) in your world.

NOTE: Mapping experts tend not to use the "Hollow" feature. You get more control over brush creation if you create walls manually. However, I am introducing you to the "Hollow" feature in order to keep this tutorial as brief as possible.

Step E: Apply Tile Texture to Inside Walls

Go to the "Textures" top-level menu again, and this time choose "tutorial" at the very bottom of the menu. You should now see the black and white tile texture in the texture window.

We will now apply the custom tile texture we created to the inside of the box. Go to the 3D view, and navigate the camera to the inside of the cube.

Once you are inside the cube in the 3D view, what we are going to do is individually select each inside face, then apply the tile texture to each face. To select a face, hold down both Ctrl and Shift, and left-click on the face you want to select. Once a face is selected, you can apply the tile texture to it by clicking on the tile texture icon. You can actually select multiple faces by holding down Alt in addition to Ctrl and Shift, and left-clicking the faces you want to select.

To unselect the faces that are currently selected, press Esc.

Step F: Create a Light Entity

We will now create a simple light source. In the grid view, right click to bring up the entities menu. Select "light" (about halfway down the menu). You can set the light intensity to 1000 or so. You should drag the light source in each of the planes in the grid view (alternate axis by pressing Ctrl+Tab) until the light is approximately in the center of the cube.

You can press Esc to unselect the light.

Step G: Add a Model

We are going to add a model (.md3 file) to our map. In our case we will add a sofa to the center of the room. Models are a nice addition to any map.

To begin, download the archive which contains the sofa model resources. Credit for this model goes to BlackRayne Studios. Place this downloaded file in the ~/.q3a/q3ut4 directory and extract it there:

user@debian:~$ mv ~/.q3a/q3ut4/
user@debian:~$ cd ~/.q3a/q3ut4/
user@debian:~/.q3a/q3ut4$ unzip
user@debian:~/.q3a/q3ut4$ rm

You should now have 2 new files, ~/.q3a/q3ut4/models/mapobjects/br_prague2/br_couch.md3 and ~/.q3a/q3ut4/models/mapobjects/br_prague2/br_couch.jpg .

In GtkRadiant, right click on the grid view to bring up the entities menu and select "misc" -> "misc_model". A file selection dialog should come up in GtkRadiant; specify the file ~/.q3a/q3ut4/models/mapobjects/br_prague2/br_couch.md3 in that dialog. You should now see a model in your map. Move the model (by left-click dragging the model in the grid view) until it touches the floor and is somewhere near the middle of the room. Again, use Ctrl+Tab in the grid view to change the viewing axis. You can press Esc to unselect the model; to select the model again, hold Shift and left mouse click on the model either in the grid view or in the 3D view.

Note that models are nonsolid; this means that you can walk right through them in-game. We're not going to make the sofa model solid in this tutorial. If you wanted to make a model solid, you might try creating brushes out of common/clip that approximate the shape of the model. common/clip is the red tiled texture with "PLAYER CLIP" written on it when you load the common shader file. Note that common/clip will not stop bullets from flying through. There are different techniques for solidifying models, and some of the techniques can be tricky. For now, leave the sofa model as nonsolid.

More information pertaining to models can be found in Appendix E. I discuss several known bugs there.

Step H: Create a Spawn Point

We will now create a generic spawn point. If you are making a map for game modes such as TDM, TS, CTF, and Bomb, you will need to make additional, slightly different spawn points (info_ut_spawn). For this example, we will stick to generic FFA spawn points (info_player_deathmatch).

Right click in the grid view to bring up the entities menu and select "info" -> "info_player_deathmatch". You should drag this entity until it is comfortably inside the cube. Don't hesitate to place the spawn point rather high, because we won't lemming when we fall on the floor because of our custom nodamage shader.

Step I: Compile Your Map

Save your map by choosing "File" from the menu bar, then "Save". You can name the map "". It should be saved in the default location, which is ~/.q3a/q3ut4/maps .

We are now ready to trigger the compile process which creates a .bsp file out of the .map file. From the "Bsp" menu in the menu bar, select one of the "test" or "final" targets (there should be 2 "test" targets and 2 "final" targets by default).

Output messages from the compile process will go to the bottom console window like so:


Step J: Test Your Map

Remember the script ~/bin/maptest-ffa that we wrote earlier? We are going to use it now. At a terminal type:

user@debian:~$ ~/bin/maptest-ffa ut4_tutorial

You should be able to load up your new map, and it should look more or less like this:


Step K: Package Your Map

Now we are going to create a .pk3 file that can be uploaded to a server. In our example we are going to include the bare minimum number of files needed to correctly run this map on a server. In real maps, there are oftentimes many more files in a .pk3, such a levelshot, a minimap, an .arena file, and so on. We are omitting all those files for this test map. To get more ideas about what is included in a typical .pk3, you can unzip existing maps (.pk3 files) and see what's inside them. To package our map:

user@debian:~$ cd ~/.q3a/q3ut4/
user@debian:~/.q3a/q3ut4$ zip ~/ut4_tutorial.pk3 \
                                maps/ut4_tutorial.bsp \
                                scripts/tutorial.shader \
                                textures/tutorial/tile.tga \

Contratulations, you have just created your first map, which is the file ~/ut4_tutorial.pk3 . You can now upload this map to a public server to test it out for real. You can download my version of ut4_tutorial.pk3 and compare it to your version. I've included the .map file inside the .pk3 file for your reference.

ONE VERY IMPORTANT NOTE: Do not leave .pk3 files sitting in the ~/.q3a/q3ut4 directory. You will have all sorts of strange errors while testing new builds if you leave .pk3 files sitting there. You could spend hours debugging the problem.

Appendix A: GtkRadiant Controls Quick-Reference

Here are perhaps the most frequently used controls in GtkRadiant:

key(s) action context
Backspace delete selected brush(es) grid view, 3D view
left mouse button drag when no brush selected create brush grid view
Esc unselect selected items grid view, 3D view
Shift + left mouse click select brush grid view, 3D view
Ctrl + Alt + left mouse click select brushes in func_group grid view, 3D view
left mouse drag on selected brush translate brush grid view, 3D view
left mouse drag outside of selected brush resize brush grid view, 3D view
right mouse click start freelook, exit freelook 3D view
arrow keys navigate 3D view, behavior is different depending on whether or not you are in freelook mode 3D view
right mouse click entity menu grid view
N entity properties window for selected brush/entity grid view, 3D view
Ctrl + Tab change viewing axis grid view
E edge handles for selected brush grid view, 3D view
V vertex handles for selected brush grid view, 3D view
Ctrl + Shift + left mouse click select face 3D view
Ctrl + Shift + Alt + left mouse click select multiple faces 3D view
Insert and Delete zoom out and zoom in grid view
right mouse drag translate grid view grid view
middle mouse click/drag rotate 3D camera grid view
Ctrl + middle mouse click position 3D camera at specified click point grid view
left mouse click select texture, apply texture to selected brushes/faces texture window
Shift + left mouse click open shader file associated with texture texture window

Appendix B: Compile Scripts

Instead of always using the GtkRadiant "Bsp" menu to compile my maps, I tend to only use the "Bsp" menu when I am testing a map for leaks. When there is a leak in your map during the compile process when you use the "Bsp" menu, a nice user interface with a thick red line will come up in GtkRadiant which will help you easily track down the leak. However, if I know that the map has no leaks and will compile fine, I tend to use standalone scripts that run independently of GtkRadiant to compile my maps. This is because I get more control when running the compile as a script; for example, I can easily fine-tune the compile parameters by editing the script, or I can easily launch the compile process with a high nice value to not hog CPU resources in case I want to play Urban Terror while my map is compiling. I can also compile the map without having to have GtkRadiant open.

I will give you a sample script, then you can make your own similar scripts and call them whatever you like. Let's create a script called ~/bin/mapbuild which will compile a map with decent compile settings that are not too expensive but produce good-looking results.

user@debian:~$ touch ~/bin/mapbuild
user@debian:~$ chmod +x ~/bin/mapbuild

Now put the following text into this script:


set -e

if [ "$#" -ne 1 ]; then
  echo "Expected exactly one argument.  Example usage:" 2>&1
  echo "  `basename \"${0}\"`" 2>&1
  exit 1
"${Q3MAP2}" -v -threads 1 -game quake3 -fs_basepath "${URTDIR}" \
  -fs_game q3ut4 -meta -patchmeta -subdivisions 1 "${MAPNAME}"
"${Q3MAP2}" -v -threads 1 -game quake3 -fs_basepath "${URTDIR}" \
  -fs_game q3ut4 -vis -saveprt "${MAPNAME}"
"${Q3MAP2}" -v -threads 1 -game quake3 -fs_basepath "${URTDIR}" \
  -fs_game q3ut4 -light -nocollapse -fast -samples 3 -bounce 2 -patchshadows \

You can now try compiling your map by using this script:

user@debian:~$ cd ~/.q3a/q3ut4/maps/
user@debian:~/.q3a/q3ut4/maps$ ~/bin/mapbuild

The best resource for discovering and understanding all the q3map2 compile options is the Q3Map2 Wikibook. Once you understand q3map2 better, you will be able to write you own scripts optimized for your map.

Appendix C: The Entity Window Bug

When you first install GtkRadiant and you press N to bring up the entity window for a selected brush or entity, the entity window might look like this:


Well as it turns out all of the good stuff is missing in this window, because it's hidden. There is a little traction bar circled in red. You should drag that down to expose all of the useful information that is hidden. Your entity window should now look more like this:


Appendix D: Surface Sounds in Your Map

When you run your player across a map in-game, you may notice that the footstep sound is different in certain areas. Also, when you shoot at a surface, the bulletmark, sound, and impact characteristics (such as sparks, chunks of wood flying off, etc.) will be different depending on the surface. This section shows you how to create those surface properties.

Every drawn texture (or shader) in your map is assigned a surface type. By default it is "none". Other possible surface types include "titanium", "hardwood", "linoleum", and others. On Linux, the tool that is used to alter surface types is called bsp-redone. This tool, when executed on the command-line, takes your compiled .bsp file as an input argument along with a surface properties file, and writes to disk a new, updated .bsp file with those new surface properties.

To begin, download the source code for bsp-redone. Place this .zip file in your home directory. Then, as a normal user:

user@debian:~$ unzip
user@debian:~$ cd bsp-redone/
user@debian:~/bsp-redone$ make
user@debian:~/bsp-redone$ mv bsp-redone ~/bin/
user@debian:~/bsp-redone$ cd ../
user@debian:~$ rm -rf bsp-redone/

This is a command-line tool. To get an idea on how to use this tool, just execute it with no arguments:

user@debian:~$ ~/bin/bsp-redone

list textures       : /home/user/bin/bsp-redone -tl bsp_file
copy textures       : /home/user/bin/bsp-redone -tc bsp_file src_dir dest_dir
export surface file : /home/user/bin/bsp-redone -se bsp_file [surface_file]
import surface file : /home/user/bin/bsp-redone -si bsp_file surface_file
surface list        : /home/user/bin/bsp-redone -sl

We will now create titanium walls in our map, ut4_tutorial:

user@debian:~$ cd ~/.q3a/q3ut4/maps/
user@debian:~/.q3a/q3ut4/maps$ ~/bin/bsp-redone -se ut4_tutorial.bsp ut4_tutorial.surfaces

Now open the file ~/.q3a/q3ut4/maps/ut4_tutorial.surfaces which should have a line that looks like this:

textures/tutorial/tile = none

Change the "none" to "titanium" and save the file. (You can leave any other lines unmodified.) Now we have to bake this new surface type back into the .bsp:

user@debian:~/.q3a/q3ut4/maps$ ~/bin/bsp-redone -si ut4_tutorial.bsp ut4_tutorial.surfaces

That's it! You now have custom surface sounds baked into your map.

To figure out what all the different surface types are, execute the following command:

user@debian:~$ ~/bin/bsp-redone -sl

Appendix E: Models in Your Map

Basic information regarding adding a model to your map can be found in Step G of Section 5. This appendix contains some addional information pertaining to models.

When you acquire models from third parties, knowing where to place the associated .md3, .jpg, and .tga files can be a little bit tricky. The relative paths to images that the .md3 model uses are hardcoded in the .md3 file. To figure out where the model is going to load its images from, you can open the binary .md3 file in an editor such as emacs or vi (or a hex editor such as xxd) and look for strings that resemble image path names. That should give you a clue as to where to place the associated image files. The relative path of the .md3 file itself may also be embedded in the .md3 file. You should use those paths.

To complicate things further, some models rely on having shaders, not just textures. You will need to add the shader definitions to one of your shader files if that is the case. The model used in this tutorial does not rely on a shader; it uses a simple texture.

If you want to use models that are already part of Urban Terror, you can do one of two things. For purposes of this discussion, let's assume that you want to use the model models/trees/tree1/tree_bare.md3 that is part of Urban Terror 4.1 (this .md3 file resides inside of zpak000_assets.pk3).

Your first choice is to extract either the entire zpak000_assets.pk3 into your ~/.q3a/q3ut4 folder, or just the .md3 files that you plan to use. (I personally prefer not to extract the entire contents of zpak000_assets.pk3 into my mapping folder because it litters my directory structure with many files that I'm not going to use, confusing things a great deal.) For example, if you want to extract a single .md3 file from Urban Terror, you might do something like this:

user@debian:~$ cd ~/.q3a/q3ut4/
user@debian:~/.q3a/q3ut4$ ln -s ~/UrbanTerror/q3ut4/zpak000_assets.pk3 .
user@debian:~/.q3a/q3ut4$ unzip zpak000_assets.pk3 models/trees/tree1/tree_bare.md3
user@debian:~/.q3a/q3ut4$ rm zpak000_assets.pk3

The above command would give you the file ~/.q3a/q3ut4/models/trees/tree1/tree_bare.md3, which you could load using the file dialog that pops up when you create a misc_model in GtkRadiant.

The second way to use a model that comes standard with Urban Terror is a bit more tricky, but does not involve extracting any files at all. To begin, create a misc_model as you normally would, but when the file chooser dialog comes up, do not specify an .md3 file at all, but rather click the "Cancel" button. This will create an "empty" model entity. While this newly-created model entity is still selected, press N to bring up the entity window. Now you should modify or add a key "model" with the value "models/trees/tree1/tree_bare.md3". This will create the tree model in your map without having to extract the corresponding .md3 file from Urban Terror.

There is one caveat to creating model entities with the second method described above. When a model entity which has not yet been assinged a valid "model" key is unselected, there seems to be no easy way to select this entity again. In the worst case, to select a model entity, you can create a brush tightly surrounding the entity, and then while this new brush is still selected, from the "Selection" top-level menu choose "Select" -> "Select Inside".

There is one more bug related to models that is worth mentioning. Ideally, all resouces used by your maps contain path names that use only lowercase letters. However, sometimes, third-party models use resources that have capital letters in them. Let's say you have a model with this absolute path: ~/.q3a/q3ut4/models/mapobjects/GR_trees/nbsnow.md3. When you follow the procedure to create a misc_model in GtkRadiant, and when you use the "Open Model" dialog to specify the .md3 file that you want to open, well *surprise* *surprise* it sets the model entity's "model" key to have the value "models/mapobjects/gr_trees/nbsnow.md3" (lowercase). To get around this bug, either have paths to your .md3 files that do not contain uppercase letters, or modify the "model" key's value after you have created the model entity to have the correct capitalization. You really ought to avoid capital letters in any resource names if you can.

Appendix F: Nuking GtkRadiant and All Preferences

You may decide to nuke all of your GtkRadiant-related data for one reason or another. For example, if your preferences/settings get really goofy and you can't figure out how to make GtkRadiant work properly again, you may decide to nuke everything and start again from scratch with the installation of GtkRadiant.

Before you nuke anything, you should make sure that you have backups of any valuable data that is in the directories that you are about to remove. You should especially think twice before removing ~/.q3a .

Nuking will take place by executing some or all of the commands below:

user@debian:~$ rm -rf ~/.radiant/
user@debian:~$ rm -rf ~/.q3a/
user@debian:~$ rm -rf ~/UrbanTerror/
user@debian:~$ rm -rf ~/GtkRadiant/

You can probably remove ~/.radiant (or just the ~/.radiant/1.6.0 folder under it) without worrying too much about it. This folder stores your preferences in GtkRadiant.

Be very cautious before you delete ~/.q3a because all of your custom map files, shaders, and textures reside here. GtkRadiant does create its own files under this directory, most notably the file ~/.q3a/q3ut4/scripts/user0.proj . You may choose to only delete this project file.

GtkRadiant modifies some files in its installation folder (~/GtkRadiant in our case), so if you want to fully restore your working environment to a pristine state, you will delete this directory and compile GtkRadiant from scratch.

You should not be storing any important information in the Urban Terror install folder (in our case ~/UrbanTerror) except for shaderlist.txt . So you might want to back that file up. Any other files in this folder that don't belong to the Urban Terror installation were probably created by GtkRadiant. Therefore, you should be able to back up your shaderlist.txt and safely remove ~/UrbanTerror . Installing Urban Terror again by unzipping the file is really easy.