Cubemaps

Specular reflections.

Many reflective materials must be combined with external data so that the Source engine can correctly generate their appearance. This data is stored as a cubemap, a texture which represents a three-dimensional rendering of an area. The Source engine uses env_cubemap entities as sampling points for generating these textures, and saves the cubemaps inside each map's BSP file. While processing specular and environment-mapped materials, it utilizes them to more accurately generate environments. In other words, a cubemap creates the textures that a reflective surface will be reflecting.

Note:Half-Life: Source, Portal 2 and Team Fortress 2 have issues with building cubemaps. Their bugs are listed here.

Building Cubemaps

Once a map has been compiled and lit by VBSP and VRAD (respectively), the cubemaps can be built. After the map is finished loading, use the buildcubemaps console command to begin building the cubemaps for the level. Here you’ll be able to see each facet of the cubemap (six per cubemap) render and this can take seconds or minutes to complete depending on your system configuration. Once finished, the map or the game must be restarted for the cubemaps to properly be applied to all surfaces.

Note:Set mat_specular to 0 before running buildcubemaps or it will result in improper reflections!

Note:Built cubemaps are saved in the BSP file the game loaded, which is in the maps folder, not the location where the BSP file was built.

Note:If you intend to change the name of your bsp and build its cubemaps, you must buildcubemaps before renaming and packing the bsp.

Note:If your map has big reflective surfaces facing each other (e.g skyscrapers), it is recommended to buildcubemaps twice, so your reflective surfaces in the reflections will also have reflections from the first build.

HDR

If the map has been compiled with the HDR lighting option enabled in VRAD, cubemaps must be built in both HDR and LDR (non-HDR) modes. Building cubemaps in only one mode will mean that cubemaps will not be present the other mode. For information on how to build cubemaps under HDR, see HDR Lighting Basics.

Cubemaps should be built for LDR and HDR maps. Presuming you are already in HDR mode and have your map loaded fresh from compilation (VRAD must have the -both parameter enabled). Go to the console and execute the following commands:

buildcubemaps
mat_hdr_level 0 (to go to LDR)
restart (to reload map)
buildcubemaps
mat_hdr_level 2 (to go back to HDR)
restart (to reload map)

Note:This does not apply to CS:GO as HDR cannot be turned off.

Team Fortress 2 / Source 2012+ Games

Team Fortress 2 does not have a default cubemap applied to reflective surfaces. (There are also similar problems with some installations of Portal 2, except cubemaps will simply not appear.) Everything shiny will shine with a pink and black checkered texture. If you were to build cubemaps now and one of your cubemap is able to see a large shiny surface; the cubemap will register that in its 6 images. That means some objects might shine as if there was something shining next to it with the pink and black texture. To solve this, you need to build the cubemaps with specular turned off. To build cubemaps for your TF2 map, go to the console and execute the following commands:

Building Cubemaps for LDR or HDR only:

Note:Do not enable sv_cheats before loading the map; it will automatically execute mat_reloadallmaterials right after the map has loaded and will cause the next menu to freeze for a moment.

Note:It is recommended to set mat_specular to 0 before loading a map, so it takes much less time to complete than doing so while/after a map has loaded.

mat_specular 0
map <your map>
sv_cheats 1
buildcubemaps
disconnect
sv_cheats 0

Building cubemaps for HDR requires you to repeat these steps after loading your map while HDR is enabled.

Note:If the game crashes when you try to build cubemaps, this probably means your game resolution is set too low. Before you try to build cubemaps you must ensure your game width and height are over 512 pixels. This means that the minimal standard resolution to build is 800×600. The video resolution can be changed from the Video tab, found under the game Options menu.

Note:If the map BSP file is renamed after the cubemaps have been built the cubemaps will no longer work and default to the sky cubemap. You must rebuild cubemaps again each time a map is renamed. However, the no-longer-working cubemaps are not removed, so this can lead to bloated files. If you plan to release a map so that others can download it, it is best to try to avoid any map-renaming after you compile it, to avoid problems.

Note:For multiplayer maps in some games, you may need to enable cheats (sv_cheats 1) before running buildcubemaps.

After SteamPipe Update

Due to the SteamPipe update, a recognised problem might be building the cubemaps with no effective results. This problem can be fixed by the following steps: †

Bug:  In Counter-Strike Global Offensive, editing your map file directly like this can have adverse side effects including node graph glitches and losing static_prop shadow data. This method can prevent that.

1. Place env_cubemap entities in valid locations in your map, and compile. Important: Name has to be shorter than 30 characters (including the .bsp extension), or the BSP won't be writeable. Also, don't change the map name after compiling, or the cubemaps won't work.
2. Use your favorite BSP pakfile editor (e. g. VIDE or Pakrat. Usage of these tools isn't included in this tutorial.), and load your BSP file.
3. Delete all files that are a "Texture" or "Texture (HDR)" type. (Not "Material" files, only the VTF's!)
4. Save the edited BSP file.
5. Copy your map back to your game's maps folder.
6. Open console and type: map <mapname>. (e. g. map ttt_mars_colony_cubemap)
7. Once in-game, open the console again and type mat_specular 0 and buildcubemaps.
8. Wait until completion, and then re-enable specular mapping with mat_specular 1 and reload your materials with mat_reloadallmaterials.

Note:If you want to pack custom content with your map, do it after building cubemaps.

† According to this thread

Source Filmmaker

Building cubemaps in Source Filmmaker is currently broken and will only render a single face of a single cubemap. To build cubemaps for Source Filmmaker maps correctly, copy the map file and assets used by the map (textures, models, etc) to Alien Swarm. As the engine branch version is very similar, there is no need to recompile separate maps or models; copying the files should suffice. Load up your map in Alien Swarm and input the buildcubemaps command into the console. After the faces are rendered, your map will now contain cubemaps and can be copied back over to Source Filmmaker. This will only work with the newer map branch version, as maps from Team Fortress 2 or Garry's Mod will crash the game upon loading.

Additional 'no-copy' version to hammer and build is using an additional mod configuration in Alien Swarm with 'alien' (relative) search pathes to the content of sfm. todo: absolute pathes.

Example for the 'common' location:

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

Portal 2

When you want to build cubemaps for a map lying in Portal 2/portal2/maps (Hammer copies the maps to there by default) Portal 2 will crash because it expect that the map can be found under the highest DLC folder (DLC2 by default). To fix the crash, just copy your map into Portal 2/portal2_dlc2/maps (or whatever the highest DLC folder is), reload it and build cubemaps again. It should work now.

Left 4 Dead 1/2

To build cubemaps in Left 4 Dead 2 the shader settings must be set to medium. If you change the shader settings while a map is loaded you may need to reload the map as sometimes overlays end up with broken lighting, making them appear unlit. Once the cubemaps for one map are built you must restart the game to test them. Sometimes you must restart the game to build cubemaps on a second map aswell.

Half-Life: Source

Building cubemaps in Half-Life: Source is not possible for now, since it will generate but not add the cubemaps into the map (it will copy the TGA files into the materialsrc folder, but the game will not convert them into VTF towards the materials folder, and from there adding them into the pakfile).

The only solution passes by copying the map and assets/mount the content to another game of the same branch (like HL2), building the cubemaps there and then copying the BSP. It shouldn't be needed to recompile the map.

Testing

Cubemaps are best tested by using the impulse 81 console command. To do this; type in impulse 81 in the Console. Then, type give weapon_cubemap.

Note: You can bind these two commands to separate keys so don't have to type this in every time.

This replaces the current weapon model with the "cubemap weapon"; a set of spheres, each with different reflective surfaces. By moving around the level it is possible to see what cubemap is being applied at that position in space at any given time, as well as if that cubemap accurately describes the area’s lighting and color.

Note:The cubemap weapon can be copied from Steam\SteamApps\common\Half-Life 2\hl2\models\shadertest\envballs.mdl to a desired mod which doesn't have it.

Note:If you run a recompiled copy of the same map without restarting the game, the cubemaps from the previous version will still be cached, making it appear as if cubemaps do not need to be rebuilt. These cubemaps are not in the map, however, as running the map again on another computer or after restarting the game will reveal. Every new compile wipes out all packed content, including cubemaps.

Performance

The env_cubemap entity allows the user to define how large the target cubemap’s texture resolution is. While a larger texture resolution will provide more accurate and “sharp” results when sampled, it also incurs a cost in texture memory. Most cubemaps should only use the default setting in the env_cubemap entity for their texture resolution (32x32 pixels for each surface). This is generally acceptable in normal conditions. Some exceptions may be necessary for areas of high reflectivity or detail, such as set-pieces for acting.

Because surfaces must approximate their surroundings via cubemaps, using too many cubemaps in a small area can cause noticeable visual discontinuities when moving around. For areas of high reflectivity, it is generally more correct to place one cubemap in the center of the surface and no more. This avoids seams or popping as the view changes.

To determine the cost of cubemaps in any one area, first look at the World Rendering category using the +showbudget console command. If this category is registering an unusually high cost, it may be due to using too many cubemaps in an area. A simple solution to check for this scenario is to use Hammer to Hide all the cubemaps in the map, and then compile and run the map again. If the performance is noticeably better, cubemap density or resolution may need to be reduced. Eventually this can also be checked by turning off cubemaps, by using mat_specular 0 to disable it, however this needs confirmation.

Bugs

Note:For some games (L4D/L4D2) a complete game restart is required after building the cubemaps in order to enable them.

Bug: In Team Fortress 2 VBSP fails to load the skybox to use it as the default cubemap, so all reflective surfaces will show the missing content texture, which resembles a pink and black checkerboard. To fix this you will need to build cubemaps manually.

Bug: Building cubemaps in Portal 2 will crash the game if the map you are running is in the default common/portal 2/portal2/maps folder. This crash happens when the map is being reloaded, after the cubemaps have been saved to the file. To prevent the crash, set the 'Place compiled maps' option in the Build Programs tab of Hammer options to 'common/portal 2/portal2_dlc2/maps', then recompile the map before compiling the cubemaps.

Bug: Some models require built cubemaps to look correct. Without them, they may end up looking super shiny and even glowing. Building cubemaps with such broken models will build those broken model materials into your cubemap. In those cases you may need to either build the cubemaps twice or lower your shader detail to a lower level where cubemaps will not be used, eliminating the broken texture bug for those few models

See Also

• env_cubemap
• $envmap