Preventing problems

Read as many beginner tutorials as you can find before you begin. You'll still make mistakes inevitably, but doing this will lessen their severity and frequency. TWHL has some excellent tutorials as well as many other sites.

Compile often. You'll find any problems more quickly, before they can "gang up" on you, and become completely unmanageable. For my first map, I built the entire thing, complete, before running a single compile! This is so absolutely the wrong way to go about it. Not only did it not compile, I don't think I ever got that first version to compile, ever. I ended up redesigning the entire thing, and learning this hard, albeit valuable lesson.

Hammer gives you a couple powerful allies to squash problems before compiling. Probably the most useful is hitting ALT-P, bringing up the "Check for Problems" Dialog: This tool is great for finding the dreaded "Invalid solid", error, as well a host of others. Click the "Go to..." button to select the offender. At this point, I usually delete whatever the problem is, and do it over. Your other option is clicking on the "Fix" button, but I'd not really recommend it. More often than not it doesn't fix stuff, and when it does, it's usually not the way you want it, and/or creates more trouble. "Entity contains unused key-values" is generally harmless but can sometimes causes very weird in-game behaviour.

Reading the Entity Report—brought up by clicking on the "Map" menu, and then "Entity Report..."—is the second in my opinion. Delete/locate/modify every single entity in your map. You may think you've deleted something, or changed it to a world brush, when in fact, it hasn't. Check the entity report periodically to make sure everything is ship-shape. One example of this is changing a brush To World—CTRL-W—but it's still compiling as an entity. Just go into the entity report, pull up the offender, and zap--delete--it!

Diagnosing Problems

OK. Now you've done everything you could think of to prevent trouble, but it still finds you. It's OK, because you still have some powerful resources left at your disposal...

Reading the Compile Log

Ya, that thing that pops up while your compiling, and is also available as a separate file in your <path/to/your>/Mapname.log (e.g. hammer/maps/Mapname.log). The compile log is a long list of each stage of Hammer converting your .rmf/.jmf file to a playable .bsp.

What we're interested in for the purposes of the tutorial are the errors. So, after each stage of compiling—HLCSG, HLBSP, HLVIS, HLRAD—Hammer will tell you if there are any problems. Also, sometimes Valve Hammer will create a error file—Yourmapname.err, located in the same folder as the exported .map file—with just the errors, and none of the other compile info, which makes them a little easier to read. Here are some common errors, and there fixes for some common troubles...

The types of errors in the log matters too. Error: lines are showstoppers and must be addressed. Warning: lines does not stop a compile, and depending on the warnings, can be safely ignored, even intentional.

CSG common problems

Error: Entity 19, Brush 1, Side 1: plane with no normal
Error: Entity 19, Brush 1, Side 1: has a coplanar plane at (3165, 3310, 3664), texture {GELAENDER

No big deal, concave or coplanar In my understanding mean pretty much the same thing, and that is two of the faces of the same brush can 'see' each other, and would be better off being one instead. The only really important thing to know imo is how to fix this, since in time, you will learn exactly what causes them.

Pretty simple, with two main fixes, one easy and one a little harder. The first way is to open up hammer, load your map, and hit Alt-P to bring up the check for problems utility. Click on the offending brush and click the fix button. This fixes the problem so you will no longer get the error message, but changes the brush in a way you may not like.

The better and slightly harder way to fix this is to hit Alt-P again, click on the offending brush, and delete it. Then, make an new brush. The best way to achieve this is by making the same brush out of 2 or more spikes/wedges. I've also heard of clipping the offending brush instead of deleting it, thereby separating the offender into separate brushes—ideally, you'd be clipping it right where the faces are 'seeing' each other—, but I've never tried it.

outside world(+/-4096): (-4048,-2064,-4132)-(4016,4048,-3036)
Error: brush outside world

This is almost always caused by the outside walls of your level being too close to the boundary of one of the 2D views in hammer. Move it away from there and you should not get the error anymore. Can also be caused by a corrutpted brush, or a corrupted brush tied to an entity. In both cases you should delete this brush and do it over. In the second case, also pull up the entity report and delete that sucker, else the error will still show up.

Interesting note about this error and a clue that's something wrong, is if you have an origin brush entity that's borked--say a func_tank. If something with the origin is causing the error, you'll notice that the center x in hammer will glow red when and only when the bad entity is selected.

Error: Entity 0, Brush 135: mixed face contents
Texture BARREL3 and !TOXICGRN
Error: mixed face contents

This one is exactly what it says. Textures like liquids and origin are special, and cannot be 'mixed' with other textures of a different type. Every side of brushes using these textures must be applied to all sides of said brush.

HLBSP Common Problems

SolidBSP [hull 0] 500...532 (0.05 seconds)
Warning: === LEAK in hull 0 ===
Entity func_door_rotating @ (-312, 210, 132)
Error: A LEAK is a hole in the map, where the inside of it is exposed to the (unwanted) outside region...

Yep, A leak. Not a complicated problem really, but can be a bitch if you build your whole map, and it's huge, and have to hunt for them. These are the people who struggle with leaks, those who don't compile early and often. And as for the pointfile, I would recommend not wasting your time with it.

Just make sure there is no part of your map that can 'see' the void--cool word for the outside of your map--, and you'll be fine. Making any or even just one of your outside walls an entity, will also cause a leak. There are many techniques for finding leaks--which I will not discuss here--, but as long as your careful, and compile often, you should never have a problem with them.

VIS common problems

Warning: Leaf portals saw into leaf
Problem at portal between leaves 3 and 7: (56.000 816.000 592.000)

Caused by having too complex a brush--too many sides, weird angles. To fix, clip it in to 2 seperate ones, and or delete it and start over. This brush shouldn't be too hard to find, unless you have tons of complicated geometry in your map, and in that case, you've got bigger problems!

RAD common problems

Error: Exceeded MAX_PATCHES

Too many Brush faces in a map and/or If you have a huge skybox around your level. Solution: Make your map smaller or less busy.

Error: Bad surface extents (7 x 7836)

Caused by scaling textures way too small or way too big. If you're not sure about a brush, scale bot x and y dimensions so it equals 256. So say If you have a 16x16 texture and you think it may be buggering your map, multiply each dimension by 16 to give you the magic 256 size. 64x4, 32x8 and so on. This won't make the texture work the best, but the easiest for Valve Hammer Editor to digest.

"Warning: Too many direct light styles on a face(-2920.500000,355.854797,19.500000)

A face can have a maximum of 4 light styles. This includes static, animated (using light styles), and named lights (with optional custom patterns). The lighting sources may be from point or texture lights (using ZHLT's func_wall style hack or VHLT's light_surface). While spicing up a map with animated lights is a plus, this limitation means you can't have too much of different lighting styles placed too close to each other. On the other hand, having a bunch of them in close proximity sharing the same styles is safe, as their combined contributions will all be merged into a single style for the affected faces.

This warning is not fatal. It's just that lighting on faces will be blotched as the RAD compiler has to arbitrarily choose which light sources would have an effect on the affected faces, and which to discard.

Recommended remedial actions:

• Place unnamed light sources with different styles, and named lights with different names, in separate areas of the map (e.g. in different rooms, separated by a corridor)
• Consolidate named lights to turn on/off together by giving them a single shared name (and optionally a shared custom pattern). This will all be merged into one single style.
• use -coring <value> compile parameter, or entity keyvalue zhlt_stylecoring to define a brightness threshold on lights. Lighting that falls below the threshold gets dropped to 0, in effect limiting how far the light spreads.
• Consider using entity effects as alternate dynamic lighting sources (caveat being it has fixed colour, white, and a fixed effect radius)
• Remove extra light sources.

More information is available in Tutorial: The Complete Guide to Lighting page, sections §3.17 - Light styles and §3.24 - Coring.

More troubleshooting resources

For a more comprehensive list of errors and their causes/solutions, check out some of these:

• ZHLT Info which also comes with Zoner's tools.
• Tommy14's error page, an extremely comprehensive list.

Search the forums

Google and the Forums (be sure to search them before posting) are both excellent resources for troubleshooting errors. Problems your having have almost certainly happened to someone else, or lots of someone else's. Learn from their mistakes!