Loading screens

When a level loads from the menu, Black Mesa covers the screen with an image of where the player is going. For multiplayer maps, it also shows the map's name and a gameplay tip, then fades from the image into the live map at the same spot.

If your level doesn't provide an image, none of that happens. The loading screen keeps whatever it was last showing (usually the main menu background) or goes black. It's one of the most common things missing from Workshop maps, and it's easy to fix.

Where the image comes from

The game looks in two places, in this order:

1. maps/<mapname>.txt. If this file exists and lists images, one of them is picked at random. This is the multiplayer system, but it works for any map.
2. Your campaign file. Otherwise, the game finds the chapter the map belongs to in campaigns/*.json and shows that chapter's image (imageSource).

Singleplayer: chapter images

Once your campaign file gives each chapter an imageSource, that image becomes the loading screen for:

• the chapter's first map, when the player starts the chapter from the menu, and
• every later map in the same chapter, when the player loads a save made there.

The game works out which chapter a map is in from its name, so map names matter. A map gets the image of the chapter that starts with it, or failing that, of the closest chapter whose first map shares its first four letters and sorts before it alphabetically. How maps are matched to chapters explains it with examples.

Multiplayer: info_observer_menu images

Multiplayer maps get the full treatment: several images, picked at random, each taken from a camera you place in the map. When loading finishes, the player starts looking from that same camera, so the image fades seamlessly into the real map.

1. Place the cameras

In Hammer, add an info_observer_menu entity for each image you want. Black Mesa's own maps use three.

• Aim each one at something worth showing off: the map's landmark areas, not a corridor.
• Give each one a unique ID (observerid), counting up from 0 with no gaps: 0, 1, 2.

2. Get the map ready

Compile the map as you'll ship it: final compile settings, and cubemaps built. The images capture whatever's on screen, so wrong reflections end up in your loading screen.

3. Generate the images

1. Launch the game and start a multiplayer game on your map. In the main menu, choose Multiplayer → Host, start any map, then open the console and run map yourmapname.

2. Turn off motion blur, or the images will be smeared:

   Copy

   mat_motion_blur_enabled 0

3. Enable cheats and start the capture:

   Copy

   sv_cheats 1
   bm_generate_menu_images

4. Don't touch anything while it runs. The view jumps between your cameras and saves one image from each, taking a few seconds per camera. Moving the mouse, typing or closing the console can ruin the shots, for example by making entities disappear from them.

5. Wait for the console to print Done! It will also say the server is now "crippled". That's expected; quit to the menu.

It's normal for the view to point the wrong way while capturing. It doesn't affect the saved images.

4. Repeat for each screen shape

Each run only captures images for your current aspect ratio. Black Mesa picks a version to suit the player's screen, so generate all three. Change the resolution, restart the game, and run bm_generate_menu_images again:

They're saved in bms/materials/vgui/multiplayer/map_backgrounds/. With three cameras that's 18 files (9 .vtf + 9 .vmt). Open a few of the .vtf files in VTFEdit or VPKEdit to check they came out right. Occasionally a capture fails and needs another run.

5. Write the map's info file

This file connects the images to your map and gives it a proper name. Create it in maps/, named exactly like your .bsp:

"dm_mymap"
{
	// The map's display name, shown while it loads.
	"name"		"MY MAP"

	// A recommendation, not a limit: how many players it plays best with.
	"players"	"4 - 12 PLAYERS"

	// One per camera. The number is the info_observer_menu ID.
	// Paths are relative to materials/vgui/ with no extension or ratio suffix:
	// the game adds _widescreen or _widescreen_16_10 itself.
	"Images"
	{
		"0"	"multiplayer/map_backgrounds/dm_mymap_0"
		"1"	"multiplayer/map_backgrounds/dm_mymap_1"
		"2"	"multiplayer/map_backgrounds/dm_mymap_2"
	}

	// Picked to match the image (description "1" goes with image "1").
	"Descriptions"
	{
		"0"	"A flooded pumping station under Sector C."
		"1"	"A flooded pumping station under Sector C."
		"2"	"A flooded pumping station under Sector C."
	}
}

• The first line must be the map's file name.
• Keep the name and descriptions short. Long text can overlap other parts of the loading screen.
• The Images numbers must match your camera IDs. That's how the game puts the player at the right spot after the fade.

6. Ship all of it

Your Workshop item needs the .bsp, the .txt and every generated .vtf and .vmt:

dm_mymap/
├── maps/
│   ├── dm_mymap.bsp
│   └── dm_mymap.txt
└── materials/
    └── vgui/
        └── multiplayer/
            └── map_backgrounds/
                ├── dm_mymap_0.vmt
                ├── dm_mymap_0.vtf
                ├── dm_mymap_0_widescreen.vmt
                ├── dm_mymap_0_widescreen.vtf
                ├── dm_mymap_0_widescreen_16_10.vmt
                ├── dm_mymap_0_widescreen_16_10.vtf
                └── … the same six for cameras 1 and 2

If you're putting the map on a dedicated server rather than the Workshop, pack the .txt and images into the .bsp with bspzip (or a tool like Compile Pal or VIDE), so joining players download a single file.

Checking it worked

• Restart the game after adding the files. If you add the .txt while the game is running, you may see a purple-and-black checkerboard instead of your image until you restart.
• Start the map from the menu (singleplayer) or host it (multiplayer) and watch the loading screen.
• Still wrong? See loading screen problems in Troubleshooting.