A CS 1.6 map is built by four separate command-line programs run in order: hlcsg, hlbsp, hlvis and hlrad. Each takes its own flags, and the difference between a 20-second iteration compile and a 40-minute release compile is entirely in those flags. There is no single -final switch that does everything; "final quality" is a specific combination of full visibility and high-quality lighting. This explains the flags that actually exist in Vluzacn's VHLT (the maintained ZHLT fork) and how to build a fast pass and a release pass.
1. The four stages
| Tool | Job | Skippable for a draft? |
|---|---|---|
hlcsg | Turns brushes into raw geometry, bakes WAD textures. | No — always runs. |
hlbsp | Builds the BSP tree, detects leaks. | No — always runs. |
hlvis | Computes what is visible from where (PVS). | Yes, but the map renders everything at once. |
hlrad | Calculates lighting and shadows. | Yes, but the map is fullbright. |
2. hlvis flags: the visibility trade-off
hlvis is the slow stage on large maps. It has two real quality levels:
hlvis -fast mymap // rough PVS, quick, over-draws — fine for testing hlvis -full mymap // full PVS, slow, tight — use for release
Run with no flag for the default (mid) quality. Never ship a -fast vis compile: it over-renders and hurts client FPS in busy areas.
3. hlrad flags: the lighting quality
hlrad is where a map goes from flat to good-looking, and where release compiles spend most of their time. The flags that matter:
hlrad -extra mymap // supersampled lighting, much smoother shadows hlrad -bounce 8 mymap // number of radiosity bounces (default is low) hlrad -chop 64 mymap // luxel patch size; smaller = finer, slower hlrad -smooth 50 mymap // angle below which faces are smooth-shaded hlrad -sparse mymap // lower memory, slightly slower vis matrix hlrad -fast mymap // quick, blocky lighting for a draft
For release, -extra plus a few extra bounces is the classic quality combination. For iteration, -fast (or skipping RAD entirely) keeps the loop tight.
4. hlcsg and hlbsp flags worth knowing
hlcsg -wadautodetect mymap // only include WADs actually used hlcsg -nowadtextures mymap // embed textures in the BSP (no external WAD) hlcsg -onlyents mymap // re-export entities only, no geometry rebuild hlbsp -leakonly mymap // stop at the first leak, skip the rest hlbsp -nofill mymap // do not auto-fill; useful when hunting leaks hlbsp -subdivide 512 mymap // face subdivision size
-onlyents is a huge time-saver: if you only changed entity keyvalues (a light color, a spawn angle) you can re-export entities in seconds without recompiling geometry, VIS or RAD.
5. Shared diagnostic flags
Most stages accept these, and they are worth adding to every compile:
-chart // print a resource usage chart (planes, clipnodes, textures) -estimate // show a running time/percentage estimate -verbose // detailed output for debugging a stuck stage -low // run at low CPU priority so the machine stays usable -texdata 16000 // raise texture memory limit for texture-heavy maps
The -chart output is your early warning for hitting engine limits — clipnodes and planes have hard ceilings, and a map that is near them will fail to run on a server even if it compiles.
6. A draft pass and a release pass
Use two saved presets in J.A.C.K.. A fast iteration pass:
hlcsg -wadautodetect mymap hlbsp mymap hlvis -fast mymap hlrad -fast mymap
A release pass:
hlcsg -wadautodetect -chart mymap hlbsp -chart mymap hlvis -full mymap hlrad -extra -bounce 8 -chart mymap
Troubleshooting
- Compile takes forever on VIS — you ran
-fullon a leaking or over-sized map. Fix the leak first; VIS should never run on a leaked map. - Lighting is blocky/pixelated — you compiled RAD with
-fast. Re-run with-extrafor release. - "Exceeded MAX_MAP_CLIPNODES" or similar — you hit an engine limit; the
-chartoutput shows which. Simplify geometry or tie decorative brushes tofunc_detailso they leave the BSP hulls. - Textures missing after compile —
-nowadtextureswas off and the WAD is not on the server, or a WAD went missing. Either ship the WAD or embed with-nowadtextures. - Entity change not showing — you used
-onlyentsbut also moved brushes; that flag ignores geometry. Do a full compile after any brush edit.
Verification
Run the release preset and read the tail of the console: hlvis and hlrad should both complete with a -chart summary and no leak warning. Load the map and confirm the lighting is smooth (no jagged shadow edges) and that distant rooms are culled when you cannot see them. Keep the draft preset for day-to-day edits and only pay for the full pass at release. If VIS or RAD refuse to run at all, the map is almost always leaking — go back to the pointfile guide.
