Making a Black Mesa Mod

This article or section needs to be cleaned up to conform to a higher standard of quality because:
improve formatting with {{{path}} and Software templates, links
Separate the manual into Linux and Windows parts, or indicate which steps may be the same/different
Can be worded better... (rewrite sections)
For help, see the VDC Editing Help and Wikipedia cleanup process. Also, remember to check for any notes left by the tagger at this article's talk page.

This article or section should be converted to third person to conform to wiki standards.

← Black Mesa Level Creation

Skill Level This tutorial expects you to have this amount of knowledge within the topic to follow along smoothly.
Novice	Familiar	Competent	Proficient	Expert

This article will discuss the creation of a Black mesa mod

Creating a mod

Head to the local variation of C:\Program Files (x86)\Steam\steamapps\common\Black Mesa then create a folder with the mod's name, and modders can name it anything they want. Examples like: "MyMod"

Setting up the files

Navigate into the directory and create the following folders and subfolders:

resource
scripts
mapsrc
mapsrc/instances
campaigns
ui

Note:Use a program like

VPKEdit to extract the files from VPK

Now open bms_misk_dir.vpk located in Black Mesa/bms/

Take the following files:

resource 
|-- clientscheme.res
|-- gamemenu.res

Add these files in the same directories as the mod, for example: MyMod/resource/...

Also take dynlightscript.txt located in Black Mesa/bms/cfg/

Warning: These files are essential for the mod, if you do not have .res files, UI will break, and dynlightscript.txt is needed for dynamic light effects like fire and battery props

Setting up the chapters

Create a scripts/chapter_manifest.txt inside the newly created scripts folder It should be something like this: Edit it to replace with the map names / the number of chapters that exist

"chapter_manifest.txt"
{
  yourmapname_a 1 // the 1 at the end means it's part of chapter 1
  yourmapname_b 2 // the 2 at the end means it's part of chapter 2 
  yourmapname_c 2 // Multiple maps can share same chapter
}

Next up create a blackmesa.json file inside myfirstmod/campaigns/, it can be modified to perfection.

{
{
    "author": "mod author", 
    "url": "",
    "title": "#key",
    "description": "",
    "imageSource": "image://game/ui/campaign/images/logo.jpg",
    "chapters": [
        {
            "title": "#key",
            "description": "",
            "imageSource": "yourpathtoimage", 
            "levelName": "yourmapname"
        },
        {
            "title": "#key",
            "description": "",
            "imageSource": "yourpathtoimage", 
            "levelName": "yourmapname"
        },
        {
            "title": "#key",
            "description": "",
            "imageSource": "yourpathtoimage", 
            "levelName": "yourmapname"
        }
    ]
}
}

Note:The imageSource path is relative to the ui/images folder of the mod and example would be "image://game/ui/campaign/images/chapter1.png"

Make sure to replace each #key in the file with the corresponding one in the corresponding localization file (See the next step)

Setting up the text for chapters

Create a myfirstmod_english.txt in myfirstmod/resource/ It should look something like this, modify it to perfection

"lang"
{ 
	"Language"	"English" 
	"Tokens" 
	{ 

// CHAPTER TITLE CARDS

		"MYFIRSTMOD_CampaignName_BMSCP1"						"CAMPAIGN" // Title, see blackmesa.json for more info
		"MYFIRSTMOD_Chapter1_Title"							"The First Chapter"
		"MYFIRSTMOD_Chapter2_Title"							"The Second Chapter"
		"MYFIRSTMOD_Chapter3_Title"							"CREDITS"
	} 
}

Warning:This file must be saved in a Unicode format.

Note:For windows save as UTF-16 LE In Notepad, under Save As..., this is equivalent to choosing unicode for the Encoding option at the bottom of the dialog.

Creating the gameinfo.txt file

Now modders will need to create the gameinfo file inside the main folder. Use the following one as a template and modify it to perfection:

"GameInfo"
{
	game			"myfirstmod"
	gamelogo 		1
	developer		"Developer Name"
	developer_url	"http://www.blackmesasource.com/"
	type			"both"
	gamelogo 		1
	SupportsDX8     0
	SupportsXbox360 1
	nomodels		1
	nocrosshair		1
	GameData 		"bms.fgd"
	InstancePath	"myfirstmod/mapsrc/instances/" 
	
	hidden_maps
	{
       
	}

	FileSystem
	{
		SteamAppId 362890
		ToolsAppId 211

		//
		// Search paths are relative to the base directory, which is where hl2.exe is found.
		//
		// |gameinfo_path| points at the directory where gameinfo.txt is.
		// We always want to mount that directory relative to gameinfo.txt, so
		// people can mount stuff in c:\mymod, and the main game resources are in
		// someplace like c:\program files\valve\steam\steamapps\half-life 2.
		//
		SearchPaths
		{
			// First, mount all user customizations.  This will search for VPKs and subfolders
			// and mount them in alphabetical order.  The easiest way to distribute a mod is to
			// pack up the custom content into a VPK.  To "install" a mod, just drop it in this
			// folder.
			//
			// Note that this folder is scanned only when the game is booted.
			game+mod								myfirstmod/custom/*
			
                        game+mod                                                                myfirstmod
			// Black Mesa VPK files.
			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

			// HL2 VPK files.
			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 VPK files.
			platform  								|all_source_engine_paths|platform/platform_misc.vpk


			// Now search loose files.  We'll set the directory containing the gameinfo.txt file
			// as the first "mod" search path (after any user customizations).  This is also the one
			// that's used when writing to the "mod" path.
			game+mod+mod_write+default_write_path	|gameinfo_path|.
			gamebin		
							|gameinfo_path|bin

                        // Load the BMS DLL files, mod will crash without this!
			gamebin	"|all_source_engine_paths|bms/bin" 
			
			// Add the HL2 directory as a game search path.  This is also where where writes
			// to the "game" path go.
			game									hl2

			// Last, mount in shared HL2 loose files
			game									|all_source_engine_paths|hl2
			platform								|all_source_engine_paths|platform
		}
	}
}

Creating the BAT file

Create a file, call it something like myfirstmod.bat This is so Windows users can launch the mod.

@echo off
if exist "%~dp0\bms.exe" (
start "" "%~dp0\bms.exe" -game myfirstmod %*
) else (
start "" "%~dp0\..\..\..\..\common\Black Mesa\bms.exe" -game myfirstmod %*
)

Also create one for the people who want to launch with oldgameui:

@echo off
if exist "%~dp0\bms.exe" (
    start "" "%~dp0\bms.exe" -game myfirstmod -oldgameui %*
) else (
    start "" "%~dp0\..\..\..\..\common\Black Mesa\bms.exe" -game myfirstmod -oldgameui %*
)

Creating the SH file

Create a file, call it something like myfirstmod.sh This is so Linux users can launch the mod.

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

Also create one for the people who want to launch with oldgameui:

#!/bin/sh -e
steam -applaunch 362890 -game myfirstmod -oldgameui $@

Final polish

This should be just enough to get the mod working, the modders will need to add things like sound manifests, models etc aswell.

modders could customize the UI further, for example by changing the colors or the actual layout by editing the .qml inside ui/ of bms_misc_dir.vpk