Making a standalone mod

Do you need one?

Most projects don't. A Workshop add-on (a VPK the game mounts on top of Black Mesa) can add maps, campaigns, models, materials and sounds, and it's one click for players to install.

You need a standalone mod (your own folder with its own gameinfo.txt, launched with -game) when you have to change things an add-on mustn't touch:

• replacing the New Game campaign rather than adding to the Workshop list,
• your own chapter list and unlocks (scripts/chapter_manifest.txt),
• your own menu: colours, layout, hidden multiplayer tabs,
• your own localization files, so #TOKEN titles work,
• changing game scripts, configs or sound manifests without affecting the base game.

The cost: players have to install it by hand and launch it separately, and it doesn't appear in Black Mesa's menu.

1. Create the folder

Make a folder for your mod inside the Black Mesa install folder, next to bms, with a short lowercase name and no spaces:

steamapps/common/Black Mesa/
├── bin/
├── bms/
└── mymod/          ← your mod
    ├── campaigns/
    ├── cfg/
    ├── maps/
    ├── mapsrc/
    ├── resource/
    ├── scripts/
    └── ui/

2. Write gameinfo.txt

mymod/gameinfo.txt tells the engine what your mod is called and where to look for files. This version is based on Black Mesa's own. Replace mymod and the names:

"GameInfo"
{
	game			"My Mod"
	developer		"Your Name"
	developer_url	"https://example.com"
	type			"singleplayer_only"	// or "both" if you keep multiplayer
	gamelogo		1
	nomodels		1
	nocrosshair		1
	nodifficulty	0
	GameData		"bms.fgd"
	InstancePath	"mymod/mapsrc/"

	hidden_maps
	{
	}

	FileSystem
	{
		SteamAppId	362890
		ToolsAppId	211

		SearchPaths
		{
			// Add-ons dropped into mymod/custom/ (VPKs or folders), scanned at startup.
			game+mod								mymod/custom/*

			// Your mod's own files. Listed before Black Mesa's, so yours win.
			game+mod+mod_write+default_write_path	|gameinfo_path|.
			gamebin									|gameinfo_path|bin

			// Black Mesa's content.
			game+mod		bms/bms_textures.vpk
			game+mod		bms/bms_materials.vpk
			game+mod		bms/bms_models.vpk
			game+mod		bms/bms_misc.vpk
			game+mod		bms/bms_sounds_misc.vpk
			game+mod		bms/bms_sound_vo_english.vpk
			game+mod		bms/bms_maps.vpk

			// Black Mesa's game code. The mod crashes on launch without this.
			gamebin			|all_source_engine_paths|bms/bin
			game			bms

			// Half-Life 2 and shared engine content.
			game			|all_source_engine_paths|hl2/hl2_misc.vpk
			game			|all_source_engine_paths|hl2/hl2_sounds_misc.vpk
			game			|all_source_engine_paths|hl2/hl2_textures.vpk
			game			|all_source_engine_paths|hl2/hl2_materials.vpk
			game			|all_source_engine_paths|hl2/hl2_models.vpk
			platform		|all_source_engine_paths|platform/platform_misc.vpk
			game			hl2
			game			|all_source_engine_paths|hl2
			platform		|all_source_engine_paths|platform
		}
	}
}

3. Copy the files the mod can't run without

Some files are only looked for in the mod's own folder, so copy them from Black Mesa. Open bms/bms_misc_dir.vpk with VPKEdit and extract:

Without the .res files, parts of the interface break. Without dynlightscript.txt, dynamic light effects such as fire and battery glows are missing.

4. Set up the campaign

A standalone mod owns its menu, so its campaign goes in campaigns/blackmesa.json, the file the New Game page reads. It's the one place this name is correct. The format is the same as any campaign file.

Then give the engine your chapter list in scripts/chapter_manifest.txt. Each line is a map name (or the start of one) and the chapter it belongs to:

"chapter_manifest.txt"
{
  mymod_01 1    // every map starting "mymod_01" is chapter 1
  mymod_02 2
  mymod_03 2    // several maps can share a chapter
  mymod_04 3
}

5. Localization (optional)

To use #TOKEN titles (and translate your mod), create resource/mymod_english.txt, where the part before _english matches your mod's folder name:

"lang"
{
	"Language"	"English"
	"Tokens"
	{
		"MYMOD_CampaignName"	"My Mod"
		"MYMOD_Chapter1_Title"	"Arrival"
		"MYMOD_Chapter2_Title"	"Underground"
	}
}

Then use "title": "#MYMOD_Chapter1_Title" in blackmesa.json.

6. Make it launchable

Players launch the mod by starting Black Mesa with -game mymod. Give them a launcher in your mod folder.

Windows: mymod/play_mymod.bat:

@echo off
start "" "%~dp0..\bms.exe" -game mymod %*

Linux: mymod/play_mymod.sh:

#!/bin/sh -e
steam -applaunch 362890 -game mymod "$@"

Players can also add -game mymod to Black Mesa's Launch options in Steam, as long as they remove it again to play the base game.

7. Change the menu (optional)

Black Mesa's menu is built in Qt (QML), and the files are plain text in bms_misc_dir.vpk under ui/themes/default/. To change a file, extract it to the same path in your mod folder and edit it there. Common changes for a total conversion:

• Accent colour. Change the highlight colour in theme.qml.
• Hide the Workshop, Achievements and Multiplayer tabs. Remove their entries from component-header.qml.
• Weapon key bindings for weapons your mod doesn't have: remove them from component-binding-weapons.qml.

A syntax error in any QML file stops the whole menu from appearing, so change one thing at a time and keep backups. The Valve Developer Community's Black Mesa Qt pages document the menu's code and the API it uses. If you just want the old menu, players can launch with -oldgameui, but it's unsupported.

Distributing it

A standalone mod isn't installed by subscribing; it has to end up as a folder next to bms. Most mods are distributed as a download (e.g. on ModDB), with instructions to extract it into the Black Mesa folder.

If you do use the Workshop, remember the game also mounts subscribed items as add-ons. Test that subscribing on its own doesn't change the base game, and give players clear install steps on the item's page.