Replacing NPC Models - Mini-Tutorial & Discovery Log


This Xen-bloodied guard is the first thing I’ve done with a technique I’ve just discovered for replacing the character models on NPCs by keyvalue- i.e., using values settable on an NPC-by-NPC basis in the hammer editor.

Those of you familiar with Black Mesa modding will be aware that this can already be done with the character manifest, a script file that the game consults and, if it finds a name matching the NPC in the map, will give the NPC features as described in the entry in the file. This is used to set hair, glasses, face shapes, etc., and can in fact set the body model of the NPC. In the vanilla game this is mostly just used to switch between the normal (clean) and ‘hurt’ (bloody) models for scientists and security guards, but you can put any model you want in there and have, for instance, an entity that is programmatically a security guard and will use a guard’s AI and dialogue, but looks like a Marine and has a Marine’s animations- or a completely custom model you made yourself. Azure Sheep uses this functionality to make its ‘maintenance worker’ and ‘Barniel’ NPCs by putting a custom model over a security guard or a security model over a female scientist, respectively.

The problem is that the character manifest does not integrate well with the Workshop mod download system and cannot just reference multiple files the way, say, a map list can. This means you have to manually install mods which modify it, and additionally multiple mods which do so must be manually merged in a text editor else they will overwrite each other. This is not a problem for Azure Sheep which uses its own executable to launch and (I think!) inserts a separate game path entirely, but for a plug-and-play mod like pre-disaster is just not workable.

However, there is a work-around that allows the model an NPC uses to be specified in the Hammer editor within a specific map. This will override the default model of the NPC and also any model specified in the character manifest. All you need to do is turn off the “smart-edit” option in the NPC’s properties window and add a key with the name “model” and the value “/path/to/your/model”- for instance, the guard above has models/humans/guard_xend.mdl, which is just the guard_hurt model with a different texture where the red blood has been turned yellow. That’s really all there is to it.

A few things I am still looking into:

  • I think the Hammer editor will in many circumstances fail to preserve the added model keyvalue over things like changing the entity class. This is kind of annoying but I don’t think will occur super-commonly so I am tempted to just live with it. Might be possible to add this keyvalue more formally by modifying the game’s FGD.
  • One thing to look out for is that not all models have the same animations, and sometimes the NPC you’ve changed the model of will try to programmatically call an animation its new model doesn’t have. I remember there being problems specifically with security guards and soldiers having different run animations and thus being unable to move. I haven’t tested this but in theory if you make a new model with animations that have the same names the NPC will work properly. Since many NPCs have the same skeleton to them it may even be possible to directly copy animation files while making the model.
  • I am not sure how character-manifest-defined bodygroup elements (hair, glasses, face flex, etc) react when the model of the NPC is changed, or if it is possible to change elements from either the old or new model by adding some other keyvalues in Hammer.
  • It is actually possible to change NPC models semi-dynamically in the game engine by firing the “addoutput” input at them with a new “model /path/to/model” parameter. However, this requires the game to be saved and reloaded to take effect, so I do not think it’ll find much use. It’s possible the engine can be commanded to update those models and only those models in a timely manner through, say, a console command, but I doubt it.

On the other hand, though, this has opened up a number of new directions for Black Mesa modding to take:

  • It will now be possible to add construction worker, office worker, and other NPCs to Pre-Disaster maps, as well as ‘Otis’ model security guards if someone ever makes a model for them. This was possible before, but only by using the compatibility-breaking overrides to the character manifest.
  • If I can get the animation issues ironed out (or just have them standing still) I can now add friendly Marine NPCs to high-security areas of the facility who will respond like security guards when talked to.
  • It is now possible to add fully-functional office worker, construction worker, and other models to canon BM maps just by editing the maps themselves- this means that incompatibility issues will only arise if another mod edits those specific maps, not any other mod trying to edit any other elements of the character manifest.
  • Opposing Force remake authors can now make HECU NPCs who will follow the player like guards would, and Black-Ops NPCs who are reskinned Marines. This was possible before, but not in a workshop-compatible
  • Similarly, this simplifies somewhat the modifications that would be required to add female versions of guard or Marine NPCs and makes them workshop-supportable. However such NPCs would still have the male combat/idle dialogue. I think it might be possible to use response contexts and custom soundscape files to replace dialogue wholesale, but I don’t know for sure.


Zen blood covered guards… why isn’t that something in the base game, I mean hunter in the lambda lab would seem more like a bad ass if they where covered in blood and looked like they have been through hell.

Maybe with a bloody and shot vest on the ground, them not having their vest.

Think that was the name of that guard.


Discovered a slight limitation: for this trick to work, NPCs must be given a name corresponding to an entry in the character manifest file which does not specify its own model line- a character manifest entry with a model, or no name at all, or a name that doesn’t correspond to any character_manifest entry, will not work. So until I can find out more, it would be a good idea to check the character manifest for any NPCs you are planning to remodel and make sure they do not have a model specified.