QBSP LIGHT VIS

How are maps made to work in Quake? What does the big picture look like? Here's some answers for you.

Quake maps are stored in .bsp files. These files contain all of the map's structure information, the map's entity locations, and the map's textures. The textures in a .bsp can make the files very large. When Quake runs a map, it gets everything it needs for the map from the .bsp file. In fact, pak0.pak and pak1.pak (the main source files for all of Quake including all the maps) contain many copies of the same textures because they are duplicated over and over in the pak file for each map.

So how does a map get built? There are three utilities that are used to process maps. They are QBSP, LIGHT, and VIS. John Carmack wrote all of them and has released the source code to the public domain. There are several versions of these utilities floating around. QBSP does the basic conversion from .map file to .bsp file. LIGHT and VIS modify the .bsp file after that. Here is a detailed description of what each one does and how to use them:

QBSP

QBSP is used to convert .map files into .bsp files. QBSP also does leak checking (I'll go into this more when we cover sealing maps) and removes non-visible brush faces on maps that are sealed. QBSP outputs a file that has the same name as the source .map file with a .bsp extension. If the map is sealed, it will generate a .prt file which is used by VIS. If the map is not sealed, then it will generate a .pts file which you can use in Quake to help locate leaks.

To use QBSP, you type QBSP mapname where mapname is the name of a .map file in the same directory as QBSP. All .map files reference a texture wad. This texture wad must also be available or QBSP will not be able to build the .bsp file.

Options for QBSP are:

-nojunc: I don't know what this is for. I've never used it.

-nofill: Another one I haven't used, I presume it prevenst QBSP from performing filling.

-threads: Number of threads to use while processing a .map file.

-draw: I don't know what this is for. I've never used it.

-onlyents: Quite possibly the most useful option of them all. You can build a map with QBSP, LIGHT and VIS and then move entities around with this option. QBSP will update the entity information from the .map file but will not otherwise modify the .bsp file. When building maps, this is the best because you don't have to rebuild the map everytime you want to tweak the position of a monster or weapon. QBSP with the -onlyents option will typically run in a second or two.

-verbose: Controls the amount of information that QBSP gives you while processing. I'm not sure if you get more or less with this option. You get a lot of info without it, so I've never used it.

-proj (project path): I don't know what this is for. I've never used it.

Once QBSP has built the BSP for the map, Quake displays the visible surfaces much the same way that Doom does. There is one major difference however, and that is Quake's lighting effects. Quake has two types of lighting: Static and Dynamic. Static lighting is added to the map before it is played by LIGHT, dynamic lighting comes from elements in the game and is generated while the map is in play. Static lighting casts shadows, dynamic lighting does not. Static lights in Quake are generated by placing light entities inside the map. Each surface in Quake has a light map. This map tells Quake how bright to draw each pixel of the texture while displaying it. This allows for both very subtle and very dramatic lighting and is responsible for the huge difference in realism between Doom and Quake. Explosions, rockets, and gunfire all cast dynamic light in Quake.

Static light in Quake is not strictly static. You can have static lights which are switched on and off, which flicker, and which fade or strobe. These are all non-static effects which are set up by LIGHT depending on what you ask for in your map. These effects will all cast shadows correctly.

The number of light entities that you place in your map only impacts LIGHT's execution speed. Once LIGHT is done, the map will play at the same speed in Quake as it would if it had no lights. You don't ever need to skimp on light sources for fear of slowing the map down. There are other things that can slow down a Quake map, but static lights is not one of them.

To use LIGHT, you type LIGHT mapname where mapname is the name of a .bsp file in the same directory as LIGHT.

Options for LIGHT are:

-threads: Number of threads to use while processing a .map file.

-extra: This causes LIGHT to completely smooth the lighting in the map. You do not need to do this while developing the map, but should do it before publishing the map. Using the -extra option makes LIGHT take 4 times as long to process the map. You may also find some times when you want to do a "LIGHT -extra" on a part of your map if you are casting intricate shadows and you want to see exactly how they will look in the final version. LIGHT without the -extra option will create blocky shadows and will not always show you the fine details in your shadows.

VIS will only run on a sealed map. It looks for the .prt file that was generated by QBSP. If it finds it, it will optimize the map for play in Quake. A large map that has not been VISed will play slowly and the models in the game (doors, lifts, etc) will vanish sometimes. This is because Quake is trying to draw everything that is in front of you even if you cannot possibly see it. VIS figures out which surfaces are visible from every point inside a map and builds a surface list which Quake uses to draw only those surfaces which are in sight. A map which is designed correctly can be quite large and play very quickly as long as only a limited number of surfaces are visible from any point in the map.

Needless to say, it is very important to VIS your maps. There are several levels of VIS which you can use. The -fast VIS is the best one to use while developing the map. It does not optimize the map enough to really play, but it does clean it up enough that the models will (usually) stop disappearing so that you can see them. It also runs very fast compared to a full VIS. A full VIS which takes hours can run in 15-20 seconds with the -fast option turned. Hoever, as Ty says: "You mileage may vary".

To use VIS, you type VIS mapname where mapname is the name of a .bsp file in the same directory as VIS. The .prt file must have already been generated by QBSP or VIS will stop without processing the map.

Options for LIGHT are:

-threads: Number of threads to use while processing a .map file.

-level 0-4: How optimized do you want your map? 0 is poorly optimized, 4 is completely optimized.

-fast: Fast VIS. This is for development only, and is a very fast way to get your map into a playable state so you can look at it while working on it. Use this a lot.

-v: Verbose processing. Lets you see what VIS is working on. Mostly useful for day-long VIS sessions where you want to make sure that VIS has not locked up on you.

When making Quake maps, I use -fast VIS for everything until I'm ready to place monsters, then I "VIS -level 4" the map and use "QBSP -onlyents" from there on to play around with entities. This way I don't have to wait for VIS to run every time I want to see the map in Quake, but I can have a completely optimized map when I'm doing monster and entity placement.

I never use VIS levels 0 thru 3.

When viewing Quake maps, build the map as fast as possible. This generally means QBSP, and LIGHT without -extra. No VIS. In many cases, you will be working on part of your map rather than the whole thing, and a VIS will not be possible. This is how you should operate since it makes the entire building process take less time. Your only goal is to see the part of the map you're working on so that you can get back into the editor and continue working. If you export the entire map every time you look at it, you will spend most of your time waiting for QBSP and LIGHT to run.

Here are the batch files which I use to run the Quake utilities. Each batch file runs a different combination of utilities depending on what you want. All of these batch files assume you are working in a subdirectory off of \Quake and copy the .bsp and .pts files into the \id1\maps directory for play in Quake after processing. These batch files are included with Thred:

    @cls
    @qbsp %1
    @copy %1.bsp ..\id1\maps\*.bsp
    @copy %1.pts ..\id1\maps\*.pts

    @cls
    @qbsp %1
    @light %1
    @copy %1.bsp ..\id1\maps\*.bsp
    @copy %1.pts ..\id1\maps\*.pts

    @cls
    @qbsp %1
    @light %1
    @vis -fast %1
    @copy %1.bsp ..\id1\maps\%1.bsp
    @copy %1.pts ..\id1\maps\%1.pts

    @cls
    @qbsp -onlyents %1
    @copy %1.bsp ..\id1\maps\%1.bsp
    @copy %1.pts ..\id1\maps\%1.pts

    @cls
    @qbsp %1
    @light -extra %1
    @copy %1.bsp ..\id1\maps\%1.bsp
    @copy %1.pts ..\id1\maps\%1.pts

    @cls
    @qbsp %1
    @light -extra %1
    @vis -fast %1
    @copy %1.bsp ..\id1\maps\%1.bsp
    @copy %1.pts ..\id1\maps\%1.pts

    @cls
    @qbsp %1
    @light -extra %1
    @vis -level 4 %1
    @copy %1.bsp ..\id1\maps\%1.bsp