Preface

 
This guide is specifically for the character models in https://steamcommunity.com/sharedfiles/filedetails/?id=2068862348 mod, and is an unofficial contribution to help other developers use the pack! This assumes you’ve followed the https://steamcommunity.com/sharedfiles/filedetails/?id=2068862348 for properly using it, and now want to define custom characters with it – with or without the knowledge of creating a character manifest. 
 

Intro

 
Source Engine’s method for storing characters is those defined in the

of a packaged game file. These define just about every aspect of how characters are “made.” If you already know this, you can skip to the next section. 

 
VPK files store a mod’s or a game’s models, scripts, materials, sounds and maps in Source. Everything is read as “from the base,” i.e., referencing “models/bob.mdl” in a script navigates to the VPK’s base, enters folder “models” and uses “bob.mdl”. Normally, developers use multiple layers, which is highly recommended for organization. 
 

Layout of Manifest Files

 
Here’s a snippet from the BMCE Misc. file: 

And one from the original Black Mesa manifest: 

This seems complex, so let’s digest it. 

• Base: The base for each character is either their class name, or their entity name – if you’ve used the manifest characters before, you’ll know that the in-mod NPC name has to match up with a specific in-manifest name. 
• flex_data: This defines how the character’s face and body are manipulated. 
• bodygroup_data: This enables or disables various models on the character, such as a guard’s bulletproof vest. 
• model: This is the packaged path to the model override, such as “models/humans/cwork_hurt.mdl” (for a hurt construction worker model) 
• skin: This is the model-specific skin for our character. Oftentimes, this affects their hair color, race and age.

Now that we know what each thing does, we can create custom characters! If you’ve used GMod’s context menu to edit the models and skins on props or ragdolls, it’s essentially the same process, but “on paper.” 
 
 

“Global” Character Attributes

BM:CE Models

 
If you didn’t know, BM:CE provides the following models: 

• Cafeteria Workers, male and female 
• Janitors 
• Construction Workers 
• Engineers 
• Improved Security Guards 
• half-life.fandom.com – https://half-life.fandom.com/wiki/Otis_Laurey our lord and overweight savior 
• Female Security Guard 
• Improved Scientists 
• Casual (no labcoat) Scientists 
• Hazmat (half-life.fandom.com – https://half-life.fandom.com/wiki/Cleansuits) Scientists 
• half-life.fandom.com – https://half-life.fandom.com/wiki/Arne_Magnusson, retconned 
• Office Workers

Global Skins

 
Black Mesa: Character Expansion (and in retrospect, Black Mesa itself) has a set of default skins per male and female model. 

 
Male Skins (Default/01) 

• 0 – White, Balding tan hair 
• 1 – White, Balding, scruffy 
• 2 – Black, Bald 
• 3 – Black, Bald, Defined Eyebrows 
• 4 – White, Smooth Hair w/ Mustache 
• 5 – White, Goatee and Squared Hair 
• 6 – White, Goatee, Balding 
• 7 – White, Goatee, en.wikipedia.org – https://en.wikipedia.org/wiki/Widow%27s_peak 
• 8 – White, Slicked Hair 
• 9 – White, Scruffy and w/ Messy Hair 
• 10 – White, Balding white hair 
• 11 – White, Goatee and Messy Hair 
• 12 – White, Balded top w/ white hair on sides 
• 13 – White, messy widow’s peak 
• 14 – White, Straight Hairline (Looks like en.wikipedia.org – https://en.wikipedia.org/wiki/Phil_Coulson#/media/File:Clark_Gregg_as_Phil_Coulson.jpg)

 
I recommend using _02 model skins at random, so unless you’ve got more time than me to list those, just do that. 

 
Male Group _03 

• 0 – White, with Mustache and chin scruff 
• 1 – White, with Silvering hair 
• 2 – Latino, with Black hair 
• 3 – Black, receeding Hairline with mustache 
• 4 – White, brown-blond hair 
• 5 – Black, Sharp, Dark hair 
• 6 – Black, Bald with Goatee

 
Female Skins 

• 0 – White, Blond hair 
• 1 – White, Gray Hair 
• 2 – White, Brown Hair 
• 3 – White, Strawberry-Blond Hair 
• 4 – Black, Lighter-Black Hair 
• 5 – Latino, Lighter-Black Hair 
• 6 – Black, Darker-Black Hair 
• 7 – Asian, Black Hair 
• 8 – Asian, Gray Hair 
• 9 – White, Brunette Hair

 
Avoid the use of the same skins in distinct characters, if you can help it. As previously stated, these are entered as single numbers in the skin group. For similar “faces,” you can delimit multiple chosen skins with commas for random choice. 
 

Glasses Models

 
Now, any cliche self-respecting scientist wears them. So here’s the list of each grouping’s glasses. 

 
Glasses Models (Worker, Male Guard, Cafeteria or Female Scientist): 

• 0 – No glasses 
• 1 – Full-Frame, Regular 
• 2 – Semi-Rounded Frames 
• 3 – Harry Potter-style Round Frames 
• 4 – “Emo” frames; Shorter 
• 5 – Half-Rims 
• 6 – b i g Frames 
• 7 – 70’s Frames (Steve Jobs) 
• 8 – 60’s Frames (Weirdly Wide) 
• 9 – THICK Frames Female; AVIATOR Frames Male 
• 10 – AVIATOR Frames Female; AVIATOR SHADED Frames Male 
• 11 – MARINE Shades Male

 
Female Guard models 

• 0 – N/A 
• 1 – Full-Frame, Regular 
• 2 – Semi-Rounded Frames 
• 3 – Harry Potter-style Round Frames 
• 4 – Ear Pencil 
• 5 – “Emo” 
• 6 – Half-rims 
• 7 – Big frames 
• 8 – 70’s style 
• 9 – 60’s style 
• 10 – Thick frames 
• 11 – Aviators

 
Male Scientist (including cleansuit) models 

• 0 – N/A 
• 1 – Full-Frame, Regular 
• 2 – Semi-Rounded Frames 
• 3 – Harry Potter-style Round Frames 
• 4 – Ear Pencil 
• 5 – Emo Frames 
• 6 – Half-Rims 
• 7 – Goggles 
• 8 – Goggles, Up on Forehead 
• 9 – Thick-Frame 
• 10 – 60’s Style 
• 11 – 70’s Style, Silver 
• 12 – Aviators, Silver

 
Construction, Engineer and Custodian models 

• 0 – N/A 
• 1 – Goggles 
• 2 – Goggles, Up on Forehead 
• 3 – Full-Frame, Regular 
• 4 – Semi-Rounded Frames 
• 5 – Harry Potter-style Round Frames 
• 6 – Ear Pencil 
• 7 – Emo Frames 
• 8 – Half-Rims 
• 9 – Thick-Frame 
• 10 – 60’s Style 
• 11 – 70’s Stlye, Silver 
• 12 – Aviators

Flex Groups

 
Flex Groups are scales on which various character model attributes are affected. An informal introduction to this can be found in https://developer.valvesoftware.com/wiki/Flex_animation or in the https://developer.valvesoftware.com/wiki/Choreography_creation/Creating_Events/Facial_expressions on the official wiki. If you’ve used SFM to any degree, or used GMod’s Face Manipulator, you’ll be familiar with these. If you don’t want to make custom face and body shaping attributes, skip this section. Unless expressly defined, all of these groups have a scale factor from 0 to 1 respectively. 
 

EYELIDS

 
right_lid_raiser, left_lid_raiser, right_lid_tightener, left_lid_tightener, right_lid_droop, left_lid_droop, right_lid_closer, left_lid_closer, blink 
 

EYEBROWS

 
right_inner_raiser, left_inner_raiser, right_outer_raiser, left_out_raiser, right_lowerer, left_lowerer 
 

NOSE

 
right_cheek_raiser, left_cheek_raiser, wrinkler, dialator 
 

MOUTH

 
right_upper_raiser, left_upper_raiser, right_corner_puller, left_corner_puller, right_corner_depressor, left_corner_depressor, chin_raiser, smile, lower_lip 
 

PHONEME AND JAW

 
right_part, left_part, right_puckerer, left_puckerer, right_funneler, left_funneler, right_stretcher, left_stretcher, bite, presser, tightener, jaw_clencher, jaw_drop, right_mouth_drop, left_mouth_drop 
 

FACE SHAPE

 
brow_h, cheek_depth, cheek_fat_max, cheek_fat_min, chin_butt, chin_width, chin_height, face_d_min, face_d_max, head_height, head_w_min, head_w_max, neck_size, ears_angle, ears_height, eyes_ang_min, eyes_ang_max, eyes_height, jaw_depth, lowlip_size, uplip_size, mouth_w_min, mouth_w_max, mouth_h_min, mouth_h_max, nose_angle, nose_d_max, nost_height, nost_width, nose_tip, cigar_mouth, hairline_puff 
 

SPECIAL FACE MODIFIERS

 
head_rightleft (from -30 to 30), head_updown (from -15 to 15), head_tilt (from -15 to 15), eyes_updown (from -30 to 30), eyes_rightleft (from -30 to 30) 
 

BODY MODIFIERS

 
move_rightleft (from -6 to 6), move_forwardback (from -10 to 6), move_updown (from -10 to 2), 
body_rightleft (from -30 to 30), chest_rightleft (from -30 to 30), head_forwardback (from -0.2 to 0.2), gesture_updown (from -1 to 1), gesture_rightleft (from -1 to 1) 
 

Notes

 
These modifiers are global for human characters in Black Mesa. You may need to experiment with them to get your specific end-goal. 
 
 

Specific Model Groups

 
Now that we’ve cleared everything else up, we can do the last, and arguably most important, step: defining what models to put on our characters! If you keep one blank, the engine will randomly select something for it, unless it’s a very specific item. 
 

CAFETERIA WORKER, MALE

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: haircap; 1: none; 2: construction helmet w/ muffs; 3: helmet w/o muffs 
• glasses (see “Global” Character Attributes) 
• chest: 0: apron; 1: bulletproof vest; 2: vest and radio; 3: tie; 4: none 
• flashlight: 0: none; 1: flashlight 
• syringe: 0: none; 1: syringe

CAFETERIA WORKER, FEMALE

 
MODEL PATHS:

BODYGROUP MODELS: 

• apron: 0: black apron; 1: no papron 
• glasses 
• hair: 0: haircap; 1: ponytail; 2: bun-ponytail; 3: free, long; 4: bowlcut; 5: middle-length, free; 6:
• bun: 7: skin-only hair (no additional models) 
• syringe: 0: none; 1: syringe

JANITOR

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: marine cap; 1: helmet w/ muffs: 2: helmet w/o muffs; 3: none 
• vest: 0: none; 1: reflective vest 
• glasses

CONSTRUCTION WORKER

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: construction helmet w/ muffs; 1: none; 2: construction helmet 
• vest: 0: none; 1: reflective vest 
• glasses 
• syringe: 0: none; 1: syringe

ENGINEER

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: construction helmet w/ muffs; 1: none; 2: construction helmet 
• vest: 0: none; 1: reflective vest 
• glasses 
• syringe: 0: none; 1: syringe

MALE SECURITY GUARD(S)

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: normal; 1: none; 2: visor down; 3: visor up; 4: marine cap; 5: marine cap #2 
• chest: 0: tie; 1: vest; 2: vest and radio; 3: none 
• glasses 
• holster: 0: none; 1: full holster; 2: empty holster 
• flashlight: 0: none; 1: flashlight

FEMALE SECURITY GUARD

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: guard helm with middle-length hair; 1: guard helm with long hair; 2: cap with hairbun; 3: cap with ponytail; 4: ponytail; 5: bun-ponytail; 6: free, long; 7: bowlcut; 8: middle-length, free; 9: bun; 10: skin-only hair 
• glasses 
• chest: 0: no vest; 1: vest; 2: vest and radio 
• holster: 0: none; 1: full holster; 2: empty holster

OTIS SECURITY GUARD

 
MODEL PATH: models/humans/guard_otis.mdl 
BODYGROUP MODELS: 

• helmet: 0: normal; 1: none; 2: visor down; 3: visor up; 4: marine cap; 5: marine cap #2 
• glasses 
• holster: 0: none; 1: filled; 2: empty 
• flashlight: 0: none; 1: flashlight

SCIENTISTS

 
MODEL PATHS:

BODYGROUP MODELS: 

• glasses 
• helmet: 0: none; 1: constr. helmet w/ muffs; 2: construction helmet 
• syringe: 0: none; 1: syringe

NON-LABCOATED (CASUAL) SCIENTISTS

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: none; 1: construction helmet w/ muffs; 2: construction helmet w/o muffs; 3: guard helmet 
• glasses 
• chest: 0: tie; 1: guard vest; 2: guard vest + radio; 3: reflective vest; 4: none 
• flashlight: 0: none; 1: flashlight 
• syringe: 0: none; 1: syringe

“CLEANSUIT”/HAZMAT SCIENTIST

 
MODEL PATHS:

BODYGROUP MODELS: 

• glasses 
• syringe: 0: none; 1: a med syringe

FEMALE SCIENTIST

 
MODEL PATH: models/humans/scientist_female.mdl 
BODYGROUP MODELS: 

• body: 0: clean; 1: bloody (hurt) 
• hair: 0: ponytail; 1: bun-ponytail; 2: free, long; 3: bowlcut; 4: middle-length, free; 5: bun; 6: skin-only hair (no additional models) 
• glasses 
• syringe: 0: none; 1: syringe

DR. ARNE MAGNUSSON

 
MODEL PATH: models/humans/scientist_magnusson.mdl 
 

OFFICE WORKER

 
MODEL PATHS:

BODYGROUP MODELS: 

• helmet: 0: None; 1: Helmet W/ Muffs; 2: Helmet W/O Muffs 
• chest: 0: Tie; 1: Guard Vest; 2: Guard Vest + Radio; 3: Reflective Vest; 4: None 
• flashlight: 0: None; 1: A flashlight 
• glasses 
• syringe: 0: none; 1: a med syringe

Tying the Metaphorical Bow

 
Now, you know the body groups, flex groups and skins that you need to start off running. Here’s an example character_manifest entry that I made: 

This makes the following: 
 
Save this in your mod’s scripts directory as character_manifest.txt, and don’t forget to pack it in your .VPK as well. Finally – Happy Manifest-ing! 
 
 

Help

Packaging yourcharacter_manifestfor use in-testing and in-publication

 
So, you’ve put your entry into a copy of the default character manifest, and now you want to use it. Make sure that your entry is at the *end* of the file, after the last entry but before the LAST closing curly bracket. Here’s my full example: 

1. Make sure your entry/entries are not outside of the last bracket, or they will not work. 
2. Place your new file (still named character_manifest.txt) into a folder with your mod’s name, inside of your <library>/Black Mesa/bms/custom directory. 
3. In your new folder, make a single folder named scripts and move the file there. 
4. Open a second Windows Explorer instance and find the <library>/Black Mesa/bin folder. The vpk.exe program is what you’ll want. 
5. Navigate back into your custom directory, and then drag your new folder atop of the vpk.exe in the other window. This will then package scripts/character_manifest.txt into a new .VPK file. 
6. Rename that for your mod, and then move it into your original bms/custom folder. Then, it should be ready to use! (Assuming that your gameinfo.txt searches the custom folder)

Some Solutions

• How do I use BM:CE? Follow these valvedev.info – https://steamcommunity.com/sharedfiles/filedetails/?id=2068862348, GCFscape; or, alternatively, the Crowbar tool. This will allow you to extract things from existing .VPKs, such as the original BMS ones, or one from BM:CE Misc that contains pre-existing character manifests! 
• Bodygroups aren’t appearing. Why? This could be for a variety of reasons; one being a conflicting mod, a typo in your manifest file, a malformed entry in your manifest file, or BM:CE not being installed correctly. 
• Why do we have to package our manifest? Unlike materials, scripts must be specifically packaged and placed in the bms directory to work. Anyways, this is also the process you must do (albeit, with your models/, materials/, sound/ and maps/ folders too) to publish your mod. 
• Doing this broke existing characters! Did you copy the original manifest and add yours to it, or did you overwrite other entries? 
• This is complex. I know; but making mods for an engine last maintained in 2005 is bound to be. 
• Everything else is right, but I don’t want a set skin/bodygroup. That’s fine; you can omit the entry for that, and the engine will randomize it. 
• Everything else is right, but the skin isn’t! Similar to above; you either omitted the skin entry in your entry, or you may of chosen the wrong one.

Hope you enjoy the Guide about Black Mesa – How to use Character Expansion (and character_manifest!), if you think we should add extra information or forget something, please let us know via comment below, and we will do our best to fix or update as soon as possible!