Writings

Half-Life level design: Common errors and problems

Error messages from the compilers can be really cryptic at times. Here's a list of some of the most common errors and their causes.

The list of errors is in the same order as the compiling tools should be run. This order is CSG, BSP, VIS and finally RAD.

_{Note: This tutorial was written for and applies to Valve Hammer Editor 3.x with the popular ZHLT compiling tools.}

CSG: Token too large

Token too large on line 5

Reason: A string in your .map file is too long.

The compile tools can't handle excessively long strings of text in .map files. This error is nearly always caused by a line that lists the WADs you're using in your map.

To fix this, you'll need to clean up your WAD list in the Options menu, Textures tab. Try to keep the list to a minimum for performance reasons, and don't add any WADs that aren't meant for mapping (such as cached.wad and pldecal.wad).

CSG: Outside world

Error: Entity 0, Brush 14: outside world(+/-4096): (-256,16,-64)-(-144,128,10032)

Reason: A brush is outside the allowed mapping area or it has an invalid structure.

There are two reasons for this error:

There's a brush outside the allowed region, shown as the grid area in the editor. To find out if there is a brush outside this area, zoom out as much as you can in all viewports and look for any brushes around the edges of the grid. If they're outside, you only need to move them back in to fix this issue.
When you have a brush that has a non-recognizable face (almost always due to bad vertex manipulation), the editor tries to make a valid brush out of it, sometimes resulting in hugely stretched faces. This causes parts of the brush to extend outside the allowed area. The coordinates in the error message usually go far beyond the limit of +/- 4096.

You'll be able to find the offending brush with the brush/entity number in the error message and the Go to brush tool. If it's an invalid brush, it's probably easier to just redo it.

CSG: Coplanar plane

Error: Entity 0, Brush 14, Side 6: has a coplanar plane at (-64, -64, -64), texture AS

Reason: A brush has more than one face on the same plane.

The Half-Life engine doesn't support a certain kind of brush structure, which ends up causing this error. An extra "edge" like in this example may look normal, but will stop the compiling process:

Find the invalid brush using the Go to brush tool using any brush/entity numbers from the error message. Use the Vertex Manipulation tool to move the offending vertices to either side, and answer Yes to the "Merge vertices?" prompt.

CSG: Plane with no normal

Error: Entity 0, Brush 14, Side 0: plane with no normal

Reason: One face of a brush doesn't have any surface area.

When you manipulate a brush and move a vertex on top of another one, the editor prompts you to merge them. Answering No is basically only good if that's a temporary position. If you don't merge them, you run the risk of getting errors such as this one.

Find the brush with the number in the error message. You can either redo the brush or use Vertex Manipulation to properly merge the vertices.

CSG: Missing '[' in texturedef

Error: Missing '[' in texturedef (U)

Reason: The compile tools couldn't read a texture name.

There are a couple of reasons why this is happening:

You have a space or some other illegal character in a texture name. Note that illegal characters also include 'ä', 'ö' and other similar letters used in some languages.
There is no texture applied to a face of a brush. The editor will find them with the Check for problems tool.

BSP: Leak

Warning: === LEAK in hull 0 ===
Entity light @ (   0,   0, 128)
Leak pointfile generated

Warning: === LEAK in hull 1 ===
Entity light @ (   0,   0, 128)
Leak pointfile generated

Error: Stopped by leak in hull 1

Reason: A point entity in your map can see into the void.

There are basically three different causes for a leak:

Your map isn't completely sealed. Even a tiny hole or misalignment can cause this.
You have a point entity outside your map.
An outer wall of your map is actually a brush based entity, such as a func_wall.

To figure out which of these is causing the leak, you need to think of any changes you've done since your last successful compile. If you can't figure out the reason, use the following commonly used methods to find what's causing the leak.

Pointfile

As you can see, the error says "Leak pointfile generated." That's an important file when looking for a leak.

If the compiler script doesn't do it automatically, copy the pointfile called yourmapname.pts to the game's map directory. You should have the corresponding file yourmapname.bsp in there already.
Run the game and load up your map in a single player game.
Pull down the console and type "pointfile" (without the quotes) to load the pointfile. If the game complains about too few particles, add the parameter "-particles 100000" to your game's command line. Increase the number as necessary.
You'll see a black-and-white line going around somewhere in your map. Fly around in noclip mode (type "noclip" in console) and try to find it. The start point of the line is at the coordinates shown in the error message.
Follow the line and find the point where it jumps outside your map. If it seems to go through a wall, make sure that the wall isn't tied to an entity. If the line actually starts from the outside of your map, look for a point entity in the editor at those coordinates.

Big Block Method

This method is based on sealing the leak in order to find it. It's a brute force approach and can get confusing with multiple leaks, so using a pointfile could be much faster in many cases.

Create a huge solid block to cover approximately half of the map and compile the map. For a faster and less cluttered result, try running BSP with the "-leakonly" parameter, and also skip both VIS and RAD.
If the leak is still present, you'll know that your leak is in the other side of the map. If the leak is gone, scale the big block to cover only half of the previous area. Compile again.
Repeat the process until you can pinpoint the leak. If I use this technique, I prefer to use the top viewport to scale the brush. I only start scaling on the Z-axis when the block is small enough.

VIS: Portal file does not exist

Error: Portal file 'mapname.prt' does not exist, cannot vis the map

Reason: VIS couldn't find the .prt file that's supposed to be generated by BSP.

This error can occur when BSP wasn't run at all, or the tools were run in the wrong order. Another common reason is an error in a previous part of the compiling process.

Look through your compiling log for the cause. If you have doubts about your compiling order, make sure the tools are run in this sequence: CSG, BSP, VIS, RAD.

The whole map is fullbright in-game

Reason: The RAD part of the compiling process wasn't successfully finished.

There are 2 very common reasons for this problem:

There was an error in the previous parts of the compile, but a playable .bsp file was still built. Check the compile log and see if you can find any error messages.
You haven't put any lights in your map. RAD requires that at least one light of some type (point entity, texture light, etc.) is present. If there is none, it will render the map fullbright.

henry.jarske.net