Template:Archived Page History/Cubemaps/en

Exaggerated specular reflections on props

A cubemap is a texture that represents a three-dimensional rendering of an area. The Source Engine uses env_cubemap entities as sampling points to generate these textures, which are then automatically embedded into the map file. Cubemaps, when built, are reflected on surfaces that use the $envmap parameter (with env_cubemap as its value). If a map does not have any env_cubemap entities present, the game will instead use a generic texture that does not reflect the map.

Building cubemaps

Building cubemaps is the process of generating their textures to then use them as reflections. For technical reasons, this process is not automated and is up to the user to do so; until then, existing env_cubemap entities will remain unused and the map, depending on the game, will display either generic or "missing" textures as reflections due to nonexistent cubemaps.

Warning:For people with epilepsy: building cubemaps on games running on Vulkan, like Left 4 Dead 2, causes the screen to violently flash black and white.

Warning:To build cubemaps, your game's screen resolution needs to be at least 4 times higher than the highest size of an existing env_cubemap, or else attempting to build them will either fail or even cause the game to crash. For example, if the highest env_cubemap sizes 128x128, a resolution no smaller than 512x512 will be needed. (128 × 4 = 512 -> 720x576 (as a valid resolution) or higher)

Note:The game may appear to freeze or become unresponsive during the cubemap-building process, and the length of said process depends on various factors. For successful results, don't switch away from the game until it's done.

Tip:The buildcubemaps command optionally accepts the number of iterations to perform. For example, buildcubemaps 2 will build cubemaps twice. This is useful when recursive reflections are needed to look correct, e.g. two buildings reflecting each other.

Bug:This command doesn't currently work in Portal 2: Community Edition.

Workaround:Run the buildcubemaps command, reload the map, then run the command again.

  [todo tested in ?]

Warning:If the Nav_Show_Ladder_Bounds command was used before building cubemaps, the green boxes will also be baked into the cubemap.

Before building

Tip:Maps for Source 2013 games and others, such as Counter-Strike: Source, are known to include pre-built, blank cubemaps after being compiled (even if there are no env_cubemap entities in them). It is recommended to first delete these cubemaps before building new ones, as detailed here.

Tip:Maxing out the game's visual settings before building cubemaps will generate their textures in the best-possible quality for the env_cubemaps' size.

LDR

Note:This step does not apply to Left 4 Dead nor Counter-Strike: Global Offensive as their maps are compiled in HDR mode only.

Building cubemaps in a map compiled in LDR (Low Dynamic Range) mode will generate textures only for that mode, regardless of your game's High Dynamic Range video setting. To build the cubemaps, submit the following commands into the game's console:

Command	Description
mat_specular 0	Turns reflections Off; required to properly build cubemaps
map map_name	Loads a map; replace "map_name" with the map's actual name
sv_cheats 1	Enables the use of cheat commands; required to build cubemaps
buildcubemaps	Begins building cubemaps. Optionally, specify the number of iterations (e.g.: buildcubemaps 2 (default is 1))
disconnect	Unloads the map, returning to the main menu
mat_specular 1	Turns reflections On
quit	(optional) Exits the game. Relaunching it is required to display newly-built cubemaps

HDR

Building cubemaps in a map compiled with HDR support needs to be performed twice - once for each mode (HDR and LDR). As opposed to an LDR map's case, your game's High Dynamic Range video setting has to be set to "Full" to build HDR cubemaps, and to "None" to build LDR ones. To build the cubemaps, submit the following commands into the game's console:

Command	Description
mat_specular 0	Turns reflections Off; required to properly build cubemaps
map map_name	Loads a map; replace "map_name" with the map's actual name
sv_cheats 1	Enables the use of cheat commands; required to build cubemaps
buildcubemaps	Begins building cubemaps. Optionally, specify the number of iterations (e.g.: buildcubemaps 2 (default is 1))
disconnect	Unloads the map, returning to the main menu
sv_cheats 0	Disables cheat commands; prevents command mat_reloadallmaterials from unnecessarily self-executing, which briefly freezes the game
mat_hdr_level 0	Switches to LDR mode (from HDR); submit mat_hdr_level 2 instead if LDR cubemaps were built first
map map_name	Loads the map again to build cubemaps for the new mode
sv_cheats 1
buildcubemaps	Begins building cubemaps for the new mode
disconnect
mat_specular 1	Turns reflections On
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) Exits the game. Relaunching it is required to display newly-built cubemaps

Required procedure for specific games

Black Mesa: Source

To build cubemaps in Black Mesa: Source maps, the game has to be launched with these parameters: -oldgameui -dev -console +r_4way_use_fast_normals 0 +mat_specular 0
Then, submit the buildcubemaps command into the console.

Half-Life: Source

Bug:Building cubemaps in Half-Life: Source is currently not possible as their textures, despite being generated, aren't embedded into the map file afterward.

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

  [todo tested in ?]

Portal 2

Bug:Building cubemaps in Portal 2 will fail if the BSP is not in the highest-numbered DLC folder (dlc2 by default).

Workaround:Either manually move the map there first, edit the "Place compiled maps in this directory before running the game" option in the Build Programs options tab to do so automatically, or create a portal2_dlc3 folder, create a maps folder in that folder, and put all your custom maps in there.

  [todo tested in ?]

Source Filmmaker

Improper rendering of an HDR cubemap's face in Source Filmmaker.

Bug:HDR cubemaps sizing lower than 64x64 built in Team Fortress 2 and some other games usually display graphical artifacts on reflections due to the last face of each cubemap not rendering properly in Source Filmmaker. While rebuilding cubemaps in it would normally fix the issue, it is currently not possible to do so as Source Filmmaker generates blank textures.  [todo tested in ?]

Workaround:If recompiling a special version of an affected map with env_cubemaps now sizing 64x64 (or higher) is not an option, move the map file into Alien Swarm's "maps" folder, build its cubemaps in that game, then move the file back into Source Filmmaker's folder.

Note:Alien Swarm's "gameinfo.txt" file needs to be modified for this procedure so that the game can have access to assets used by other games' maps not to build cubemaps with missing textures or models. The file's "SearchPaths" section should look like this:

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

Note:Team Fortress 2 configurations were used for the example; consider replacing game subfolders (only those within Source Filmmaker paths) with the ones needed.

Workaround:Another option is to manually remove the sphere map (face #7) from the existing HDR cubemap textures. See Creating a custom static cubemap texture for more info.
Alternatively, deleting the affected HDR cubemap texture files will cause the LDR versions to be used, which do not suffer from this bug.

Deleting cubemaps

Several tools make it possible to delete unnecessary or outdated cubemaps; BSPZIP is one official, command-line tool which is usually the preferred option for this procedure, allowing for an usage unlikely of corrupting the map due to misuse. To delete cubemaps, execute the following command within the maps folder:

..\..\bin\bspzip -deletecubemaps map_name.bsp

Note:Replace "map_name" with the map's actual name.

Warning:Deleting cubemaps actually deletes all the texture (".vtf") files currently embedded into the map, so it's recommended not to embed custom textures before deleting cubemaps.

Extracting cubemaps

In cases where a map has to be recompiled with minor changes (and its built cubemaps vanish as a result), extracting them beforehand will make it not necessary to go through the whole cubemap-building process again. To extract cubemaps with BSPZIP, create a folder that will contain the extracted cubemaps inside the maps one, then execute the following command:

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

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

Embedding cubemaps

For BSPZIP to make a map use extracted cubemaps, create a text file inside the maps folder. The file's content should look like this:

materials/maps/map_name/c-128_384_64.hdr.vtf
foldername\materials\maps\map_name\c-128_384_64.hdr.vtf
materials/maps/map_name/c-128_384_64.vtf
foldername\materials\maps\map_name\c-128_384_64.vtf
materials/maps/map_name/c448_-256_64.hdr.vtf
foldername\materials\maps\map_name\c448_-256_64.hdr.vtf
materials/maps/map_name/c448_-256_64.vtf
foldername\materials\maps\map_name\c448_-256_64.vtf
materials/maps/map_name/cubemapdefault.vtf
foldername\materials\maps\map_name\cubemapdefault.vtf

Note:Replace "map_name" with the map's actual name, the cubemaps' filenames with correct ones, and "foldername" with the actual name of the folder that contains the extracted cubemaps.

A file requires two dedicated lines (paths): the first line represents the path it will use within the map file, whereas the second one is the actual location of the file to embed into the map file. Relative location paths were used for the example, but they can also be Absolute. Once the text file is ready, execute the following command:

..\..\bin\bspzip -addlist map_name.bsp textfile.txt newmap_name.bsp

Note:Replace "map_name" with the map's actual name, "textfile" with the text file's actual name, and "newmap_name" with either the map's actual name, or a new name not to overwrite the original file (and instead create a separate one).

Renaming a map

For built cubemaps to work, they must be located in a folder that is named after the map; this folder is automatically created within the map file during the building process. Renaming the map file will not also rename the folder within it, and therefore cubemaps will not be accessed. Some third-party apps allow renaming the folder, though it is not advisable to do so as it may corrupt the file. Instead, either delete and then rebuild the cubemaps, or revert the map to its original name.

See also

• env_cubemap
• $envmap
• parallax_obb - For Parallax Corrected Cubemaps.