Workshop docsHelp & reference
Reference
Every file path, console command and link from these guides on one page, for when you know what you're doing and just need the detail.
File paths
All paths are relative to the root of your VPK, or to Black Mesa/ for loose files.
| Path | What it is |
|---|---|
maps/ | A compiled map. |
maps/ | The map's AI nodegraph. Generated on first load; ship it. |
maps/ | Multiplayer map info: display name, player count, loading images. |
materials/ | Multiplayer loading images: a .vtf and .vmt named <map>_<id> (4:3), <map>_<id>_widescreen (16:9) and <map>_<id>_widescreen_16_10 (16:10) for each camera. |
campaigns/ | A campaign, listed on the Campaigns tab of the main menu's Add-ons section. |
campaigns/ | The official campaign. Standalone mods only. |
scripts/ | Which maps belong to which chapter. Standalone mods only. |
resource/ | Localization tokens (UTF-16 LE). Standalone mods only. |
ui/ | The main menu's code. Standalone mods only. |
bms/ | Drop VPKs or folders here to test them. Scanned at startup. |
steamapps/ | Where Steam puts subscribed Workshop items. |
Tools
In steamapps/:
| Tool | Use |
|---|---|
hammer.exe | Level editor. Needs bms.fgd under Game Data files. |
vpk.exe <folder> | Pack a folder into <folder>.vpk. |
vpk.exe -M -c <MB> <folder> | Pack into a multi-part VPK (_dir.vpk plus _000.vpk, _001.vpk, …). |
blackmesa_publish.exe | Upload and update Workshop items. |
bspzip.exe | Pack files into a .bsp. |
hlmv.exe | View models. |
Campaign file fields
| Field | Required | Notes |
|---|---|---|
title | Yes | Plain text. #TOKEN only in standalone mods. |
imageSource | Yes | image://, PNG or JPG. |
chapters | Yes | One entry per chapter. A single entry starts the map directly. |
chapters[].title | Yes | Shown on the chapter card and loading screen. |
chapters[].imageSource | Yes | Also the loading screen for the chapter's maps. 1280×720 or larger. |
chapters[].levelName | Yes | The .bsp name without extension. |
author, url, description | No | Not shown in the menu. |
Console commands
| Command | Use |
|---|---|
map <name> | Load a map. |
maxplayers <n> | Set the player limit before loading a multiplayer map. |
sv_cheats 1 | Allow cheat commands (needed for many below). |
buildcubemaps | Build cubemaps (run mat_specular 0 first, mat_specular 1 after). |
bm_generate_menu_images | Capture multiplayer loading images from each info_observer_menu. |
mat_motion_blur_enabled 0 | Turn off motion blur (before capturing images). |
cl_drawhud 0 | Hide the HUD (for screenshots). |
noclip, god, impulse 101 | Fly, invulnerability, all weapons. |
developer 1 | Show developer messages on screen. |
Launch options
| Option | Use |
|---|---|
-dev -console | Developer messages, and the console at startup. |
-game <folder> | Run a standalone mod. |
-oldgameui | The old VGUI menu (unsupported). Needed when building cubemaps. |
Black Mesa-specific entities
| Entity | Use |
|---|---|
info_observer_menu | Camera for a multiplayer loading image. observerid 0, 1, 2… |
info_player_deathmatch | Deathmatch spawn. |
info_player_marine, info_player_scientist | Team Deathmatch spawns. |
item_weapon_*, item_ammo_* | Pickups. Hard Respawn flag for fixed-schedule respawns. |
newLight_Point, newLight_Spot, newLight_Dir | Real-time deferred lights. |
The VDC keeps a full list of Black Mesa entities.
Further reading
- Black Mesa level design: the Valve Developer Community's index of Black Mesa pages.
- Official Black Mesa map sources: the VMFs for the game's own maps.
- Black Mesa Qt UI documentation: the main menu's code and API, for standalone mods.
- Black Mesa's new lights: the deferred lighting system.
- VPKEdit: browse and extract the game's VPK files.
- Original Black Mesa Workshop guide (PDF, 2016): the guide these pages replace. Parts of it are out of date.
- Black Mesa Workshop and the Crowbar Collective Discord.