Cubemaps

Models with specular reflections.

A cubemap is a texture that represents a three-dimensional rendering of an area. The Source Engine uses env_cubemaps as sampling points for generating these textures, which are then saved into the BSP file. Surfaces using the $envmap parameter with env_cubemap as its value will reflect the built cubemaps.

Building cubemaps

For technical reasons, env_cubemaps remain unused in compiled maps until built manually; until then, and depending on the game, the map will use either generic reflections, or a missing texture due to non-existent cubemaps.

Warning:Your game's resolution must be at least 4 times higher than the highest size of an env_cubemap in a map, or else attempting to build them will either fall or even cause the game to crash. For example: if an env_cubemap sizes 128x128, you'll need a resolution of at least 512x512 (128 × 4 = 512 -> 720x576 or higher).

Note:It's necessary to relaunch the game after building cubemaps in order to display them.

Tip:Maxing out your game's visual settings prior to building cubemaps will generate their textures in the best-possible quality (based on the env_cubemaps' size).

Before building

Counter-Strike: Source maps are among the known ones to include pre-built, blank cubemaps on compile; they're built even if there are no env_cubemaps in the map, and it is recommended to erase them first as explained here.

LDR

Note:This step does not apply to Counter-Strike: Global Offensive as its maps are compiled in HDR only.

A map compiled in LDR (Low Dynamic Range) will build only that mode's cubemaps, regardless of your game's current HDR (High Dynamic Range) setting. Submit the following commands into the game's console:

Command	Description
mat_specular 0	Disables specularity. Required to properly build cubemaps
map <the map's filename>	Loads the map (e.g., map cs_mymap)
sv_cheats 1	Enables the use of cheat commands. Required to build cubemaps
buildcubemaps	Starts building cubemaps
disconnect	Unloads the map, returning you to the main menu
mat_specular 1	Enables specularity. Required to see reflections
quit	(optional) Closes the game. Required to see reflections after building cubemaps

HDR

A map compiled with HDR support will need its cubemaps built twice; once for each mode (HDR and LDR). As opposed to a LDR map's case, your game's HDR setting must be set to "None" to build LDR cubemaps, and to "Full" to build HDR ones. Submit the following commands into the game's console:

Command	Description
mat_specular 0	Disables specularity. Required to properly build cubemaps
map <the map's filename>	Loads the map (e.g., map cs_mymap)
sv_cheats 1	Enables the use of cheat commands. Required to build cubemaps
buildcubemaps	Starts building cubemaps
sv_cheats 0	Disables cheat commands. Prevents command mat_reloadallmaterials from self-executing and briefly freezing the game unnecessarily
disconnect	Unloads the map, returning you to the main menu
mat_hdr_level 0	Switches to LDR mode (from HDR). Submit mat_hdr_level 2 instead if LDR cubemaps were built first
map <the map's filename>	Loads the map again to build cubemaps for the new mode
sv_cheats 1
buildcubemaps	Starts building cubemaps for the new mode
disconnect
mat_specular 1	Enables specularity. Required to see reflections
mat_hdr_level 0/1/2	If necessary, switches back to the mode it was before having submitted mat_hdr_level 0/2
quit	(optional) Closes the game. Required to see reflections after building cubemaps

Half-Life: Source

Bug:Cubemaps in Half-Life: Source don't currently build properly as their textures, despite being generated, aren't saved into the BSP file afterward.  [todo tested in ?]

Workaround:Move the BSP file into the "maps" folder of a game of the same engine branch (such as Half-Life 2), build the cubemaps in said game, then move the file back into Half-Life: Source's.

Source Filmmaker

Bug:Cubemaps in Source Filmmaker don't currently build properly as their textures are generated blankly.  [todo tested in ?]

Workaround:Move the BSP file into Alien Swarm's "maps" folder, build the cubemaps in that game, then move the file back into Source Filmmaker's.

Note:For this procedure, Alien Swarm's "gameinfo.txt" file will need to be edited to use assets from Source Filmmaker's mod directories not to build cubemaps with missing textures/models. The file's "SearchPath" section should look like this:

"SearchPaths"
{
	"Game"	"|gameinfo_path|."
	"Game"	"swarm_base"
	"Game"	"platform"
	"Game" "..\SourceFilmmaker\game\hl2"
	"Game" "..\SourceFilmmaker\game\tf"
	"Game" "..\SourceFilmmaker\game\tf_movies"
	"Game" "..\SourceFilmmaker\game\usermod"
}

Deleting cubemaps

Deleting cubemaps is useful to get rid of unnecessary or outdated ones and their associated files. Out of all other capable tools, BSPZIP is the safest way for doing so without potentially corrupting the map; from the "maps" folder where the BSP is located, execute the following command:

..\..\bin\bspzip -deletecubemaps mapname.bsp

Note:Replace "mapname" with the map's actual filename.

Warning:Cubemaps should be deleted before embedding texture (".vtf") files into the BSP file as this procedure actually deletes all the texture files in it.

Extracting cubemaps

In cases where a map needs to be updated (recompiled) with minor changes and its built cubemaps vanish as a result, extracting said cubemaps beforehand will make it not necessary to go through the whole cubemap-building process again until it actually becomes so. Create a folder that will contain the extracted cubemaps within the "maps" folder and execute the following command:

..\..\bin\bspzip -extractcubemaps mapname.bsp "foldername"

Note:Replace "mapname" with the map's actual filename, and "foldername" with the actual name of the folder to extract cubemaps into.

Embedding cubemaps

To make use of extracted cubemaps, create a text file that will include the directory structure to use within the BSP file and the path to the file(s) to embed with BSPZIP. Here's an example of "packlist_mymap.txt" (the text file can be named anyhow; its name will later be referenced in BSPZIP):

materials/maps/mapname/c0_416_64.hdr.vtf
foldername\materials\maps\mapname\c0_416_64.hdr.vtf
materials/maps/mapname/c0_416_64.vtf
foldername\materials\maps\mapname\c0_416_64.vtf
materials/maps/mapname/c416_0_64.hdr.vtf
foldername\materials\maps\mapname\c416_0_64.hdr.vtf
materials/maps/mapname/c-416_0_64.hdr.vtf
foldername\materials\maps\mapname\c-416_0_64.hdr.vtf
materials/maps/mapname/c416_0_64.vtf
foldername\materials\maps\mapname\c416_0_64.vtf
materials/maps/mapname/c-416_0_64.vtf
foldername\materials\maps\mapname\c-416_0_64.vtf
materials/maps/mapname/cubemapdefault.vtf
foldername\materials\maps\mapname\cubemapdefault.vtf

Note:Replace "mapname" with the map's actual filename, and "foldername" with the actual name of the folder that contains the extracted cubemaps.

Each file requires two dedicated lines (paths); the first line represents the structure of the directory that the file will use in the BSP file (always basing from the game's subfolder), while the second one is the actual location of the file to find and embed. The second line in this example used a relative path (considering that the text file is located inside the "maps" folder, alongside the folder that contains the cubemaps), but it can also be absolute. After the text file is created, execute the following command:

..\..\bin\bspzip -addlist mapname.bsp textfile.txt newmapname.bsp

Note:Replace "mapname" with the map's actual filename, "textfile" with the text file's actual filename, and "newmapname" with the map's actual filename to override it (or type in a different filename to generate an additional BSP file).

Renaming a map

Built cubemaps are saved into a directory within the BSP file, with the directory sharing its name; changing the name of the BSP will cause cubemaps not to load alongside the map, and therefore it will act as if there were none. To correct that, either delete then rebuild cubemaps, or extract then repack (embed) them with a matching map name in the cubemaps' directory.

See also

• env_cubemap
• $envmap