This is a perennial question on the forums; I’ve started mapping and I use Radiant, and the build menu isn’t working! I can’t compile my map! How do you compile a map, after all?
Here is the short version:
You need to download “the map compilers” aka “the tools” to compile your map. I suggest these:
The tools were originally released by id software, but many people added improved functionality to them over the years; Greg Lewis, Tyrann, AguirRe, to name but a few. Bengt’s version is the culmination of that process and is the most suggested one.
The tools are three small command line programs; under Windows you would run them in a DOS prompt, while under Linux you can use Wine to run them from a terminal.
Running the tools
While you’re in the editor, please save your map. I recommend always saving .map files to the same location because that allows you to automate the process later. Note where the .map file is saved to.
For a start, you can put the tools into that same folder where your .map files are; it simplifies things in the beginning because you don’t have to type any paths.
You must then run the tools successively in this order (let’s assume your map file is called “mymap.map”):
1. QBSP.exe mymap.MAP (this outputs a .bsp file containing e.g. collision hulls and textures)
2. VIS.exe mymap.BSP (this calculates visibility information and writes it into the .bsp)
3. LIGHT.exe mymap.BSP (this creates the lightmaps and also writes them into the .bsp)
You may run Light before Vis, as well, it doesn’t matter. But QBSP has to be run first!
It is important to run QBSP on the .map file, but Vis and Light on the .bsp file. I can’t remember if the tools are smart enough to automatically do this right, so make sure of it by specifying the suffix. If QBSP doesn’t output a .bsp file, please see “Common problems” below.
Compilation is complete if all three tools have run on the correct file without major errors.
Running the map
The resulting “vised and lit” .bsp file is then copied to the Quake/id1/maps folder. If that folder doesn’t exist, you may create it. The custom map is then run from the Quake console (usually opened by pressing ^or ~ or from the main menu) by typing “map mymap” and pressing Enter. The .bsp suffix may be omitted. All Quake maps can be started like this.
You will notice there are different QBSP compilers, different versions of Vis, and different versions of Light available in different places on the Internet. It fundamentally doesn’t matter which ones you use, they should all do the same thing. I recommend you use TxQBSP combined with the Vis and Light tools from Bengt’s page if you’re only starting out.
If you would like to use coloured lighting for your map, there is a modified Light tool by MH that does this (it writes a .lit file that needs to go alongside the .bsp file in the maps folder). Most Quake engines now support this method. Read below for an explanation of how it works.
There is also a version of the Vis program (wvis) that uses multithreading to speed up the vising process. This can be extremely helpful for very large maps. Multithreading was already present in id’s version of the tools but for some reason not enabled. Willem first enabled the threading and Tuna fixed it later. For first maps, the standard Vis will be enough.
Command line switches
If you use func_group in Radiant to selectively hide/unhide parts of your map, you must use the -group switch on the TxQBSP command line for the compiler to recognize them.
The most common switch is probably -fast added to Vis. This will run only basic vis calculations and thus save a lot of time (“fastvis“). Remove this switch to do a “fullvis”. You should always fullvis your map before releasing it.
Light has a number of switches such as -extra that affect the quality of the lighting. I very much recommend to read the Light tool’s documentation if you’re getting really into mapping.
QBSP has a couple switches, depending on the version you use. One of those is the switch for transparent water; this isn’t needed with all variants, but if it’s needed it’s probably -transwater.
Front-ends for the Tools
Over the years, people created batch files (or bash scripts under Linux) to automate the compile process, and even graphical frontends. I suggest to learn the command line tools first in order to fully understand what they do.
But afterwards, you might find the graphical compiler frontend by Necros useful.
Here is a simple Bash script I use for compiling maps (Linux only). If you want to try it, save it as a plaintext file to a location in your $PATH; for example /usr/local/bin. Let’s assume you save it under the name “buildmap.sh”. Then make it executable by “chmod +x buildmap.sh” (as root or using sudo). As you can see, this does nothing dangerous; it simply runs the map compilers and copies the result to the maps directory. This script needs Wine (the Windows not-emulator) installed as well as the tools.
#!/bin/sh cd ~/quake/tools/quest wine ~/quake/tools/txqbsp/Txqbsp.exe $1.map wine ~/quake/tools/WVis.exe -fast $1.bsp wine ~/quake/tools/bengtlight/Light.exe -threads 2 -extra $1.bsp # removes skip surfaces #~/quake/tools/newskip/newskip $1.bsp cp $1.bsp ~/quake/id1/maps/ cp $1.map ~/quake/id1/maps/ cp $1.pts ~/quake/id1/maps/ cp $1.lit ~/quake/id1/maps/
Where ~/quake/tools/quest is the location of all my map files; yours may be different. You will have to tweak the paths in this script to match the paths you are using: the path to your map files, the paths to the tools, and the path to your Quake/id1/maps directory.
The “newskip” tool is a program that removes any surface that has a texture named “skip”. This is something pretty specialized; if you ever need it, you can run it right after the other tools.
The “$1″ is shorthand for “the first argument this script was run with”. Consequently, to compile mymap.map, the script needs to be run as follows:
user@machine $ buildmap mymap
Any line starting with a # is a comment and does not get executed.
In case you’re wondering what all those files are at the end, a .lit file is created in the case of coloured lighting; a .pts file (“pointfile”) is created only in case of a leak and is helpful for fixing such leaks. More on that later. You want any such files stored alongside the .bsp file.
If someone donates a DOS / Windows batch file that does the same as the Linux one, I will include it here.
A batch file (.bat) also just runs several programs in succession, just like the shell script, so you might be able to write one yourself following these guidelines.
What you want it to do is run TxQBSP, Vis and Light in succession.
Radiant build menu
The default build menu in (Net)Radiant does not work with Quake 1 because Radiant assumes that most users are mapping for Quake 3-based games. The default build menu wants to run the Quake 3 compiler, which is why it fails when trying to build a Quake 1 map.
It is possible to customize the build menu; an example follows beneath. Please note that you do not need the build menu to compile your maps; I myself use a shell script and I’m happy with that even though I compile maps very often. But there are those of us who like everything lined up neatly, so here goes:
Customizing the Radiant build menu
based on work by Mad Gypsy
The build menu is an XML file located in the q1.game folder under your Radiant directory called default_build_menu.xml. Under Linux most editors will be able to handle XML, while Windows users should use something like notepad++ to edit it.
Here is a minimal example file based on the one Mad Gypsy showed to me. This uses a Windows .bat file (run.bat). Linux users could probably shove a shell script in there instead to run their engine.
<?xml version="1.0"?> <project version="2.0"> <!-- engine/mod/QC config vars --> <var name="Engine"> "darkplaces.exe" </var> <var name="ModFolder"> "QuakeMod" </var> <!-- relies on above config vars --> <var name="Run"> "[EnginePath]/run.bat" </var> <!-- bsp1 compilers --> <var name="bsp"> "[RadiantPath]/compilers/map1/txqbsp.exe" </var> <var name="vis"> "[RadiantPath]/compilers/map1/wvis.exe" </var> <var name="light"> "[RadiantPath]/compilers/map1/light.exe" </var> <!-- newskip tool --> <var name="skip"> "[RadiantPath]/newskip.exe" </var> <build name="Quick"> <command>[bsp] "[MapFile]"</command> <command>[vis] -fast "[MapFile]"</command> <command>[light] -extra "[MapFile]"</command> </build> <build name="Full"> <command>[bsp] "[MapFile]"</command> <command>[vis] "[MapFile]"</command> <command>[light] -extra"[MapFile]"</command> </build> <build name="Run Map"> <command>[Run] [Engine] [ModFolder] "[MapFile]"</command> </build> </project>
I hope this is understandable even to beginners; you need to tweak the paths etc. to what they look like on your machine. If XML is all alien to you, or you just dislike XML for configuration files, or if you find the script/batch method easier, or if you like Necros’ compiler GUI, then I suggest using what you’re most comfortable with.
In the upper part, the paths etc. are defined as variables (tokenized). Those tokens are then later used in the commands. Stuff between <build> and </build> constitutes a build menu entry. [MapFile] and [RadiantPath] are internal tokens that don’t need to be defined.
Here’s the run.bat Mad Gypsy sent me (to put in the Quake folder):
cd /d %~dp0 %1 -game %2 +map %~n3
That, of course, is all alien to me. Linux users should substitute that with a bash script.
Mad Gypsy has the complete low down on the build menu here.
Here’s a list of things that can go wrong and how to fix those problems. Please tell me if you want anything added/answered here and I’ll add it.
The most likely cause of this (besides a typo on the command line) is a leak.
Quake 1 maps need to be hermetically sealed against the surrounding “void”. Think of it like a spaceship! If you have a tiny hole somewhere in your map’s outer hull, then there is a connection to the void and your compile will go wrong. This is called a leak.
Some compilers will immediately abort upon detecting a leak and not even write a .bsp file. TxQBSP will give an error message, create a pointfile, and continue building a simplified version of the BSP. This is what the error looks like:
—— FillOutside ——
WARNING: Reached occupant at (-1088 576 -191), hint_sentry
Simplifying … Leak file written to broodtest_v1.pts
Why is this bad? It’s quite simple really, it can have horrible effects on the performance of the map. The Vis tool can not work on a leaking map. If it even loads in the engine, it might run slow as molasses or have visual artifacts. You need to fix leaks if you have them. That’s what the .pts file is for.
If you do have a leak, load the map in the engine; then, in the console, type “pointfile” and click Enter. You should get something like this:
On one end of the dotted line is the entity mentioned in the error message (“occupant reached”). On the other end (where the line passes through the geometry) is the leak! You can type “noclip” in the console to freely fly around your map and get a better view of the leak. Take a good look at that spot in the map editor. In my case, I simply didn’t fully close the blue textured box around my map (if you’re a beginner, please try and DO NOT box your map – it’s a case of knowing the rules before breaking them; please seal the individual rooms and corridors of your maps properly instead).
If there is no visible hole and the line goes straight through a wall, try to rebuild and if necessary simplify the geometry surrounding that spot and snap everything to the grid (Ctrl-G in Radiant). In difficult cases, read this.
If the engine can’t find the pointfile, you didn’t copy the .pts file alongside your .bsp file.
Rule #1: Always snap everything to the grid, or you might get microscopic leaks that are hard to detect.
You get a compiler message like this:
WARNING: No valid wadfiles in worldmodel
and your map looks like this when loaded into the engine:
This means you didn’t specify the correct wad path in the map’s worldspawn.
In Radiant, select a normal wall brush and press N. You will see this:
The worldspawn entity needs to have a key named “wad” that points to the location of the texture .wad file the map is using. In my case, I made a typo; it should have been dev.wad instead of devv.wad. Because of that, the compiler complained. Make sure you have this wad path in your map’s worldspawn entity. (Radiant expects all texture wads in Quake/id1 anyway, but this wad path is needed by the compiler.)
ERROR: Didn’t split the polygon near…
You rescaled brushes with texture lock engaged; or you simply have a face where the texture is scaled too small. It tells you roughly where that face is; find it and reset the texture alignment (press S in Radiant) to “Axial”, or set the horizontal/vertical stretch to 1 or something bigger.
Vis cannot operate on a map that has a leak. This would be the most likely cause. The result is bad performance at the least.
Other warning or error
Please read Bengt Jardrup’s Q1 Tooltips document; it lists compiler messages and their causes.
My map is too big!
The default size limit for a Quake 1 map is 4096 units in each direction (starting at 0 0 0). This means 8192×8192 units maximum. If your map is bigger than that, you will get very strange visual glitches and you’ll hit an invisible wall while running around your map.
The only way around this is to use a specific engine that removes the protocol limit that is responsible for this. Such engines are the RMQ engine, FTEQW (set bigcoords 1 in the console) and probably Darkplaces. Vanilla Quake engines will fail at that point.
My map breaks the vertex/clipnodes/marksurfaces/whatever limit!
These are hard limits in the Quake 1 BSP format. Many engines will print warnings when you cross the “soft version” of these limits (defined in the engine) but will not fail until you reach the hard limit (defined in the BSP format itself). The only way around this is to use a different BSP format; this also means different compilers. Your choices include BSP2 and q3bsp.
HOWTO coloured lighting
To have coloured lights in your map, you need to a) use MH’s BengtLightColoured or a similar Light tool, and b) add colour values to the light entities in your map.
Select a Light entity (or torch etc) and press N in Radiant to bring up the entity window. Add a “_color” key (American spelling!) with a value of “R G B” (red green blue) where each is a number between 0 (minimal amount of that colour) and 1 (maximum of that colour).
“_color” “1 1 1″ means white because all three channels (RGB, right) are set to maximum. Experiment with these values; a nice orange for torches etc. would be “1 0.6 0.3″. Radiant will display the colour on the light entity itself.
The Light tool will generate a .lit file that needs to be copied to the same place as your .bsp file.
Some light tools, including the Bengt Jardrup one, MH’s modified one, and hmap2, allow you to have every sky surface cast “sunlight” automatically. This is a good way to light outdoor areas and rooms that are open to the sky.
This is how you use sunlight in your map with Bengt’s (and MH’s) Light tools:
Select a normal wall brush and press N in Radiant to bring up the entity window. You should see the worldspawn entity (same thing as setting the wad path earlier).
Enter a new key called “_sunlight” (with the leading underscore) and give it a value like any other light. You can start with 250 and lower it according to the sky and the setting of your map. This will make all sky surfaces cast light (or rather, shadows) of the specified value.
It is possible to add a little ambient effect that will roughly simulate radiosity in neighbouring areas. Create a new key in worldspawn (by now you should know how to do that) called “_sunlight2″ or “_sunlight3″ (the latter creates softer shadows). Give this a lower value than the first sun, perhaps half of your sunlight value. Experiment here.
After saving and compiling your map, your sky should now cast sunlight.
The default sunlight will be cast straight downwards; this is a little unrealistic because the sunlight’s angle really depends on the time of day, the time of the year and the geographical location. Fortunately Bengt’s tool allows you to specify this angle! If you are using a sky texture or a skybox that has an actual sun on it, make sure this angle matches the location of your sun. You don’t want your sun on one side of the sky and the shadows coming from the other.
Create a worldspawn key called “_sun_mangle” (mangle, not angle) with a value of “yaw pitch”. This might sound a little alien at first, but “yaw” means the horizontal direction of the sun in your map. Imagine this like the degrees of a compass: 0 would be North, 180 would be South, 90 would be East and 270 would be West. You’ll have to experiment with this angle because I don’t remember what the Light tool thinks is North. Just know that the circle has 360 degrees and experiment with the value until it looks right.
“pitch” means the height of the sun in the sky; -90 (minus 90) is straight up, 90 is straight down, 0 is the horizon. I recommend setting “pitch” to something like -75 (minus 75) and going from there. Again, experiment until it is right. If your sky has an actual sun, set yaw and pitch so the direction of the shadows matches up with your sun.
Example: “_sun_mangle” “270 -60″ means the sun is in the West and 60 degrees above the horizon. It usually looks best if the yaw value is *not* a main compass direction, because a lot of your brushwork is at those angles. To get the prettiest sunshadows, choose a slightly in-between yaw such as 130 or 220 and a medium pitch between -30 and -75.
Lit with sunlight only: _sunlight 250, _sunlight3 125, _sun_mangle 340 -55. Light tool ran with -soft and -extra4.
Please comment with any questions you might have or any additions you would like to see.
Copyright (c) J. Nicolaisen except where noted otherwise.