VBSP, VVIS and VRAD Explained: The Three Compile Steps

Compiling turns your VMF into a playable BSP in three steps: VBSP builds the geometry and checks for leaks, VVIS calculates what is visible from where, and VRAD calculates the lighting. VVIS and VRAD take most of the time. For tests you use fast settings, for release a full compile.

Overview: who does what

The three programs vbsp.exe, vvis.exe and vrad.exe are in the game's bin folder. Hammer runs them one after another when you press F9 and copies the finished BSP into the maps folder. Everything the programs print also ends up in a log file next to your VMF.

VBSP: geometry and leaks

VBSP converts your brushes into faces, removes faces that lie outside the map and divides the interior into visleafs. It also writes entities, static props, overlays and displacements into the BSP.

While doing so, VBSP checks whether the map is sealed. It floods the space starting from the entities and reports a leak as soon as it reaches the empty space outside. The log then shows **** leaked ****, and VBSP writes a pointfile that you can display in Hammer via Map > Load Pointfile as a line leading to the leak. No portal file is created in that case. The consequences: VVIS cannot work, the engine always draws the whole map, and the lighting is only calculated incompletely. How to find the leak is shown in Fix a map leak error.

The parameter -onlyents is useful for tests. It only updates the entities in an already compiled BSP without rebuilding the geometry. That saves time when you have only changed logic or entity settings. Brushes, including those of brush entities, stay as they were. In our test with GMod's VBSP, static props were updated as well, overlays were not.

VVIS: visibility

VVIS reads the portals between the visleafs and calculates for every area which other areas could be visible from it. The engine later uses this result to decide what it has to draw at all.

You can recognise two phases in the log: BasePortalVis is a rough pre-calculation, PortalFlow the exact and usually much longer one. Before that, the log states the number of portals. It determines the duration more than anything else. Many small world brushes and large open spaces create many portals.

• With -fast, VVIS skips the exact calculation. The compile is quick, but the engine draws more than necessary in game. That is unsuitable for a release, and FPS measurements are worthless with it.
• If VVIS takes too long, turn details into func_detail and simplify the world geometry. For large open areas there is func_viscluster. Details are in VVIS taking forever.

VRAD: lighting

VRAD calculates the direct light for every face, then lets it bounce off surfaces several times and stores the result as lightmaps. On top of that come lighting data for static props and for moving objects.

The most important parameters:

• -fast: quick, visibly coarser calculation for tests.
• -final: more accurate calculation for release, considerably slower.
• -ldr, -hdr, -both: defines which brightness range is calculated. With -both the calculation runs twice.
• -StaticPropLighting, -StaticPropPolys, -textureshadows: better lighting and more accurate shadows for static props.

The time depends on the size of the map, the number of lights and the lightmap scale. Small lightmap scale values on large faces are a common reason for very long runs. In the log you first see the direct lighting (BuildFacelights), then the individual bounces and finally a table showing how full the data sections of the BSP are. Everything about lighting is covered in the Source Engine lighting guide.

Settings for tests and release

In the normal "Run Map" dialog you choose between "No", "Normal" and "Fast" for VIS. RAD has the same three levels in Hammer++, and the bundled Hammer adds "Faster" and "Final". For BSP, the third option is "Only entities" instead of a fast mode. "Expert" takes you to ready-made profiles and lets you edit the parameters individually.

After the release compile, two more tasks follow that are not part of the three programs: building cubemaps in game and packing custom content into the BSP. How that works is described in Pack custom content into a BSP.

When the compile fails

Read the log from top to bottom and look for the first error. Later messages are often just consequences of it. A leak in VBSP, for example, means that VVIS cannot find the portal file. If you only read the last message, you end up looking in the wrong place.

You can also paste the log into the Map Scanner. It detects root causes, follow-up errors and matching fixes in VBSP, VVIS and VRAD logs.

FAQ

Why does VVIS take so long?

The duration depends on the number of portals, and that rises with every world brush that cuts up the space. Turn details into func_detail and keep the sealing geometry simple. Large open spaces are generally more expensive than winding interiors.

Can I skip VVIS or VRAD?

For tests, yes. Without VVIS the engine always draws the whole map, without VRAD the map is evenly bright and without shadows. A published map needs both steps in full.

What does "leaked" mean in the log?

The interior of the map is not completely enclosed by world brushes, or an entity lies outside. VBSP then creates no portal file, and the following steps do not deliver a usable result. Fix the leak before investigating other errors.

Do I have to recompile everything after every change?

After changes to brushes, yes, because geometry, visibility and lighting depend on each other. If you have only changed entity settings that do not affect lighting, a VBSP run with -onlyents is enough for a test. It does not update overlays or brushes, and a release needs a full compile.