Source is just like any other game engine or computer in general: it only does what you tell it to. Even then, as any Source veteran will tell you, she's a feisty old SOB, so sometimes just being patient will be your best weapon.

Last Guide Update: 2018 October 19

While not every issue can be outright fixed, a good few of the issues you see are caused by errors on the part of content creators.

As always, if you're a novice to Source, watching tutorials, checking the wiki, and looking at guide should help. If you're new, or passing through on your way to parts unknown, welcome to this guide.

• The Valve Developer Community (VDC) - The official Valve/Source/GoldSrc wiki
  
• The Garry's Mod Wiki[wiki.garrysmod.com] - The official wiki for GMod and such. Due to GMod being such a strange beast itself in the world of Source, at times there will be both overlap and outright differences.

If you find any error not listed here, shoot me a message or comment. Obviously working with this thing for a decade, I have most definitely forgotten some of the cornucopia of errors it can spitball you with.

Overview

For this guide, we're not diving majorly into how materials/textures work, but how to identify and fix some common material-based errors. To do this, we need a bit of background information.

In the Source engine, materials are typically defined in layman's terms as the material files. What this means is the Valve Material (.VMT) format.

Textures are defined as the Valve Texture Format (.VTF) file type.

These two are both separate, but equal. Without a .VMT file, the model or Hammer will completely disregard the .VTF files, because it has no way of knowing what to do with them.

A Normal, Working Material

The following is a normal, working material file:

Please note that "quotes" are not required if the string or input does not use white space. For the most part, basic material commands are also case-insensitive.

The material abouve will appear as this in-game:



As you can see, it has an albedo, bump, lightwarp, and detail map. All of which are currently working properly. But that's boring, so let's start breaking this thing.

Dude, Where's My Material?

If the .VMT file can't be found at all by the model in any of the paths the model was compiled to look for it in, it will just be purple and black, like my goggled-doppelgänger here:



Note the complete lack of, well, any kind of detail. What kind? Let's keep moving.

A Missing Albedo Map

If the engine can't find the albedo map, either by typo or it just outright not existing, it will not tell you. It will just throw a visual error, such as this:



As you can see, the detail map has loaded, as indicated by the detail-y-bits, while the base itself is missing. This can be used as an indication that the .VMT loaded, but something's wrong with it.


As you can see, even something like an underscore can throw the thing into chaos. Check for typos if you're sure that the texture exists.

A Missing Normal Map

While a missing material or albedo will be purple, a missing normal or bump map can be a bit more cryptic. Instead of the normal purple & black checkerboard a lot of us are familiar with, it will look like this:



A missing bump map can be indicated by the "shadow/ghost"-like checkerboard overlay. Note that the albedo texture loaded, as well as the detail map. This means it loaded the .VMT, but that there was once again something wrong with it.

Lightwarped Reality

However, since there's a bunch of these materials you can use, we also need to cover lightwarps.

Lightwarps are a bit more obvious when they're messed up:


Instead of a checkerboard, the whole dang thing is just bright pink. Check your lightwarp.

Exponential Errors

Next, I'm going to lump two semantically-named and somewhat-related errors together: Cubemap Masks and Phong Exponent Masks.

For the former, it involves the use of the $envmap parameter; layman's terms, the venerable (if dated) cubemap. Ask any mapper, and they're bound to give cubemaps a verbal brow-beating at least once if they've used them. However, a missing cube map mask, via the $envmapmask command also throws another visual error.



This will not be the only way you'll see the error, as cubemaps themselves, like phong, also combine several other subcommands into the .VMT to gain specific effects as-desired. Like the others, it will require a keen eye to make sure you didn't screw up the paths. As the errors are not 100% consistent in appearance, take this advice: the engine only does what it's told. Check your strings if something doesn't look or feel right.

Detailed Errors

Last on this list: the detail map.

Detail maps are a great way to gain extra effects on your models without extra geometry. For example, here's a model with only a basic $basetexture command:



And here's the same model with a nice detail texture and some other edits done purely via the .VMT file:



However, like the other materials, if you mess up the paths, it will also appear broken as hell in game:



You may notice this one appears similar to a missing .VMT or missing albedo, but note the effects of the lighting on it. Depending on the blend factor of the detail texture overlay, it might look more like this:



Since detail maps are just a texture overlay, the $detailblendfactor command can greatly alter the appearance of not just the texture, but the error as well. Use your head to figure it out.

You might, albeit rarely, run across the issue like this with certain textures. They'll look fine, but if you just twitch your view a tiny bit, they go ballistic like this:



This is an issue with the $ssbump settings. Something, either (less likely) the .VMT settings, or (more likely) the .VTF file itself being defined by the $bumpmap setting isn't properly formatted.

Easiest thing to do is convert it to the standard blue-hue bump maps we all know and love-hate, or if it ABSOLUTELY MUST BE A SELF-SHADOWING BUMP MAP check your .VTF flags and formatting.


I'm putting this in the material section, since it's a material error.

When using the VertexLitGeneric material type on a brush this will almost consistently happen.



The reason? Like it says in the text of VertexLitGeneric: it is a model material, not a brush material.

For brushwork, you will need to use LightmappedGeneric.

Somewhat related, you should almost always try to stick to using WorldVertexTransition on displacements, as it might work to use the former, but the latter is pretty much meant for it. Likewise, if you use WorldVertexTransition on a model or a standard brush surface, don't expect it work right, either. Propper sends their regards.

A Model Error

Models are another fine piece of work. The third dimension of the geometry means it has another vector at which to go bonkers.

Über Flex

For models, many of them use the old Enhanced Citizens ragdoll physics. This is good if you're a scene builder or a poser, and bad if you're a player, since dying in inhuman positions can be a bit of an immersion breaker at times.



Using more "natural" flex limits for NPC and players is recommended, unless you want countless comments complaining about them "melting"

A good death ragdoll for most things will collapse like this.



Unless you want A.) a poser-friendly model, or B.) something out of a cartoon, use normal flex limits on NPC/player ragdolls.

Speaking of Melting

So people complain about the hyper-flex being melty? Allow me to retort:



This is a melt. Don't ask me how or why it did that, because it was a one-off error I had in 2011. If I had to guess, check your ragdoll file for something that would cause his bones to disappear or unclamp.

Bad Rigging

I'll be the first to admit it here: organic rigging is a massive pain in the sphincter. You have no idea how annoying, time consuming, and downright infuriating it is until you try it.

But just because you can shelve the model for a while, doesn't mean you should push some complete broken and awful models to the base-game just because you lack the skill to do it right.




I could go on and on for hours about the number a certain modeler did on a good portion of the stock GMod models, but we don't have the time or need to cover that.

Basically, don't be lazy. If you need help, ask someone. If you need more skill, practice. Don't be a jabroni.

The "Who Made That Man A Gunner!" Bug

You know the scene from Spaceballs where the gunner is shooting at the ship and missing every shot? It's like that.



Check your .QC files for the lines that control eyes. Some likely suspects are your $eyeposition or one of your Flex animation settings like the following:

There's a saying: excess copy makes a coder sloppy. In the case of the HL2 citizen heads, they each usually have some different settings for eyes, so just mindlessly copying them will probably lead to issues like this, like my screenshot there. I used the BMS head eyes with the ArmA head models, without checking the positions.

The "Creepy Student Film" Bug

You know those bad (purposely or not) student films where the model just basically explodes when it moves? It's popular in GMod and SFM animations as a comedic tool, but it can also appear when you really don't want it to:



Somewhere, likely in the finger areas at times, the bones won't match. As a result of the new model not having a freaking clue what to do with those extra fingers since HL2 character usually have mitten hands, it will just do... that.

Check your .QC files if it's a compiled model. If all else fails, use the $definebone commands to define the bone if adding it to the root mesh in a modeling software isn't an option.


We all know it. The dreaded (although incorrectly named) "t-pose" model.



Whatever $sequence the model is looking for isn't being found. If it's a replacement for the Rebels, Combine, or a default NPC on the default Valve biped, it means one of two things:

• Your bones aren't right
  
• The animation files added to the model via $includemodel are conflicted, corrupted, or otherwise missing

Check the files for conflicting models from other games, or if the model itself actually has the right path.

Reminder: GMod uses the 9-way animation system for players, while NPCs use the older 8-way system. Under no circumstances should you mix HL2 NPC and GMod player animation files, as they will lead to massive reference posing issues like this.

A Feisty SOB, for Sure

Let's face it Hammer is a lot like our grandparents; old, cranky, and complaining all the time about trying to make them change or do things differently. However, Hammer is at the same time a program that if you treat it right, it might treat you well in kind.

You know what they say about staring into the abyss? Eventually it stares back, shakes your hand, and takes you out for coffee.

Learning to work with Hammer's quirky & inconsistent behavior is just part of working with it in general. The best skills you can have when working with Hammer, are adaptability, creativity, and persistence. No dingus on the internet ever made a good map by quitting the first time he crashed Hammer.

That being said, there are a few operator errors you can have with Hammer.

No-NoDraw

Don't use nodraw on displacements



Open and shut, using tools/toolsnodraw on displacements will, somewhat manically, defy nodraw.

Ignoring the Entities

You might find that sometimes after compiling a map, that you find an entity you specifically know for a fact you set up, has reverted to, well, just a big trigger-textured brush instead of a trigger brush.



Unfortunately, you better have a backup, because this likely means the brush was at some point during editing, messed with in a way that would cause it to lose its entity data. A likely candidate is by using grouping or the Ignore Groups setting while messing with entities.

Remember: when copying or otherwise messing with entities, do not leave Ignore Groups selected, as the copies will all be copied as basic brushes, and not entities. In the worst case, the original entity itself might become corrupted.

But just in case, here they are.




No idea to this day what happened here, because it only happened once upon starting the map in EP2, and after just reloading the map it worked.


No, this isn't an episode title from the smash-hit TV show Butt Ugly Martians, it's a bug that was fixed many moons ago in GMod that would cause the entire texture cache to basically go apes!@# and corrupt itself.



Hasn't happened since about 2012 when GMod 13 went out, but if it happens, just shut the game down and restart it. No use trying to fix that, it's a write off.


Ask any GMod old-timer, and they'll likely know about this old issue named Reliable Snapshot Overflow. Basically, if the server had too much going on, you'd likely lose connection with a very irritating, and mis-spelled error message:
(Credit: Guillaume Bois, Stack Exchange)

GMod managed to fix this years ago, while other Source games like TF2 apparently still have it, according to this Stack Exchange thread[gaming.stackexchange.com] I shamelessly stole that image from.