Fixing Source Engine Map Leaks and Cutting VVIS Compile Time

When a Source Engine map compile stops with a leak error, or VVIS runs for hours, the cause is usually the same: the world geometry is not sealed, or it is sliced into far more leaves than the visibility pass can handle. Both problems are fixed in the map source, not in the engine. This guide covers the compile order, how to trace a leak with the pointfile, and how to cut VVIS work without breaking the level.

What each compiler does, and why order matters

• VBSP converts world brushes into a BSP (binary space partitioning) tree, splitting space into convex leaf nodes and deciding what is inside the map versus the void outside it.
• VVIS builds the Potentially Visible Set (PVS) — for each leaf, the list of other leaves that can be seen from it. It needs a sealed map to bound that calculation.
• VRAD bakes lightmaps by ray-casting direct and indirect light. It is slow but does not affect structural integrity.

A VBSP leak stops VVIS from producing meaningful visibility data, so fix leaks before tuning anything else.

Prerequisites

• Hammer from the SDK matching your game branch (for example Source SDK 2013 for HL2-era mods).
• A saved .vmf map file.
• At least one info_player_start inside the playable space; VBSP uses entities to decide which side of the geometry is inside.
• Write access to the game's maps folder, since the compilers overwrite the .bsp.

Procedure: find and seal a leak

1. In Hammer, open File → Run Map and set VVIS and VRAD to No so only VBSP runs. This keeps the loop fast.
2. Read the compile log. A leak is reported as Leak (file: mapname.lin), along with the entity the trace reached.
3. In Hammer, choose Map → Load Pointfile. A red line is drawn from the leak point to an entity inside the map.
4. Follow the line in the 3D view. Where it crosses a wall, floor or ceiling, there is a gap. Only world brushes seal the map — brush entities such as func_door, func_brush and func_detail do not.
5. Fill the gap with world geometry and recompile. VBSP reports one leak at a time, so repeat until the log is clean.

Check: the VBSP log ends without a leak message and VVIS proceeds. If VVIS still refuses to run, re-read the log rather than assuming the seal is complete.

Reducing VVIS time

VVIS cost grows with the number of leaves and portals, and in bad cases the growth is close to exponential. Three levers matter most.

Convert decoration to func_detail

Select the brushes (pillars, trim, stair steps, window frames) and press Ctrl+T, then choose func_detail. Detail brushes are excluded from the BSP partition, so they create no leaves or portals. Overusing it on large structural walls has the opposite effect: it can hide real occluders and let the player see into areas that should be culled.

Block sightlines

• func_areaportal in a doorway tells the engine that when the portal is closed or out of view, everything behind it can be skipped.
• func_occluder on a large solid wall lets VVIS discard geometry behind it.
• The tools/toolshint and tools/toolskip textures force a BSP split where you place them, which can replace many automatic splits with a few deliberate ones.

Keep open areas bounded

A single huge outdoor room with no blockers produces a large PVS: every leaf can see most other leaves, so the visibility data grows and memory use rises. Break the space with terrain, buildings or areaportals.

Running the compilers directly

Run these from the game's bin folder (or the SDK's), with the game directory pointing at the folder containing gameinfo.txt. Replace the placeholders with your own paths. No elevated permissions are needed beyond write access to the output folder.

vbsp.exe -game "C:\path\to\gamedir" "C:\path\to\map.vmf"
vvis.exe -game "C:\path\to\gamedir" "C:\path\to\map"
vrad.exe -game "C:\path\to\gamedir" "C:\path\to\map"

Note that the later stages take the map name without the .vmf extension, because they read the .bsp written by VBSP. These tools do not modify the .vmf, but they do overwrite the .bsp; keep the source under version control or a backup copy.

Verifying the result in game

• mat_wireframe 1 shows triangle density; use it to spot geometry that is far more complex than it needs to be.
• mat_leafvis 1 draws the current leaf and the leaves in its PVS. If rooms that should be hidden are drawn, the visibility data is wrong or missing.
• Compare the .bsp size with a similar map from the same game. A much larger file usually means a bloated PVS rather than more geometry.

Limitations

This applies to the classic VBSP/VVIS/VRAD pipeline used by HL2-era branches, TF2 and CS:GO-era maps. Later Source 2 tooling and some community compiler forks change flags, defaults and even the visibility algorithm, so check the executables shipped with your SDK. Compile times also depend heavily on hardware and on whether the tools run single- or multi-threaded; treat any timing figure as specific to your machine.