Difference between revisions of "Cubemaps"

From Valve Developer Community
Jump to: navigation, search
(Explain why there are no default cubemaps)
(Building cubemaps: added note tor games running on vulkan)
 
(17 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{otherlang2
+
{{lang|Cubemaps}}
|fr=Cubemaps:fr
+
[[Image:Env_cubemap.png|left]]
|ru=Cubemaps:ru
+
[[Image:Specular.jpg|thumb|right|300px|Specular reflections on props.]]
}}
+
A '''cubemap''' is a texture that represents a three-dimensional rendering of an area. The [[Source|Source Engine]] uses [[env_cubemap]] entities as sampling points to generate these textures, which are then automatically embedded into the [[BSP|map file]]. Cubemaps, when [[#Building cubemaps|built]], are reflected on surfaces that use the [[$envmap]] parameter (with ''env_cubemap'' as its value).
[[Image:Env_cubemap.png|left]][[Image:Specular.jpg|thumb|350px|right|Specular reflections.]]
 
Many reflective [[material]]s 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|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|[[Portal 2]] and [[Team Fortress 2]] have issues with building cubemaps. Their bugs are listed [[#Bugs|here]] }}
 
{{note|[[Counter-Strike: Global Offensive]] must be launched with the -insecure flag in order to build cubemaps. }}
 
  
 +
== 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_cubemaps''' will remain unused and the map, depending on the game, will display either generic or "missing" textures as reflections due to nonexistent cubemaps.
 +
{{warning|To build cubemaps, your game's screen resolution needs to be at least 4 times higher than the highest [[env cubemap#Keyvalues|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 of 512x512 will be needed. (''128 × 4 = '''512''' -> 720x576 or higher'')}}
 +
{{note|Newly-built cubemaps will display after relaunching the game.}}
 +
{{tip|Maxing out the game's visual settings before building cubemaps will generate their textures in the best-possible quality for the '''env_cubemaps'''<nowiki>'</nowiki> size.}}
 +
{{note|Its possible the game may appear to freeze during building of cubemaps. But it keeps on building cubemaps in the background. Be patient and do not close the game, or unfocus the game (Alt-Tabbing) as it may cause the game to crash. }}
 +
{{warning|Games running on Vulkan, like {{l4d2}} will not pause the screen during building cubemaps, but the screen will violently flash black and white. But you must not alt tab out of this process to stop the flashing. If you are prone to epileptic seizures you should either look away or walk away from the computer.}}
 +
=== Before building ===
 +
{{tip|Maps for {{css}}'''Counter-Strike: Source''' and some other games are known for including pre-built, blank cubemaps after being compiled (even if there are no '''env_cubemaps''' in them). It is recommended to delete these cubemaps before building new ones, as explained [[#Deleting cubemaps|here]].}}
  
==Building Cubemaps==
 
Once a map has been compiled and lit by [[Vbsp|VBSP]] and [[Vrad|VRAD]] (respectively), the cubemaps can be built. After the map is finished loading; use the <code>buildcubemaps</code> [[Developer_Console|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 <code>mat_specular</code> to 0 before running <code>buildcubemaps</code> or it will result in improper reflections!}}  
+
=== LDR ===
 +
{{note|This step does not apply to {{csgo}}'''Counter-Strike: Global Offensive''' as its maps are compiled in [[#HDR|HDR mode]] only.}}
 +
Building cubemaps on 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:
 +
{| class="wikitable"
 +
|-
 +
! Command !! Description
 +
|-
 +
| <code>mat_specular 0</code> || Disables reflections. Required to properly build cubemaps
 +
|-
 +
| <code>map ''cs_mymap''</code> || Loads a map; replace "''cs_mymap''" with the map's actual name
 +
|-
 +
| <code>sv_cheats 1</code> || Enables the use of cheat commands. Required to build cubemaps
 +
|-
 +
| <code>buildcubemaps</code> || Starts building cubemaps
 +
|-
 +
| <code>disconnect</code> || Unloads the map, returning you to the main menu
 +
|-
 +
| <code>mat_specular 1</code> || Enables reflections
 +
|-
 +
| <code>quit</code> || (optional) Closes the game. Relaunching it is required to display newly-built cubemaps
 +
|}
  
{{note|Built cubemaps are saved in the bsp file the game loaded, which will be 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.}}
+
=== HDR ===
 +
Building cubemaps on a map compiled with [[HDR]] support needs to be done twice - once for each mode ('''HDR''' and '''LDR'''). As opposed to a '''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:
 +
{| class="wikitable"
 +
|-
 +
! Command !! Description
 +
|-
 +
| <code>mat_specular 0</code> || Disables reflections. Required to properly build cubemaps
 +
|-
 +
| <code>map ''cs_mymap''</code> || Loads a map; replace "''cs_mymap''" with the map's actual name
 +
|-
 +
| <code>sv_cheats 1</code> || Enables the use of cheat commands. Required to build cubemaps
 +
|-
 +
| <code>buildcubemaps</code> || Starts building cubemaps
 +
|-
 +
| <code>disconnect</code> || Unloads the map, returning you to the main menu
 +
|-
 +
| <code>sv_cheats 0</code> || Disables cheat commands. Prevents command <code>''mat_reloadallmaterials''</code> from unnecessarily self-executing and briefly freezing the game
 +
|-
 +
| <code>mat_hdr_level 0</code> || Switches to '''LDR''' mode (from '''HDR'''); submit <code>''mat_hdr_level 2''</code> instead if '''LDR''' cubemaps were built first
 +
|-
 +
| <code>map ''cs_mymap''</code> || Loads the map again to build cubemaps for the new mode
 +
|-
 +
| <code>sv_cheats 1</code> ||
 +
|-
 +
| <code>buildcubemaps</code> || Starts building cubemaps for the new mode
 +
|-
 +
| <code>disconnect</code> ||
 +
|-
 +
| <code>mat_specular 1</code> || Enables reflections
 +
|-
 +
| <code>mat_hdr_level ''0/1/2''</code> || If necessary, switches back to the mode it was before having submitted <code>''mat_hdr_level 0/2''</code>
 +
|-
 +
| <code>quit</code> || (optional) Closes the game. Relaunching it is required to display newly-built cubemaps
 +
|}
  
{{note|If your map has big reflective surfaces facing each other (e.g skyscrapers), it is recommended to <code>buildcubemaps</code>  twice, so your reflective surfaces in the reflections will also have reflections from the first build.}}
 
  
===HDR===
+
=== Half-Life: Source ===
 +
{{bug|Building cubemaps in {{hls}}'''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 {{hl2}}'''Half-Life 2'''), build its cubemaps in that game, then move the file back into '''Half-Life: Source'''<nowiki>'</nowiki>s folder.}}
  
If the map has been compiled with the [[HDR|HDR]] lighting option enabled in [[Vrad|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 '<code>-both</code>' parameter enabled). Go to the console and execute the following commands:
+
=== Source Filmmaker ===
 +
[[Image:Cubemap_bug_sfm.jpg|thumb|right|300px|Improper rendering of an HDR cubemap's face in Source Filmmaker.]]
 +
{{bug|'''HDR''' cubemaps sizing lower than 64x64 built in {{tf2}}'''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 {{sfm}}'''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.}}
 +
:{{workaround|If recompiling a special version of an affected map with '''env_cubemaps''' now sizing 64x64 is not an option, move the map file into {{as}}'''Alien Swarm'''<nowiki>'</nowiki>s "maps" folder, build its cubemaps in that game, then move the file back into '''Source Filmmaker'''<nowiki>'</nowiki>s folder.}}
 +
::{{note|'''Alien Swarm'''<nowiki>'</nowiki>s "gameinfo.txt" file needs to be edited 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 be 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|{{tf2}}'''Team Fortress 2''' configurations were used for the example; consider replacing game subfolders (only those within '''Source Filmmaker''' paths) with the ones needed.}}
  
  buildcubemaps
+
== Deleting cubemaps ==
mat_hdr_level 0 ''(to go to LDR)''
+
Several tools make it possible to delete unnecessary or outdated cubemaps; of them all, [[BSPZIP]] not only is an official one, but is also the easiest and safest option for this procedure without potentially corrupting the map. To delete the cubemaps, execute the following command within the "maps" folder:
restart ''(to reload map)''
+
  ..\..\bin\bspzip -deletecubemaps mapname.bsp
  buildcubemaps
+
{{note|Replace "''mapname''" with the map's actual name.}}
mat_hdr_level 2 ''(to go back to HDR)''
+
{{warning|Deleting cubemaps actually deletes all the texture ("[[Valve Texture Format|.vtf]]") files embedded into the map at the time, so it's recommended not to embed custom textures before deleting cubemaps.}}
restart ''(to reload map)''
+
== 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 until it actually becomes so. To extract its cubemaps with '''BSPZIP''', create a folder that will contain the extracted cubemaps inside the "maps" one, then execute the following command:
 +
  ..\..\bin\bspzip -extractcubemaps mapname.bsp "foldername"
 +
{{note|Replace "''mapname''" with the map's actual name, and "''foldername''" with the actual name of the folder to extract cubemaps into.}}
  
{{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 <code>sv_cheats</code> before loading the map; it will automatically execute <code>mat_reloadallmaterials</code> right after the map has loaded and will cause the next menu to freeze for a moment.}}
 
{{note|It is recommended to set <code>mat_specular</code> 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 800X600. 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 (<code>sv_cheats 1</code>) before running the <code>buildcubemaps</code> command.}}
 
 
===Cubemaps after SteamPipe Update===
 
Due to the SteamPipe update, a recognised problem might be building the cubemaps with no effective results. According to a [http://www.facepunch.com/showthread.php?t=1293081 thread], this problem can be fixed by following those steps:
 
{{bug|{{csgo}} 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.[https://steamcommunity.com/app/211/discussions/0/846959998155287479/ This] method can prevent that.}}
 
<code>
 
# Place env_cubemap entities in valid locations in your map, and compile. Important: Name has to shorter than 30 characters (including the .bsp extension), or the .bsp won't be writeable! Also, don't change the map name after compilling, or the cubemaps won't work!
 
# Use your favorite .bsp pakfile editor (For example, VIDE or Pakrat. Usage of these tools isn't included in this tutorial.), and load your .bsp.
 
# Delete all files that are a "Texture" or "Texture (HDR) type. (Not "Material" files, only the .vtf's!)
 
# Save the edited .bsp.
 
# Copy your map back to your game's maps folder.
 
# Open console and type: "map -mapname-". (In my case, "ttt_mars_colony_cubemap".)
 
# Once you're ingame, open the console again and type this: "mat_specular 0" and "buildcubemaps".
 
# Wait until the cubemaps are built, 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.}}
 
</code>
 
 
===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 [[TF2]] 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 "portal2_dlc2/maps". So if you want to fix the crash, just copy your map into "Portal 2/portal2_dlc2/maps" (or the maps folder of your custom mod) 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 [[UnlitGeneric|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.
 
 
== Testing ==
 
Cubemaps are best tested by using the <code>[[impulse]] 81</code> console command. To do this; type in <code>[[impulse]]</code> 81 in the Console. Then, type <code>[[give]]</code> weapon_cubemap.
 
 
{{note| You can bind these 2 commands to separate keys so don't have to type this in every time.}}
 
 
This replaces the current weapon model with the "[[weapon_cubemap|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 [[weapon_cubemap|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 <code>[[env_cubemap|env_cubemap]]</code> 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 <code>[[env_cubemap|env_cubemap]]</code> 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 <code>[[showbudget|+showbudget]]</code> 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 <code>mat_specular 0</code> to disable it, however this needs confirmation.
 
 
==Bugs==
 
{{note| For some games (L4D{{L4d}}/L4D2{{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 [[Hammer_Build_Programs|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 ==
 
  
 +
=== Embedding cubemaps ===
 +
To make a map use extracted cubemaps, create a text file that will be used by '''BSPZIP''' - the file should be created inside the "maps" folder, and will contain paths to the files to embed into the map file. The file's content should be like this:
 +
materials/maps/mapname/c-128_384_64.hdr.vtf
 +
'''foldername\materials\maps\mapname\c-128_384_64.hdr.vtf'''
 +
materials/maps/mapname/c-128_384_64.vtf
 +
'''foldername\materials\maps\mapname\c-128_384_64.vtf'''
 +
materials/maps/mapname/c448_-256_64.hdr.vtf
 +
'''foldername\materials\maps\mapname\c448_-256_64.hdr.vtf'''
 +
materials/maps/mapname/c448_-256_64.vtf
 +
'''foldername\materials\maps\mapname\c448_-256_64.vtf'''
 +
materials/maps/mapname/cubemapdefault.vtf
 +
'''foldername\materials\maps\mapname\cubemapdefault.vtf'''
 +
{{note|Replace "''mapname''" 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, while 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 mapname.bsp textfile.txt newmapname.bsp
 +
{{note|Replace "''mapname''" with the map's actual name, "''textfile''" with the text file's actual name, and "''newmapname''" 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 ==
 +
Built cubemaps are saved into a folder within the map file that uses its name; renaming it will cause the cubemaps not to load alongside the map, and therefore it will act as if there were none. To fix that, either delete then rebuild the cubemaps, or extract then embed them back (with their folder's name matching that of the map).
 +
== See also ==
 +
* [[env_cubemap]]
 
* [[$envmap]]
 
* [[$envmap]]
 
 
[[Category:Level Design]]
 
[[Category:Level Design]]

Latest revision as of 16:53, 14 September 2021

English Español Français Русский
Env cubemap.png
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).


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_cubemaps will remain unused and the map, depending on the game, will display either generic or "missing" textures as reflections due to nonexistent cubemaps.

Warning.png 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 of 512x512 will be needed. (128 × 4 = 512 -> 720x576 or higher)
Note.png Note: Newly-built cubemaps will display after relaunching the game.
Tip.png 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.
Note.png Note: Its possible the game may appear to freeze during building of cubemaps. But it keeps on building cubemaps in the background. Be patient and do not close the game, or unfocus the game (Alt-Tabbing) as it may cause the game to crash.
Warning.png Warning: Games running on Vulkan, like Left 4 Dead 2 will not pause the screen during building cubemaps, but the screen will violently flash black and white. But you must not alt tab out of this process to stop the flashing. If you are prone to epileptic seizures you should either look away or walk away from the computer.

Before building

Tip.png Tip: Maps for Counter-Strike: SourceCounter-Strike: Source and some other games are known for including pre-built, blank cubemaps after being compiled (even if there are no env_cubemaps in them). It is recommended to delete these cubemaps before building new ones, as explained here.


LDR

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

Building cubemaps on 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 Disables reflections. Required to properly build cubemaps
map cs_mymap Loads a map; replace "cs_mymap" with the map's actual name
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 reflections
quit (optional) Closes the game. Relaunching it is required to display newly-built cubemaps


HDR

Building cubemaps on a map compiled with HDR support needs to be done twice - once for each mode (HDR and LDR). As opposed to a 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 Disables reflections. Required to properly build cubemaps
map cs_mymap Loads a map; replace "cs_mymap" with the map's actual name
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
sv_cheats 0 Disables cheat commands. Prevents command mat_reloadallmaterials from unnecessarily self-executing and briefly freezing 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 cs_mymap 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 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. Relaunching it is required to display newly-built cubemaps


Half-Life: Source

Bug.png Bug: Building cubemaps in Half-Life: SourceHalf-Life: Source is currently not possible as their textures, despite being generated, aren't embedded into the map file afterward.
Placementtip.gif Workaround: Move the map file into the "maps" folder of a game of the same engine branch (such as Half-Life 2Half-Life 2), build its cubemaps in that game, then move the file back into Half-Life: Source's folder.


Source Filmmaker

Improper rendering of an HDR cubemap's face in Source Filmmaker.
Bug.png Bug: HDR cubemaps sizing lower than 64x64 built in Team Fortress 2Team 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 FilmmakerSource 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.
Placementtip.gif Workaround: If recompiling a special version of an affected map with env_cubemaps now sizing 64x64 is not an option, move the map file into Alien SwarmAlien Swarm's "maps" folder, build its cubemaps in that game, then move the file back into Source Filmmaker's folder.
Note.png Note: Alien Swarm's "gameinfo.txt" file needs to be edited 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 be 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.png Note: Team Fortress 2Team Fortress 2 configurations were used for the example; consider replacing game subfolders (only those within Source Filmmaker paths) with the ones needed.

Deleting cubemaps

Several tools make it possible to delete unnecessary or outdated cubemaps; of them all, BSPZIP not only is an official one, but is also the easiest and safest option for this procedure without potentially corrupting the map. To delete the cubemaps, execute the following command within the "maps" folder:

..\..\bin\bspzip -deletecubemaps mapname.bsp
Note.png Note: Replace "mapname" with the map's actual name.
Warning.png Warning: Deleting cubemaps actually deletes all the texture (".vtf") files embedded into the map at the time, 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 until it actually becomes so. To extract its cubemaps with BSPZIP, create a folder that will contain the extracted cubemaps inside the "maps" one, then execute the following command:

..\..\bin\bspzip -extractcubemaps mapname.bsp "foldername"
Note.png Note: Replace "mapname" with the map's actual name, and "foldername" with the actual name of the folder to extract cubemaps into.


Embedding cubemaps

To make a map use extracted cubemaps, create a text file that will be used by BSPZIP - the file should be created inside the "maps" folder, and will contain paths to the files to embed into the map file. The file's content should be like this:

materials/maps/mapname/c-128_384_64.hdr.vtf
foldername\materials\maps\mapname\c-128_384_64.hdr.vtf
materials/maps/mapname/c-128_384_64.vtf
foldername\materials\maps\mapname\c-128_384_64.vtf
materials/maps/mapname/c448_-256_64.hdr.vtf
foldername\materials\maps\mapname\c448_-256_64.hdr.vtf
materials/maps/mapname/c448_-256_64.vtf
foldername\materials\maps\mapname\c448_-256_64.vtf
materials/maps/mapname/cubemapdefault.vtf
foldername\materials\maps\mapname\cubemapdefault.vtf
Note.png Note: Replace "mapname" 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, while 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 mapname.bsp textfile.txt newmapname.bsp
Note.png Note: Replace "mapname" with the map's actual name, "textfile" with the text file's actual name, and "newmapname" 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

Built cubemaps are saved into a folder within the map file that uses its name; renaming it will cause the cubemaps not to load alongside the map, and therefore it will act as if there were none. To fix that, either delete then rebuild the cubemaps, or extract then embed them back (with their folder's name matching that of the map).

See also