View source for Cubemaps

{{LanguageBar}}
{{Tabs|Cubemaps|source=1|source2=1|main=source}}
[[File:Env_cubemap.png|left]]
[[File:Specular.jpg|thumb|right|300px|An example of specular reflections on some models (exaggerated through {{cmd|r_showenvcubemap}}).]]
A '''cubemap''' is a texture that represents a three-dimensional rendering of an area. {{source|4.1}} uses {{ent|env_cubemap}} entities as sampling points to generate these textures, which are then integrated into the [[BSP|map file]]. Cubemaps, when [[#Building cubemaps|built]], are reflected on materials that use the [[$envmap]] parameter (surfaces such as reflective glass, tiles, water, etc.) A map without built or existing '''env_cubemap''' entities will instead use other kinds of "reflections" (such as default cubemap texture, see below) that don't properly depict it, appear broken ([[Missing content|missing textures]], reflections appear bright, etc...), or simply doesn't show any reflections (if the cubemap texture is black).


==Building cubemaps==
[[File:Default_cubemap.png|192px|thumb|right|This default cubemap texture will appear if you skip building blank cubemaps during VBSP process.]]
'''Building cubemaps''' is the process of generating textures to use as reflections. For technical reasons, this process isn't automated {{mapbase|in|addtext-front=''Except''{{nbsp}}}} 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:
*Blank (black) texture (which basically make it look the same as {{code|mat_specular}}/reflections being disabled)
** During compilation, VBSP will generates blank cubemap textures.
** If you skip VBSP blank cubemap generation (either by using Mapbase VBSP without adding {{code|-autocubemap}}, using {{slamminsrc|name}} VBSP with {{code|-nodefaultcubemap}}, or if you [[Cubemaps#Deleting_cubemaps|deleted the cubemaps]], it will display the missing or generic texture instead, and building cubemaps for first time (without disabling {{code|mat_specular}}) will instead generate blank textures (or partially generate the cubemaps, with some of them are blank), until building it again second time, so don't forget to disable it. {{code|mat_specular}} must be also disabled prior to loading the map, otherwise disabling them after the map have been loaded, will cause {{code|buildcubemaps}} to generate blank textures aswell.
*Default cubemap textures (see image on right)
** If the cubemap is missing, the game first tries to fall back to LDR cubemaps (and fails), so the game ended up using this texture instead.
*Cubemaps appear bright ([[HDR]] only)
** If HDR version of the cubemap isn't present, the game will fall back to LDR version, which will cause it to appear bright on HDR.
*[[Missing content|Missing textures]] as reflections
** If the cubemap is missing and the game fails to use the default cubemap texture for some reasons, missing texture will show up as reflections.
** This also appears if you recompiled the map and overwrite the original which have cubemaps texture baked in, then {{key|Alt}} + {{Key|Tab}} back to the game (which sometime reloads the textures).

===Before building===
{{Cleanup|Modern Source games, namely {{portal2|1}} and {{p2ce|1|nt=1}}, do not need all these complicated params and steps, at least in my experience -[[User:Equalizer5118|Equalizer]] ([[User talk:Equalizer5118|talk]]) 10:56, 22 March 2024 (PDT)
Also some Source games (such as CS:S and HL2), doesn't appear to require cheats to be enabled to build cubemaps. Deleting cubemaps is probably not needed (atleast for SP games), since this would require you to use {{code|mat_specular 0}}, otherwise {{code|buildcubemaps}} will instead generate blank texture until you run the command again.</br>Edit 2: {{css|2}} builds cubemap correctly now without deleting cubemaps after engine update ({{tf2branch|1}}), so some steps can be skipped. -[[User:Kr0tchet|leonidakarlach]] ([[User talk:Kr0tchet|talk]]) 02:50, 25 August 2024 (PDT) - Edited 24 Feb 2025.
{{l4d2|2}} also does not require anything, other than '''maybe''' turning shader quality to medium. But it's not always required. Just loading the map and running Buildcubemaps is often enough. --[[User:MrFunreal|MrFunreal]] ([[User talk:MrFunreal|talk]]) 02:23, 11 February 2025 (PST)}}
{{Important|Maps for {{src13|4.1}} games (including {{tf2branch|4.1}}) and others, such as {{css|4.1}}, are known to include pre-built, blank cubemaps after being compiled (even if there are no '''env_cubemap''' entities in them). In {{mapbase|4.1}}, blank cubemaps are not automatically generated by default.</br>For {{src13sp|2}} and {{src13mp|2}} titles (including previous version of Valve games), [[Cubemaps#Deleting_cubemaps|deleting cubemaps]] will be required (in order to make sure cubemaps are properly written to the BSP). 
{{Tip|Deleting pre-built blank cubemaps, while not required, is recommended for {{l4dbranch|2}} games or later (and [[HDR]]-only games) since [[VBSP]] generates blank LDR cubemap texture that increase BSP file size while being unused anyway in those games.}}
{{Note|Deleting pre-built blank cubemaps isn't required for {{hl2|1}}, {{portal|1}} and all {{tf2branch|2}} games ({{css}}, {{dods}}, {{hldms}}, {{hldms}} and {{tf2}}), since updated version of those games now built and written generated cubemaps to the .BSP correctly.}}
}}
{{Important|
*  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.<br>For example, if the highest '''env_cubemap''' sizes 128x128, a resolution no lower than 512x512 will be required. (''128 &times; 4 &#61; '''512''' -&gt; 720x576'' (as a valid resolution) or higher)
* Disable any [[anti-aliasing]] method (SGSSAA for example) forced through GPU driver and enable the in-game AA or use FXAA instead (or simply run the game in [[Vulkan]] which will disable all forced AA) to avoid cubemaps being slowly built. This also applies to running the game at higher resolutions (such as 4K), which will cause cubemaps to be slowly built on weaker hardware. Running the game at lower resolutions (like 1080p) and/or disable AA (other than in-game AA), and disable any FPS cap, will significantly speed up building cubemaps progress.
}}
{{warning|{{clr}}
* '''EPILEPSY WARNING''': Building cubemaps on a faster systems (with high single-thread performance) will causes the top left of the screen (which display captured cubemap images) to flicker much faster. Look away from the screen while the cubemap is being built.
** Additionally, the screen will also flashes white when building HDR cubemaps.
** This mostly doesn't applies to games on {{src06|1}} or earlier, since these branches doesn't support multi-core and building cubemaps will take little bit longer on these branches.
* If the {{Command|nav_show_ladder_bounds}} command was used before building cubemaps, the green boxes will also be baked into the cubemap.
* The game may appear to freeze or become unresponsive during the process of building cubemaps, and the amount of time depends on various factors (amount of {{code|env_cubemap(s)}}, cubemap sizes, CPU usage/utilization and framerate). For successful results, don't switch away from the game until it's done.</br>If you have the game running on windowed/borderless windowed mode, clicking on the game while building cubemaps will cause the windows to freeze with "Not Responding" on the titlebar (even through the game is still building cubemaps). To avoid this, it's highly recommended that you run the game in (exclusive) fullscreen mode.</br>'''For users using Vulkan instead of Direct3D 9 (Windows only):''' Clicking on the game while building cubemaps, even in fullscreen, will also cause the game to permanently freeze.
* If you are building cubemaps for {{Hl2|4.1}} (except episodes) after the '''20th Anniversary Update''', you must [[Cubemaps#Half-Life_2|follow the instructions]] here. Also building cubemaps in Half-Life 2 without removing some NPCs (or switch the Gravity Gun to another weapon) will cause sprites light from them to be baked into cubemaps.
}}
{{tip|{{clr}}
* {{ent|env_cubemap}} entities [[Env cubemap#Keyvalues|allow]] for generating higher- or lower-quality reflections, though the game's texture quality also comes into play; consider maxing out your game's visual settings (set texture, models, shaders, shadow details to '''High'''/'''Very High''') before building cubemaps.
* Running the game at lower resolution (while making sure your screen resolutions are 4 times larger) and disabling FPS cap (both in game, graphics driver and software like [https://www.guru3d.com/page/rivatuner-rtss-homepage/ RTSS]) can speed up building cubemaps progress.
* [[Bind]] {{code|mat_hdr_level 0}}, {{code|mat_hdr_level 2}}, {{code|building_cubemaps 1}} to any numpad keys, and {{code|buildcubemaps}} to numpad {{Key|Enter}} key, so you don't have to manually type and submit most of these command on console.
}}
* If you are using {{mapbase|4.1}}, you can add {{code|-autocubemap}} to launch game ({{code|$game_exe}}) command line in {{hammer|1}}. The game will automatically build cubemaps
* {{slamminsrc|4.1|nt=1}} VBSP features the {{code|-nodefaultcubemap}} command, which skips automatically generating skybox cubemaps on map compile.

===LDR===
{{note|This step doesn't apply to {{l4d|4.1}} nor {{csgo|4.1}} as their maps are compiled in [[#HDR|HDR mode]] only. While {{p2|4.1}} does support LDR, the game uses HDR by default, so we recommend building cubemaps in HDR only.}}
{{Note|Cheats do not have to be enabled to build cubemaps in: {{hls|1}}, {{hl2|1}}, {{hl2dm|1}} (all three since {{hl2}} 20th Anniversary Update), {{portal|1}} (since May 20, 2025) and all {{tf2branch|1}} games.}}
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:
{| class="wikitable"
|-
! Command !! Description
|-
| {{Command|mat_specular|0}} || Turns reflections off, which is necessary if using only one iteration of buildcubemaps, and if all [[#Deleting cubemaps|cubemaps has been deleted]].<br>It also meant that disabling reflections would avoid some case where missing textures or default cubemap texture ({{code|materials/engine/defaultcubemap.vtf}}, aka a desert with orange sunset sky), might ended up reflected on the cubemap itself.</br>{{Note|If you let VBSP generate blank cubemap and you build cubemap without this command, it will build (and written cubemaps to [[BSP]]) just fine (atleast in {{hl2}}), however, if you deleted the cubemaps and run {{code|buildcubemaps}}, without disable {{code|mat_specular}}, it will instead generate and write blank texture, until you run {{code|buildcubemaps}} second time. {{code|mat_specular}} must be also disabled prior to loading the map, otherwise disabling them after the map have been loaded, will cause {{code|buildcubemaps}} to generate blank textures aswell.}}
|-
| {{Command|map}} ''map_name''</code> || Loads the map; replace "''map_name''" with the map's actual name
|-
| {{Command|sv_cheats|1}} || Enables the use of cheat commands; required to build cubemaps<br>{{Note|{{hl2|1}}, {{hl2dm|1}} (since 20th Anniversary), {{portal|1}} (since May 20, 2025 update) and all {{tf2branch|1}} games ({{css}}, {{dods}}, {{hl2dm}}, {{hldms}} and {{tf2}}), doesn't require cheats to build cubemaps, so this step can be skipped. In many {{src13|1}} (SP/MP) games, including previous version of {{css|1}}, {{code|buildcubemaps}} can be also built without enabling cheats, however, {{code|mat_reloadallmaterials}} (command that requires {{code|sv_cheats 1}}) must be run once in order to display the newly built-cubemaps, since cubemap textures may not be automatically loaded when you load up the map manually. Confirm if other games also require cheats to build cubemaps.}}
|-
| {{Command|buildcubemaps}} || Begins building cubemaps. Optionally, specify the number of iterations (e.g.: <code>buildcubemaps 2</code> (default is 1))
|-
| {{Command|disconnect}} || Unloads the map and returns to the main menu
|-
| {{Command|mat_specular|1}} || Turns reflections on, then follow the step below, or optionally you can repeat the process again by following instructions on [[#Improve reflections by rebuilding cubemaps|Improve reflections by rebuilding cubemaps]].
|-
| {{Command|map}} ''map_name''</code> || Loads the map again, your cubemaps should display after doing these steps.
|-
| {{code|[[mat_reloadallmaterials]]}}</br>(''requires'' {{code|sv_cheats 1}})|| In some games or branch ({{src13|1}}), if it doesn't display new cubemap textures after loading the map, run this command to display the newly-built cubemaps. This command may run automatically when you load up the map while cheats is already enabled. This command is usually not required on {{hl2|1}} (since 20th anniversary), {{portal|1}} (since May 2025 update) or all {{tf2branch|1}} games, since cubemaps should be automatically reloaded when you load the map.
|}

===LDR + HDR===
Building cubemaps in {{src06|3.1}} - {{src13|3.1}} game, with 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 (or using the {{code|mat_hdr_level}} command. To build the cubemaps for both LDR + HDR, submit the following commands into the game's console:
{{Note|Maps built on {{l4d|1}}, or later (and some third-party Source games), does not requires building cubemaps on LDR. See [[#HDR]]}}
{{Note|Cheats are not required to be enable to build cubemaps in: {{hl2|1}}, {{hl2dm|1}} (since 20th Anniversary) and all {{tf2branch|1}} games.}}
{| class="wikitable"
|-
! Command !! Description
|-
| {{Command|mat_specular|0}} || Turns reflections off, which is necessary if using only one iteration of buildcubemaps, and if all [[#Deleting cubemaps|cubemaps has been deleted]].<br>It also meant that disabling reflections would avoid some case where missing textures or default cubemap texture ({{code|materials/engine/defaultcubemap.vtf}}, aka a desert with orange sunset sky), might ended up reflected on the cubemap itself.{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar mat_specular 0}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("mat_specular", "0")}} (using [[VScript]]).}}{{Note|If you let VBSP generate blank cubemap and you build cubemap without this command, it will build (and written cubemaps to [[BSP]])  just fine (atleast in {{hl2}}), however, if you deleted the cubemaps and run {{code|buildcubemaps}}, without disable {{code|mat_specular}}, it will instead generate and write blank texture, until you run {{code|buildcubemaps}} second time. {{code|mat_specular}} must be also disabled prior to loading the map, otherwise disabling them after the map have been loaded, will cause {{code|buildcubemaps}} to generate blank textures aswell.}}
|-
| {{Command|map}} ''map_name'' || Loads the map; replace "''map_name''" with the map's actual name
|-
| {{Command|sv_cheats|1}} || Enables the use of cheat commands; required to build cubemaps<br>{{Note|{{hl2|1}}, {{hl2dm|1}} (since 20th Anniversary) and all {{tf2branch|1}} games ({{css}}, {{dods}}, {{hl2dm}}, {{hldms}} and {{tf2}}), doesn't require cheats to build cubemaps, so this step can be skipped. In many {{src13|1}} (SP/MP) games, including previous version of {{css|1}}, {{code|buildcubemaps}} can be also built without enabling cheats, however, {{code|mat_reloadallmaterials}} (command that requires {{code|sv_cheats 1}}) must be run once in order to display the newly built-cubemaps, since cubemap textures may not be automatically loaded when you load up the map manually. Confirm if other games also require cheats to build cubemaps.}}
|-
| {{Command|building_cubemaps_(console_command)|alt=building_cubemaps|1}} || Sets HDR exposure to a consistent value, which will make sure that one cubemap won't look as bright or darker than others. This will automatically reset back to 0 after cubemaps are built.{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar building_cubemaps 1}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("building_cubemaps", "1")}} (using [[VScript]]).}}
|-
| {{Command|buildcubemaps}} || Begins building cubemaps. Optionally, specify the number of iterations (e.g.: <code>buildcubemaps 2</code> (default is 1))</br>In singleplayer games, the map will be automatically reloaded after building cubemaps.
|-
| {{Command|disconnect}} || Unloads the map and returns to the main menu
|-
| {{Command|sv_cheats|0}} || Disables cheat commands; prevents command <code>''mat_reloadallmaterials''</code> from unnecessarily self-executing (which briefly freezes the game)
|-
| {{Command|mat_hdr_level|0}} || Switches to '''LDR''' mode (from '''HDR'''); submit <code>''mat_hdr_level 2''</code> instead if '''LDR''' cubemaps were built first
|-
| {{Command|map}} ''map_name'' || Loads the map again to build cubemaps for the new mode
|-
| {{Command|sv_cheats|1}} ||
|-
| {{Command|buildcubemaps}} || Begins building cubemaps for the new mode
|-
| {{Command|disconnect}} ||
|-
| {{Command|mat_specular|1}} || Turns reflections on, then follow the step below, or optionally you can repeat the process again by following instructions on [[#Improve reflections by rebuilding cubemaps|Improve reflections by rebuilding cubemaps]].
|-
| {{Command|mat_hdr_level|0/1/2}} || If necessary, switches back to the mode it was before having submitted <code>''mat_hdr_level 0/2''</code>
|-
| {{Command|map}} ''map_name''</code> || Loads the map again, your cubemaps should display after doing these steps.
|-
| {{code|[[mat_reloadallmaterials]]}}</br>(''requires'' {{code|sv_cheats 1}})</br>or {{Key|Alt + Tab}} / Restart game|| In some games, such as {{css|1}}, if it doesn't display new cubemap textures after loading the map, run this command to display the newly-built cubemaps. This command may run automatically when you load up the map while cheats is already enabled.</br>If this command does not reload cubemaps in-game, you can instead try {{key|Alt}} + {{key|Tab}} while in fullscreen or simply restart the game can sometime reload the texture (and display the new cubemap) aswell.
{{Note|{{Key|Alt + Tab}} only works properly in {{src09|1}} or earlier, and {{l4dbranch|1}} or later. {{src13|1}} or {{csgobranch|1}} games use Direct3D 9Ex, which meant that running those games on Windows 10/11, without setting multiple displays to "Duplicate" or disable fullscreen optimization, it will not reload anything at all when you {{key|Alt + Tab}}.}}
{{Note|Usually not required on {{hl2|1}} or all {{tf2branch|1}} games, since cubemaps should be automatically reloaded when you load the map.}}
|}

===HDR===
This section is for games running on the {{l4dbranch|4}} and later, or engine branches that only support HDR (such as {{xengine|1}}). To build cubemaps in HDR only, submit the following commands into the game's console:

{| class="wikitable"
|-
! Command !! Description
|-
| {{Command|mat_specular|0}} || Turns reflections off, which is necessary if using only one iteration of buildcubemaps, and if all [[#Deleting cubemaps|cubemaps has been deleted]].<br>It also meant that disabling reflections would avoid some case where missing textures or default cubemap texture ({{code|materials/engine/defaultcubemap.vtf}}, aka a desert with orange sunset sky), might ended up reflected on the cubemap itself.{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar mat_specular 0}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("mat_specular", "0")}} (using [[VScript]]).}}{{Note|If you let VBSP generate blank cubemap and you build cubemap without this command, it will build (and written cubemaps to [[BSP]])  just fine (atleast in {{hl2}}), however, if you deleted the cubemaps and run {{code|buildcubemaps}}, without disable {{code|mat_specular}}, it will instead generate blank texture, until you run {{code|buildcubemaps}} second time. {{code|mat_specular}} must be also disabled prior to loading the map, otherwise disabling them after the map have been loaded, will cause {{code|buildcubemaps}} to generate blank textures aswell.}}
|-
| {{Command|map}} ''map_name'' || Loads the map; replace "''map_name''" with the map's actual name
|-
| {{Command|sv_cheats|1}} || Enables the use of cheat commands; required to build cubemaps<br>{{Note|{{hl2|1}}, {{hl2dm|1}} (since 20th Anniversary) and all {{tf2branch|1}} games ({{css}}, {{dods}}, {{hl2dm}}, {{hldms}} and {{tf2}}), doesn't require cheats to build cubemaps, so this step can be skipped. In many {{src13|1}} (SP/MP) games, including previous version of {{css|1}}, {{code|buildcubemaps}} can be also built without enabling cheats, however, {{code|mat_reloadallmaterials}} (command that requires {{code|sv_cheats 1}}) must be run once in order to display the newly built-cubemaps, since cubemap textures may not be automatically loaded when you load up the map manually. Confirm if other games also require cheats to build cubemaps.}}
|-
| {{Command|building_cubemaps_(console_command)|alt=building_cubemaps|1}} || Sets HDR exposure to a consistent value, which will make sure that one cubemap won't look as bright or darker than others. This will automatically reset back to 0 after cubemaps are built.{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar building_cubemaps 1}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("building_cubemaps", "1")}} (using [[VScript]]).}}
|-
| {{Command|buildcubemaps}} || Begins building cubemaps. Optionally, specify the number of iterations (e.g.: <code>buildcubemaps 2</code> (default is 1))</br>In singleplayer games, the map will be automatically reloaded after building cubemaps.
|-
| {{Command|disconnect}} || Unloads the map and returns to the main menu
|-
| {{Command|mat_specular|1}} || Turns reflections on, then follow the step below, or optionally you can repeat the process again by following instructions on [[#Improve reflections by rebuilding cubemaps|Improve reflections by rebuilding cubemaps]].
|-
| {{Command|map}} ''map_name''</code> || Loads the map again, your cubemaps should display after doing these steps.
|-
| {{code|[[mat_reloadallmaterials]]}}</br>(''requires'' {{code|sv_cheats 1}})</br>or {{key|Alt + Tab}} / Restart game|| In some games, such as {{css|1}}, if it doesn't display new cubemap textures after loading the map, run this command to display the newly-built cubemaps. This command may run automatically when you load up the map while cheats is already enabled. In {{l4d|1}} (or some Source games), this command may not reload cubemaps in-game, so instead try {{key|Alt}} + {{key|Tab}} while in fullscreen or simply restart the game can sometime reload the texture (and display the new cubemap) aswell.
{{Note|{{Key|Alt + Tab}} only works properly in {{src09|1}} or earlier, and {{l4dbranch|1}} or later. {{src13|1}} or {{csgobranch|1}} games use Direct3D 9Ex, which meant that running those games on Windows 10/11, without setting multiple displays to "Duplicate" or disable fullscreen optimization, it will not reload anything at all when you {{key|Alt + Tab}}.}}
{{Note|Usually not required on {{hl2|1}} or all {{tf2branch|1}} games, since cubemaps should be automatically reloaded when you load the map.}}
|}

==Building cubemaps in specific games==
===Black Mesa ===
To build cubemaps in {{bms|4.1}} maps, the game has to be launched with these parameters: <code>-oldgameui -dev -console +r_4way_use_fast_normals 0</code><br>Then, load the map, follow the instructions on [[#HDR|HDR section]].

After building cubemaps, you can proceed to [[#Improve reflections by rebuilding cubemaps]] or simply quit the game, then launch the game again without the command line argument.

===Half-Life: Source===
{{Note|Some materials/textures in HL:S will use reflections located on {{path|environment maps}} folder instead. So even if you already build cubemaps, it only displays in some materials that use {{code|[[$envmap]] env_cubemap}}.}}
{{bug|hidetested=1|Building cubemaps in older version of {{hls|4.1}} is currently not possible as their textures, despite being generated, aren't embedded into the map file afterward.</br>
This is fixed with Half-Life 2's 20th Anniversary update, which also applies to HL:S. Issue is not affected on {{hldms|1}}.
{{workaround|Move the map file into the {{path|maps}} folder of a game in the same engine branch (such as {{hl2|4.1}}), build its cubemaps in that game, then move the file back into '''Half-Life: Source'''<nowiki>'</nowiki>s folder.}}}}

=== Half-Life 2 ===
; All versions
{{bug|hidetested=1|NPCs such as [[npc_combine_camera]] and [[npc_turret_ceiling]], while completely invisible when building cubemaps, will have it's sprite lights baked into cubemaps.
{{Workaround|Enable {{code|sv_cheats 1}} then remove the NPCs above using {{code|ent_remove_all npc_combine_camera;ent_remove_all npc_turret_ceiling}} command before running {{code|buildcubemaps}}.}}
}}
{{bug|hidetested=1|Similar to above, if the [[player]] equips [[weapon_physcannon|Gravity Gun]], then building cubemaps, it's sprite lights also get's baked into cubemaps.
{{Workaround|Simply switch to other weapons.}}
}}
; 20th Anniversary only
{{bug|hidetested=1|Building cubemaps in {{hl2|4.1}}, {{hl2ep1|4.1}} and {{hl2ep2|4.1}}, after the 20th Anniversary update, might fail. In Half-Life 2's case, the game may access the wrong directory (example: {{code|episodic/maps}}), instead of {{code|hl2/maps}}, preventing the cubemaps from embedded into the map file.

You may also see this error message generated on the console:
{{code|vtex failed to compile cubemap! Unable to remove \steamapps\common\half-life 2\episodic\materials\maps\<map name>\<cubemap location>.vtf}}

{{Workaround|Launch Half-Life 2 with {{code|-game hl2}} [[command line argument]] (or go to {{code|steamapps\common\Half-Life 2}} and run {{code|hl2.exe}} directly). For Episodes, launch the game through Steam > Tools (or using {{code|-game episodic}} or {{code|-game ep2}}).}}
}}

=== Left 4 Dead / Left 4 Dead 2 ===
{{l4d|4}} and {{l4d2|4}} restrict certain console commands, such as {{code|mat_specular}} and {{code|building_cubemaps}}. While it seems to be optional, the latter command is recommended to make HDR cubemap have consistent exposure.

;For {{l4d|2}}, you must use {{code|SourceMod}} in order to use these commands (since VScript wasn't introduced until L4D2):
:{{code|sm_cvar mat_specular 0}}
:{{code|sm_cvar building_cubemaps 1}}

;For {{l4d2|2}}, you can either use SourceMod or run these [[VScript]] command:
:{{code|script Convars.SetValue("mat_specular", "0")}}
:{{code|script Convars.SetValue("building_cubemaps", "1")}}

Additionally, unlike {{css|1}} or other Source branches, {{code|mat_reloadallmaterials}} does not reload the cubemap texture, so after you built the cubemap, you will need to restart the game, or alternatively, while in fullscreen mode, {{key|Alt}} + {{key|Tab}} to desktop then back to the game (while the map is already loaded) will reload the cubemap texture in-game.

===Portal 2===
{{bug|hidetested=1|Building cubemaps in {{portal2|4.1}} will fail (and may crashes the game) if the map file is not in the highest-numbered DLC folder ({{path|dlc2}} by default, mods installed will be {{path|dlc3}} or higher).

{{workaround|Move the map to that folder before building cubemaps and, if necessary, edit the "'''Place compiled maps in this directory before running the game'''" path in [[Hammer Build Programs|Hammer's Build Programs]] options so that the map is automatically generated there.}}|only=portal2}}

===Source Filmmaker===
[[File:Cubemap_bug_sfm.jpg|thumb|right|300px|Improper rendering of an HDR cubemap's face in Source Filmmaker.]]
{{bug|hidetested=1|'''HDR''' cubemaps sizing lower than 128x128 built-in {{tf2|4.1}} and some other games usually display graphical artifacts on reflections due to the last face of each cubemap not rendering properly in {{sfm|4.1}}. While rebuilding cubemaps in it (and restart the game to display new cubemaps) would normally fix the issue, it is currently not possible to do so as {{Sfm|4}} doesn't built it correctly (all faces will ended up look the same as each other, even if there are multiple {{code|env_cubemap}} entities).
{{workaround|If recompiling a special version of an affected map with {{ent|env_cubemap}}'s now sizing 128x128 (or higher) is not an option, move the map file into {{as|4.1}}<nowiki>'</nowiki>s {{path|maps}} folder, build its cubemaps in that game, then move the file back into {{sfm|4.1}}<nowiki>'</nowiki>s folder.}}}}

:{{note|'''Alien Swarm'''<nowiki>'</nowiki>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|{{tf2|4.1}} configurations were used for the example; consider replacing game subfolders (only those within {{sfm|4.1}} paths) with the ones needed.
:{{workaround|Another option is to manually remove the [[$envmapsphere|sphere map]] (face #7) from the existing HDR cubemap textures. See [[$envmap#Creating a custom static cubemap texture|Creating a custom static cubemap texture]] for more info.<br>Alternatively, deleting the affected HDR cubemap texture files will cause the LDR versions to be used, which do not suffer from this bug.}}}}

=== Source 2013 MP / Team Fortress 2 ===
{{warning| Building cubemaps on a [[BSPZIP#Compression|compressed .bsp]] (in {{src13mp|1}} and {{tf2branch|1}} games) will crash the game!}}
{{Note|For {{tf2branch|4}} games, [[#Deleting_cubemaps|deleting cubemaps]], and using {{code|sv_cheats}} to build cubemaps are no longer required. However if you are mapping on {{src13mp|1}} games (including previous version of Valve games running on {{src13mp|1}} branch), you will need to delete cubemaps and enable cheats to build cubemaps.}}

== Improve reflections by rebuilding cubemaps ==
This step is optional but after building cubemaps once and enable reflections ({{code|mat_specular 1}}), you can build cubemaps again to improve reflections. The improvement it makes is only noticeable if the {{code|env_cubemap}} size was increased to higher resolutions and/or there are two reflective surfaces near each other.

To improve reflections, run the following commands:
{| class="wikitable"
|-
! Command !! Description
|-
| colspan = 2 | <center>Follow the same instructions as '''[[#LDR|LDR]]''', '''[[#LDR + HDR|LDR + HDR]]''' or '''[[#HDR|HDR]]''', up until the {{code|building_cubemaps}} and {{code|buildcubemaps}} command. Make sure {{code|mat_specular}} is set to "0" first.</center>
|-
| {{Command|building_cubemaps_(console_command)|alt=building_cubemaps|1}} || Sets HDR exposure to a consistent value, which will make sure that one cubemap won't look as bright or darker than others. This will automatically reset back to 0 after cubemaps are built.{{note|Only use this command if the map is loaded in HDR}}{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar building_cubemaps 1)}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("building_cubemaps", "1")}} (using [[VScript]]).}}
|-
| {{Command|buildcubemaps}} || Begins building cubemaps.{{note|Running {{code|buildcubemaps}} with multiple iterations (e.g. {{code|buildcubemaps 2-4}} or etc..), does not appear to actually improve reflections, it only repeats the buildcubemaps process. To actually improve reflections, you have to disconnect and reload the map before building cubemaps again, this will make sure the map would display the newly built cubemaps.}}
|-
| {{Command|disconnect}} || Unloads the map and returns to the main menu</br>Skip both {{code|disconnect}} and {{code|map}} if the game (usually singleplayer like {{hl2}}) reloads map automatically.
|-
| {{Command|map}} ''map_name'' || Loads the map again
|-
| {{Command|mat_specular|1}} || Turns reflections on.
|-
| {{Command|building_cubemaps_(console_command)|alt=building_cubemaps|1}} || Sets HDR exposure to a consistent value again. This will automatically reset back to 0 after cubemaps are built.{{note|Only use this command if the map is loaded in HDR}}{{Note|This command is flagged as "launcher"-only in {{l4d|1}} and {{l4d2|1}}, you can use the following command instead: </br>{{L4d}} {{code|sm_cvar building_cubemaps 1)}} command (with [[SourceMod]] installed) or </br>{{L4d2}} {{code|script Convars.SetValue("building_cubemaps", "1")}} (using [[VScript]]).}}
|-
| {{Command|buildcubemaps}} || Building cubemaps the second time.
|-
| {{Command|disconnect}} || Once you are done, unloads the map.<br>Alternatively, you can switch to LDR or HDR mode using {{code|mat_hdr_level 0/2}}, then repeat the steps starting from the first {{code|buildcubemaps}} command. You can also optionally repeat the process again multiple times to further improve reflections, but 2 iterations should be enough.
|-
| {{Command|map}} ''map_name'' || Loads the map again, it should display the new cubemap textures after doing these steps. 
|-
| {{Command|mat_reloadallmaterials}}</br>or {{Key|Alt + Tab}} / Restart game || In some games, such as {{css|1}}, if it doesn't display new cubemap textures after loading the map, run this command to display the newly-built cubemaps. This command may run automatically when you load up the map while cheats is already enabled. In {{l4d|1}} (or some Source games), this command may not reload cubemaps in-game, so instead {{key|Alt}} + {{Key|Tab}} while in fullscreen or simply restart the game can sometime reload the texture (and display the new cubemap) aswell. 
{{Note|{{Key|Alt + Tab}} only works properly in {{src09|1}} or earlier, and {{l4dbranch|1}} or later. {{src13|1}} or {{csgobranch|1}} games use Direct3D 9Ex, which meant that running those games on Windows 10/11, without setting multiple displays to "Duplicate" or disable fullscreen optimization, it will not reload anything at all when you {{key|Alt + Tab}}.}}
|-
|}

<div style=width:100%;overflow:auto>
{| border="0" cellpadding="4"
|[[File:Buildcubemaps - 1st iterations.jpg|thumb|center|1st iteration]]
|[[File:Buildcubemaps - 2nd iterations.jpg|thumb|center|2nd iteration]]
|[[File:Buildcubemaps - 8th iterations.jpg|thumb|center|4-8th iteration]]
|}
</div>

==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 file due to misuse. To delete cubemaps, execute the following command within the {{path|maps}} folder:
 ..\..\bin\bspzip -deletecubemaps map_name.bsp
{{note|Replace "''map_name''" with the map's actual name.}}
{{Note|Once you deleted the cubemaps, building cubemaps again will require {{code|mat_specular 0}} prior to loading the map, otherwise {{code|buildcubemaps}} will need to be run twice, since it has to generate blank textures first to avoid missing texture/generic texture on reflective surface being baked into cubemaps. {{code|mat_specular 0}} will prevent that from happen, so you just simply run {{code|buildcubemaps}} once.
Deleting cubemaps will also display the message {{code|Failed, using default cubemap 'maps/map-name/cubemapdefault'}} once you load the map with deleted cubemaps.
}}
{{Note|If you are making maps for HDR only games, deleting unused blank LDR cubemaps is optional but recommended to reduce BSP file sizes.}}
{{Important|Usually not required on {{tf2branch|1}} games ({{css}}, {{dods}}, {{hl2dm}}, {{hldms}} and {{tf2}}), since cubemaps are now properly written to the BSP. But if you still encounter the problem, try to delete cubemaps.}}
{{warning|Deleting cubemaps actually deletes all the texture ("[[Valve Texture Format|.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 {{path|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 {{path|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==
Renaming the map .bsp file breaks cubemaps on non-world geometry (models, props, weapons etc.). When map is being loaded the Source engine loads the Pakfile (containing, amongst others, cubemap textures and patch materials) embedded in the map. To display cubemaps on said geometry the engine searches ''materials/<MAP BSP FILENAME>'' directory but if such directory is not found, due to the BSP file being renamed, the cubemaps are not displayed.
Cubemaps on world geometry however are not affected, as the internal BSP data still points to a valid materials inside the Pakfile (see [[BSP_(Source)#TexdataStringData_and_TexdataStringTable|TexdataStringData and TexdataStringTable]]).
<br>
{{Bspentspy|2}} allows for renaming the internal map structure and data to fix the issues with Cubemaps

==See also==
* [[env_cubemap]]
* [[$envmap]]
* [[parallax_obb]] - For Parallax Corrected Cubemaps.

[[Category:Cubemaps]]
[[Category:Level Design]]