How the game finds your files

Black Mesa doesn't care where a file came from: the game folder, a VPK you made, or a Workshop item. It stacks all of them into one virtual file system and looks files up by their relative path, like materials/mymod/wall.vmt or maps/mymap.bsp.

That gives you the one rule that matters: put each file at the path the game expects, and it will be found. Your mod folder should mirror the layout of the game's own bms folder.

The folders you'll use

A finished singleplayer map with a few custom textures might look like this:

mymap/
├── campaigns/
│   └── mymap.json
├── maps/
│   ├── mymap.bsp
│   └── graphs/
│       └── mymap.ain
├── materials/
│   └── mymap/
│       ├── wall_panel.vmt
│       └── wall_panel.vtf
└── ui/
    └── mymap/
        ├── logo.png
        └── chapter1.png

Same path, same file: overrides

If two sources contain a file at the same path, only one of them is used, and content from add-ons and Workshop items wins over the base game. That's how weapon and model replacement mods work.

It's also how a map ends up breaking the game for everyone who subscribes to it. If your item ships a file at a path the game already uses, your version replaces the original for every map, not just yours.

The fix is simple: give your files their own folder. Put textures in materials/<yourname>/, models in models/<yourname>/, sounds in sound/<yourname>/, menu images in ui/<yourname>/, and give your campaign file a name nobody else will use.

Don't repack the game's own files

Don't start from a copy of one of Black Mesa's VPKs and upload it with your changes. Every file in it replaces the game's version for everyone who subscribes, including the ones you never touched, and those copies go out of date with every update.

Ship only the files you made. To replace something on purpose, like a weapon model, ship just those files. To change the game's text, menus or scripts, make a standalone mod.

Where to put files while you're testing

You don't need to pack anything to try your map. The game also reads loose files from its own folder:

• Black Mesa/bms/: loose files placed here (e.g. bms/maps/mymap.bsp) work straight away. This is where Hammer copies your map after compiling.
• Black Mesa/bms/custom/: any .vpk file or folder inside this is mounted at startup. Create the folder if it doesn't exist. It's the easiest way to test a packed VPK exactly as players will get it.

The game only looks for VPKs and Workshop items when it starts. Restart the game after adding or removing one.

Naming rules that save headaches

• Lowercase, no spaces. Use wall_panel_01.vmt, not Wall Panel 01.vmt. Source tools struggle with spaces, and file names can be case-sensitive on Linux.
• A unique prefix for everything. Short initials or a project tag (ap_, lrs_) on map names, folders and campaign files avoids clashes with the game and with other people's items.
• Never name a map after an official one. A map called bm_c1a0a.bsp replaces the start of the real campaign.

Glossary