Tutorial: How to create -BSP files using GtkRadiant

Original version by Till Hoffmann

Note: This was written for Ogre 1.0.7, and is known to compile against it. If this is not the current version of Ogre, please pester torquedev at gmx dot net to fix it. Any problems you encounter while working with this tutorial should be posted to the Help Forum.


This tutorial assumes you have knowledge of C++ programming and are able to setup and compile an Ogre application (if you have trouble setting up your application, see this guide for specific compiler setups). NO knowledge of Ogre is assumed for this tutorial outside of what is contained in the setup guide.


In this tutorial I will be introducing you to the most popular editing tool for Quake3 -BSP files: GtkRadiant
We will use the GtkRadiant to create a simple map. Afterwards we will use the tool q3map2 by ydnar to compile the created *.map file. q3map2 creates -BSP files from your *.map files. Lastly we will write a small program to display the -BSP scene.

As you go through the tutorial you should be slowly adding code to your own project and watching the results as we build it. There is no substitute for actual programming to get familiar with these concepts! Resist the urge to simply read along.

Downloading the needed files

  • Download a demo of Quake III here. If you already have a copy of Quake III you don't have to download the demo.

  • Download the GtkRadiant here. I recommend using a stable version but lastly this is your own decision. You have to download the version for Quake III.

  • Get the latest version of q3map2. Unfortunately the website (http://www.shaderlab.com/) is currently down, but the GtkRadiant binaries usually contain a copy of q3map2.

  • Download q3map2build which is a GUI interface for q3map2 here.

Installing the files

  • Install the Quake III demo to any directory.
  • Install the GtkRadiant to any directory but pay attention to choose the correct directory for Quake III during the installation process.
  • Extract q3map2build to any directory.

The main installation process is done but there will be problems because we are using a demo of Quake III and the GtkRadiant was designed for the usual version. If you are using your own copy of Quake III skip the following step.

  • The installation executable of the GtkRadiant created a folder called 'baseq3' in your installation directory of Quake III. The data needed to play the game is in the folder called 'demoq3'. Copy all files from 'demoq3' to 'baseq3'.

Setting up q3map2build and GtkRadiant

Since there are thousands of tutorials on the internet how to set up these tools I won't describe it another time. Here are some links:

Simply search the web for tutorials.

Using GtkRadiant and q3map2

Start GtkRadiant and open the file 'q3dm1sample.map'. After a short while you should see a small level of Quake III. Get some tutorials to find out how to use this mighty tool to create your own maps.

The more interesting part is to compile the MAP file to a -BSP file. Use this tutorial to set up q3map2build. Compile the map called 'q3dm1sample.map'.

Using Ogre

Now we have a map compiled to be used by our rendering engine. We will write a small programm which loads the file 'q3dm1sample.bsp' which you created using q3map2build

Create a new project and add a source file containing the following code:

#include "ExampleApplication.h"
 class TutorialApplication : public ExampleApplication
     void chooseSceneManager(void)
     void createScene(void)
 #define WIN32_LEAN_AND_MEAN
 #include "windows.h"
 int main(int argc, char **argv)
     // Create application object
     TutorialApplication app;
     try {
     } catch( Exception& e ) {
         MessageBox( NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
         fprintf(stderr, "An exception has occured: %s\n",
     return 0;

We have to specify that we want to use a BspSceneManager. Add the following code to chooseSceneManager(void):

mSceneMgr = mRoot->createSceneManager("BspSceneManager");
Now we have to load the -BSP file into Ogre. Add the following code to createScene(void):

Compile and run your program. You will get an error, that the file 'q3dm1sample.bsp' was not found.

Editing resources.cfg

You have to edit the file 'resources.cfg' add the following line at the end of the file:


Furthermore you have to zip the 'maps' folder contained in baseq3. Now add another line to 'resources.cfg':


Now try to run your program. Don't get confused. It takes a while to load all the resources.

Adjusting the axis

You might have noticed that the camera is not moving correctly in the scene. This is because the Y and Z axis are swapped in Quake III and therefore in the -BSP file. Add the following code to createScene(void):

mCamera->pitch(Degree(90)); // Quake uses X/Y horizon, Z up
                // Don't yaw along variable axis, causes leaning
                mCamera->setFixedYawAxis(true, Vector3::UNIT_Z);