How to properly build cubemaps for your hammer map

This guide explains how to build cubemaps in your Portal 2 custom maps made in hammer and how to fix possilbe issues.

Why build cubemaps anyway?

It's important to build cubemaps because they provide the reflections on reflective materials in your map such as glass and shiny surfaces. When you're not building the cubemaps, the engine sometimes shows default reflections which look really wrong and ugly.

Preparation

Before you can build cubemaps, you need to make sure that:

1. your map contains env_cubemap entites in the right spots (next to shiny objects or generally in the center of a room. a good height to place them at is 64 units because that's the eye-level of the player) because otherwise the engine doesn't know where to build the cubemaps from.
   
2. your map is compiled using a full compile for both HDR and LDR. (well, you don't absolutely need to do this for the next step to work, but I'm highly recommending it.) If you don't know how to do a full compile, there are some guides in the workshop about that such as this one.
   
3. the file name of your map does not contain any spaces or weird characters. To be 100% safe just refrain from using anything but a-z, underscores and numbers to name your file. (The reason for that is that if you have these characters, the file will automatically be renamed after uploading and renaming breaks the cubemaps. More on that below)

Building cubemaps

Normally, to build your cubemaps in a source game you just type buildcubemaps into the developer console and reload your map. In Portal 2 however, things get a little more compilcated.

First of all, your freshly compiled map will be copied to the following directory: <Steam installation directory>/steamapps/common/Portal 2/portal2/maps. If you're loading up your map in Portal 2 with the map <your map name> command and then proceed to build the cubemaps with the buildcubemaps command, your game will crash. gg valve

So, to prevent that from happening, you need to move your fully compiled bsp file from <Steam installation directory>/steamapps/common/Portal 2/portal2/maps to <Steam installation directory>/steamapps/common/Portal 2/portal2_dlc2/maps. After that, you can load up your map in the game again.

Note: As Luke18033 pointed out in the comments, if you're using custom content, beemod or have a higher DLC folder for some other reason (e.g. portal2_dlc3) you should put your map there (in the DLC folder with the highest number at the end) instead of portal2_dlc2.

Then proceed to enter the following commands:

1. mat_hdr_level 0
   
2. mat_specular 0
   
3. buildcubemaps
   
4. mat_hdr_level 2
   
5. mat_specular 0
   
6. buildcubemaps

What this does is building your cubemaps for both HDR and LDR lighting. The mat_specular command disables any reflections that are already present so that they don't interfere with the new reflections that are being built.

Note: Your game will reload the map after the mat_hdr_level and buildcubemaps commands. That's fine.

What now?

Congratulations, your cubemaps have been built! (hopefully)
If you want to test the newly generated reflections, just type in the command mat_reloadallmaterials and reload your map. You should now see nice reflections on the shiny surfaces in your map. (If you want to be 100% sure that you're not seeing any cached reflections, just relaunch the entire game. That's what I do most of the time)
If there were any errors, you can hop over to the next section where I'm trying to explain possible errors.

Two more things that are important:

1. Do NOT rename your map after you've built the cubemaps. You can move it, that's fine, but renaming will break the reflections. If you're going to upload this map, make sure you do not change the file name after you've built the cubemaps! (You can of course change the title of your workshop item when you're uploading your map, but the filename has to stay the same)
   
2. If you want to pack some custom content into your map, do that AFTER you've built the cubemaps. I also highly recommend to move your bsp from the portal2_dlc2/maps folder back to the portal2/maps folder in case you're using software like Pakrat to pack your custom content because the file paths to the textue files in your custom material files will be updated by Pakrat and if your map is still in the portal2_dlc2/maps folder, that might mess something up (It shouldn't, but better move it back just to be sure)

Troubleshooting

Here are some common problems:

Problem: HAALP MY PORTAL 2 IS CRASHING!!!11!1 wtffffffff
Solution: Make sure you placed your map in the portal2_dlc2/maps directory and not in the default portal2/maps folder.

Problem: The reflections are not showing up after I reload my map.
Solution: Close your game and reopen it and try again. Maybe something has been cached.

Problem: The reflections are still not there after I relaunched the game OR the reflections are way too bright/colorful, look wrong or not fitting.
Solution: There are a couple of things that might have gone wrong.
First of all, when you're using the buildcubemaps command and it seems to work fine, what the engine does is building the cubemaps by essentially taking 6 low resolution square screenshots of the surrounding environment of each env_cubemap entity (hence the name cubemap, because it maps the environment onto the 6 faces of a cube). These images are then written to the existing bsp file on disk in the portal2_dlc2/maps directory. So the first thing that you can do is check if they have actually been saved to your map file. In order to do this, navigate to your map file in the file explorer (<Steam installation directory>/steamapps/common/Portal 2/portal2_dlc2/maps) before building the cubemaps and remember the file size. Then proceed to build the cubemaps as described above and check the file size again. If it hasn't gone up, that means your cubemaps have probably been built but not saved to the file. This shouldn't happen, but what you can try to do is recompiling your map, restarting your game or follow the steps in the next section.

Problem: The filesize of my map has gone up after I used buildcubemaps, but the reflections still look weird or are missing.
Solution: This problem occured to me too. I think it has something to do with the steampipe update for Portal 2 because this has been working before. You can find the solution to this problem in the next section.

Problem: The filesize of my map has gone DOWN?! after I used buildcubemaps!
Solution: This happens sometimes. As long as the filesize changes it means Portal 2 was able to write into the bsp file. So as long as the reflections are working the next time you load up your map, theres nothing to worry about, I think.

Trying to fix the steampipe problem

You can skip this section if everything worked for your map!

If it didn't, here's the issue that's probably caused building cubemaps to fail:
Since Valve ported Portal 2 to the steampipe content distribution system, for some reason, building cubemaps sometimes fails because the map compiler already puts empty cubemap textures in the bsp file and then Portal 2 doesn't want to overwrite this data or fails in doing so.
To fix that, we need to first remove that data from the bsp file so Portal 2 can put its new data there. To do this, you need a bsp file editor like Pakrat or VIDE.
I will be using Pakrat to demonstrate what you'll need to do. You can download Pakrat here[www.bagthorpe.org]

Alright, so first, make sure your map is not loaded in the game (it's best to exit Portal 2 altogether).
Then, open up your map with the bsp editor of your choice.
You will see all the additional files that are packed into your bsp map file:

Now, what you want to do is select all the files that end in .vtf and .hdr.vtf EXCEPT FOR cubemapdefault.vtf and cubemapdefault.hdr.vtf
Also make sure you don't select any files ending with .vmt if there are any because they're required. Then delete these files by pressing the delete button below. I would once again like to point out that you must NOT delete cubemapdefault.vtf and cubemapdefault.hdr.vtf because that would mess up pretty much everyting reflection-wise.
After you removed these files, hit File -> Save BSP and overwrite the file, that means save the file in the exact location where it was before (in the portal2_dlc2/maps directory) with the same file name. Now the cubemap texture data is removed from the bsp and you can proceed to build the cubemaps in the game (restart your game and reload your map first).

Note: Sometimes, applying this fix can screw things up even more and then the cubemaps look very colorful and unfitting. In that case, just recompile the map and try again to build the cubemaps without deleting the cubemaps in the bsp file before. If you're aware of why that happens, please tell me because I don't really have any clue...


If it's still not working for you now or if you have any questions, leave a comment below explaining your problem and I'll look at it and try to provide you with a solution or an answer.

Thanks for reading and happy cubemapping! ;)

[Noratekki]

For people who dont already know, you can do buildcubemaps 2 to build the cubemaps 2 times for recursive reflections in the cubemap. Good if you placed a cubemap in a spot where's there's a reflective object and you want recursive reflections for it.

[PuzzlePuddles]

team fortress 2 btw

[PuzzlePuddles]

i build my cubemaps normally alright and they do work properly once but for some reason each time i leave and recompile later the cubemaps break and i have to rebuild them again??

[mallary.thompson]

fgrtsdd fart

[mallary.thompson]

gg

[nobbers]

Yes, and a thank you as well for the guide Enderlux. I had been using cubemaps incorrectly in the past just to 'squash' ugly reflections, and not to render the correct reflections. I'm using the giant pistons in my latest map in a room with brick wall texture, and seeing what looks like grey rock shining back on the cylinders isn't really all that spectacular

[anna]

@Seg ty! this guide is for portal 2 specifically so i can't say if it'll work this way with other source games (the basics such as buildcubemaps and stuff should be the same but there might be some game specific quirks that are not mentioned here, e.g. like in portal2 you have to move it to the dlc dir to have it work)

[anna]

yeah idk it's a bit weird. at least there's some way to get it to work instead of having it outright not work at all (remember that time when the map uploader was broken for like a year lmao)

[nobbers]

It's a real shame that after all this time that the map (still) has to be in the portal2_dlc2/maps directory to work properly. Putting it back in the default portal2/maps folder after all these steps and running it just breaks it all over again.

Not a small thing Valve, given the number of peeps that contribute their Workshop items, and that there has been two updates over the last month or so.........

[Seg]

important to do those cube maps since a lot of weapons these days (particularly in garrys mod) have reflective textures, which have a really unpleasant effect if cubemaps aren't properly placed. Put off learning how to do this for a while. Great guide!