How to use Black Mesa: Character Expansion (and character_manifest !)

Overview

A complete, detailed but unofficial guide to using Black Mesa: Character Expansion in a mod/map, complete with examples for a character_manifest.txt file.

Preface

This guide is specifically for the character models in Black Mesa: Character Expansion mod, and is an unofficial contribution to help other developers use the pack! This assumes you’ve followed the installation guide for properly using it, and now want to define custom characters with it – with or without the knowledge of creating a character manifest.

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.

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

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

• Cafeteria Workers, male and female
• Janitors
• Construction Workers
• Engineers
• Improved Security Guards
• OTIS[half-life.fandom.com] our lord and overweight savior
• Female Security Guard
• Improved Scientists
• Casual (no labcoat) Scientists
• Hazmat (Cleansuit[half-life.fandom.com]) Scientists
• Doctor Magnusson[half-life.fandom.com], retconned
• Office Workers

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, Widow’s Peak[en.wikipedia.org]
• 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 Agent Colson from the M.C.U.[en.wikipedia.org])

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.

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 Flex Animation or in the Choreography Pages 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.

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

right_inner_raiser, left_inner_raiser, right_outer_raiser, left_out_raiser, right_lowerer, left_lowerer

right_cheek_raiser, left_cheek_raiser, wrinkler, dialator

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

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

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

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)

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)

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.

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

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

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

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

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

MODEL PATHS:

BODYGROUP MODELS:

• helmet: 0: normal; 1: none; 2: visor down; 3: visor up; 4: Hat, with Microphone; 5: Hat
• 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

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

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

MODEL PATHS:

BODYGROUP MODELS:

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

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

MODEL PATHS:

BODYGROUP MODELS:

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

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

MODEL PATH: models/humans/scientist_magnusson.mdl

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:
Another one I have creates this tired-looking engineer:
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

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)

• How do I use BM:CE? Follow these instructions.
• Can I edit VPK files? Yes, with one of Nem’s Tools[valvedev.info], GCFscape; or, for decompiling VPKs and other Source engine files, 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.
• Other characters are working, but my custom one isn’t. I had this too; you need to make sure your VPK is in the bms/custom directory, that your manifest is correctly formatted, and that your bms/gameinfo.txt searches the custom directory – you should’ve done this when setting up BM:CE.
• 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.

Finally: It has come to my attention that various bot-moderated websites (including the page here![steamlists.com]) have copied this as their own. If you’re reading this outside of the official Steam community, please report it, as I have not authorized any external sites to outright copy this guide at all.