Building and compiling a map

This page assumes you can already build a basic room in Hammer. If you can't, work through the Valve Developer Community's Your First Map series first. It's written for Half-Life 2, but nearly everything carries over. Then come back here for the parts that are different in Black Mesa.

Before you start

Pick a name now. Map names are hard to change later, because campaign files, loading screens, level transitions and nodegraphs all refer to them.

• Use lowercase, no spaces, and a prefix that's yours: ap_storage_01, not Storage Map.
• Black Mesa itself uses bm_ for singleplayer and dm_ for multiplayer maps. You can follow that convention, but don't start a singleplayer map name with bm_c. The official campaign uses that prefix, and the menu groups maps by their first four letters when it picks a loading screen image.
• If your campaign has several maps, number them in play order (ap_01_lobby, ap_02_vault) so they also sort alphabetically in that order.

Keep your VMFs outside the game folder, e.g. in C:\bms-mapsrc\. Game updates and file verification can delete things you leave in the install folder.

Spawning the player

A singleplayer player spawns with nothing. Give them the HEV suit (item_suit) and any weapons as entities in the map, or with a game_player_equip, if you want them armed from the start.

Compiling

Press F9 (File → Run Map) to compile.

• Normal mode is fine while you're building. Set VIS and RAD to Fast for quick iteration.
• Expert mode lets you pass extra parameters to the compilers. Use it for your final builds, because Black Mesa's lighting looks noticeably better with the right VRAD settings.

Final compile settings

These are the VRAD (lighting) parameters the official Black Mesa maps were compiled with. Choose the line that matches your map:

In Hammer's expert compile, add -game $gamedir $path\$file at the end of the line, as the default commands do. If you'd rather not set up expert compiles by hand, HTCT has a Black Mesa preset that does it for you.

Lighting

Black Mesa has two kinds of light:

• Baked lights (light, light_spot, light_environment) are computed by VRAD when you compile, exactly as in other Source games.
• New lights (newLight_Point, newLight_Spot, newLight_Dir) are real-time deferred lights with dynamic shadows and light cookies. They were added in the Xen update and are used throughout the official maps.

Most official maps use baked lighting for the overall light and new lights for the parts that move, flicker or need sharp shadows. The VDC page on Black Mesa's new lights explains every setting. The in-game New Lights Editor lets you tune them live.

Cubemaps

Cubemaps give shiny surfaces (floors, metal, glass, water) their reflections. Without them, reflective materials show a generic image that looks wrong in almost any room.

1. Place env_cubemap entities in each distinct area, about head height, away from walls.

2. Compile the map.

3. Launch the game with these launch options: -oldgameui -dev -console +r_4way_use_fast_normals 0

4. Load your map from the console: map yourmapname

5. Run these console commands:

   Copy

   mat_specular 0
   buildcubemaps
   mat_specular 1

6. Quit, and remove the extra launch options.

The cubemaps are saved into the .bsp itself.

Nodegraphs (maps with NPCs)

NPCs find their way around using info_node entities you place in Hammer. The first time the map loads, the game turns them into a nodegraph and saves it as maps/graphs/<mapname>.ain.

• After your final compile, load the map once so the nodegraph is rebuilt, then include maps/graphs/<mapname>.ain in what you ship. Otherwise every player's game has to rebuild it, which makes their first load slower.
• If NPCs stand still or walk into walls after you've changed the layout, the nodegraph is out of date. Delete the .ain and load the map again.

Testing

Hammer copies the compiled map into bms/maps/. In the game console:

map yourmapname

Useful while testing (some need sv_cheats 1):

Once the map plays well, read Loading screens and Creating a campaign before you pack it. They're the two steps people most often miss.