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.

IMPORTANT: Files designed with this guide should be done for mods with dedicated "launchers", i.e, those with separate executable directories (like Blue Shift and Damocles), as the file which any changes are made to will be loaded in place of the default Black Mesa character_manifest file! Even if you keep its contents, your mod will likely conflict with others also using a custom manifest unless you use a separate launcher. That's just how Source works, I'm afraid.

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. If you're looking for Black Mesa's default one, you'll need to unpack it from first, and then place it into your mod's folder at the position defined earlier.

---

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."

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, messy white hair (no longer Agent Coulson :( )

---

Male Group _02 (thanks to Joanai for going through these ones!)
• 0 - White, Bald
  
• 1 - Black, Receding hairline (Remains the same)
  
• 2 - White, Squared hair (Remains the same)
  
• 3 - Black, Bald (Remains the same)
  
• 4 - White, Goatee, Squared hair (Remains the same)
  
• 5 - Black, Squared hair (Originally 13th skin)
  
• 6 - White, Goatee, Balding tan hair (Originally 5th skin)
  
• 7 - Latino, Slicked hair (Originally 6th skin, last time I got this guy's race wrong, he's not Black, he's Latino)
  
• 8 - White, Window peak hair
  
• 9 - White, Messy hair (Originally 8th skin)
  
• 10 - Latino, Straight hairline (Originally 7th skin)
  
• 11 - Latino, Brown straight hairline w/ Mustache (Remains the same)
  
• 12 - White, Blonde smooth hair
  
• 13 - Latino, Squared hair
  
• 14 - Black, Bald

---

Male Group _03 (thanks to Joanai for updating these ones!)

• 0 - White, Balding brown hair w/ Mustache
  
• 1 - White, Squared hair w/ Mustache
  
• 2 - White, Balding hair w/ Goatee
  
• 3 - White, Thick eyebrow, Uneven hair
  
• 4 - White, Trimmed beard, Widow's peak
  
• 5 - White, Balding white hair w/ Tan mustache
  
• 6 - White, Dark squared hair
  
• 7 - Black, receeding Hairline with mustache (Originally 3rd skin)
  
• 8 - White, Squared brown hair (Kind of looks like Magnusson)
  
• 9 - White, Balding hair (Looks like Kevin from the Office)
  
• 10 - White, Straight gray hairline
  
• 11 - White, Balding hair w/ Mustache (Bob King from 2008 Black Mesa)

---

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 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. [/b] 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.

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:

• head 0: nothing, 1: helmet, 2: gasmask (don't you dare), 3: shades
  
• cigar 0: none, 1: cigar
  
• gloves 0: none, 1: tacti-cool gloves
  
• helmet_medic 0: none, 1: med's helmet - don't use with the head:1 helmet!
  
• holster 0: none, 1: sidearm holster
  
• packs_chest 0: none, 1: chest packs
  
• packs_hips 0: none, 1: waist-area packs
  
• packs_thigh 0: none, 1: thigh packs

MODEL PATHS: BODYGROUP MODELS:

• head 0: nothing, 1: helmet, 2: gasmask, 3: shades
  
• gloves 0: none, 1: tacti-cool gloves
  
• gasmask_nv 0: none, 1: helmet, gasmask + NV (don't use with another)
  
• holster 0: none, 1: sidearm holster
  
• packs_chest 0: none, 1: chest packs
  
• packs_hips 0: none, 1: waist-area packs
  
• packs_thigh 0: none, 1: thigh packs

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 PATH: 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

MODEL PATH: models/humans/fem_office_worker.mdl
This model shares the Female Scientist bodygroups, and also has 36 skins for different outfits.

MODEL PATHS: I have not decompiled this new model to determine its bodygroups. It does, however, sport 31 skins for the different male characters (previously split in groups _01 to _03).

MODEL PATHS: BODYGROUP MODELS:

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

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.

Update
We need to retain the original BM:CE file in our manifest files, or else every character in the game will appear as defaults! Instead of creating a new file, I now recommend putting your custom ones at the top of a copy from the BM:CE manifest, so that the original game has unique characters, and so your mod can too. Unless, of course, you're talented enough (unlike myself) to create a full launcher for your mod, like in Azure Sheep or DAMOCLES.

A copy of such a file, of which is a basic one I'm using currently, is available here (pastebin)[pastebin.com] if you want to modify it. Most of it is a mix between BM:CE and the newest edition of HECU marine entries, but my mod's portion is at the top.

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 directory, such as bms\bm__xenatek_pack
   
3. In your new folder, make a single folder named scripts and move the file there. If you're using custom models and stuff as well, make sure to package those into your base mod directory as well (models + materials directories).
   
4. Open a second Windows Explorer instance and find the <library>\Black Mesa\bin folder. The vpk.exe program is what you'll want, as it is what packages folders into .VPKs.
   
5. Navigate back into your bms directory, and then drag your new folder atop of the vpk.exe in the other window. This will then package your entire mod folder into a new .VPK file.
   
6. Rename that for your mod if needed, 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 browse 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\custom directory to work.
  
• 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, if not be default.
  
• 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.
  
• I want it to randomize from certain optoins! That's easy! Simply delimit a short list for each value, like skin 0,1,2,3,4,5 or glasses 0,2,3,4,6 and the engine will select one from that list to use.
  
• 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.
  
• I want to make my mod have a dedicated BMS launcher, like Damocles! This would be incredibly helpful, yes - you could trim out the entirety of the BM:CE part of the character manifest, and instead have all custom for your mod (along with aesthetic and portability bonuses). However, I lack the knowledge to do this, so you'll have to ask people who have done it how (or if there's a guide, use that).
  
• I can't seem to spawn in my NPC! Make sure the NPC has the exact same name as the title you specified in the character manifest (i.e. in my example, the NPC for "Doctor Bob" must have a name of doctor_bob, same as in the manifest).