Cubemaps in GMod: Fix Purple and Black Reflections

Purple and black checkered or wrong reflections appear when reflective materials cannot find matching cubemaps. Either they were never built, they were built for only one of the two lighting modes, or they were lost after a change to the BSP. Place env_cubemap entities, load the map in game and run buildcubemaps separately for LDR and HDR. Then reload the map.

What cubemaps are and why they can be missing

A cubemap consists of six images of the surroundings, captured from a fixed point. Materials with a reflective component use it as a precalculated reflection. It is not a real-time mirror. When compiling, VBSP assigns each reflective brush face to an env_cubemap, by default the nearest one. Models use the one closest to them.

Compiling only creates placeholders. You capture the actual images in game afterwards, and the engine writes them into the pakfile of the BSP. Until that has happened, the faces reflect the sky as a substitute. Indoors this looks too bright and often bluish. If that substitute cannot be found either, the purple and black checkerboard shows up in the reflection. If the cubemaps exist for only one of the two modes, the reflections in the other one are too bright or blank, according to the Valve Developer Community.

This has nothing to do with missing materials. The face itself is textured correctly, only the reflection is broken. For real pink and black surfaces and ERROR models, see the article on fixing missing textures and ERROR models.

Placing env_cubemap correctly

• One per room or lighting mood. Every area with its own lighting or wall colour needs at least one env_cubemap. In long corridors you place several, especially at transitions.
• At eye level. The reflection should match what a player sees. So put the entity at roughly head height above the floor.
• Away from walls. An env_cubemap inside a brush or right against a wall captures a useless image.
• Assign faces deliberately. With the "Brush faces" property you define which faces use exactly this cubemap. That helps with reflective floors and glass.
• Do not overdo it. Every cubemap increases the size of the BSP, and HDR maps add the images for the second mode on top. Many entities in a small space bring no visible gain.

How strongly a face reflects is determined by its material. The basics of light and HDR are covered in the article on lighting in the Source Engine.

Building cubemaps: LDR and HDR separately

Two requirements: the BSP comes from the final compile, and it sits in the garrysmod/maps folder as a regular, writable file. For a BSP that is not writable, the engine has a console message of its own (is not writable). A map that only exists inside an addon archive is not a regular file of this kind either.

If the map is compiled with HDR, you need two passes:

1. Start the game and load the map.
2. Enter mat_specular 0. This keeps existing, faulty reflections out of the new images.
3. Enter mat_hdr_level 0 and reload the map, for example with map <mapname>.
4. Enter buildcubemaps and wait until the process has finished. The view briefly jumps through all capture positions.
5. Enter mat_hdr_level 2 and reload the map again. For the HDR pass, the Valve Developer Community also recommends building_cubemaps 1, which keeps the exposure the same for all images.
6. Enter buildcubemaps once more.
7. Set mat_specular 1 again, reload the map and check the reflections.

For a map without HDR a single pass is enough. Steps 5 and 6 are then skipped.

Known pitfalls

What to watch after packing

The cubemaps are stored as files in the pakfile of the BSP, in a folder below materials/maps/ that carries the name of the map. Three rules follow from that.

Every new compile discards them. VBSP writes the BSP from scratch. So you always build cubemaps at the end, and again after every final compile.

The name has to be final. Settle on the final file name before you build cubemaps. According to the Valve Developer Community, renaming the BSP afterwards breaks the cubemaps on models, props and weapons, because the engine looks for them in a folder named after the BSP file. The brush faces of the map are not affected.

Check after every edit to the BSP. Build cubemaps only after the final compile and compress the BSP at the very end, because according to the Valve Developer Community buildcubemaps crashes the game on a compressed BSP. Whether you pack custom content before or after the cubemaps matters less than checking afterwards. Any tool that rewrites the pakfile can change entries. So load the finished file in game once more and check the reflections in both modes.

The Map Scanner lists embedded Lua and asset files in the pakfile. Whether the reflections are really correct can only be seen in game, though. A look at the reflections is therefore part of checking a map before release.

FAQ

Why are the reflections on my map purple and black?

The reflective materials cannot find a matching cubemap. A typical cause is cubemaps that a tool removed from the pakfile, so that not even the substitute is found. A BSP that was renamed after building is a different case: according to the Valve Developer Community, models, props and weapons then lose their cubemap reflections, while brush faces keep theirs. Rebuild the cubemaps under the final map name for LDR and HDR.

Do I have to rebuild cubemaps after every compile?

Yes. Every compile produces a new BSP without captured cubemaps. You can skip it while working, but before a release it is mandatory.

How many env_cubemap entities does a map need?

Enough for every room and every clearly different lighting mood to have its own. There is no fixed number. More entities mean a larger file, so sparing and deliberate use pays off.

What can I do as a player about purple and black reflections?

You cannot repair the cubemaps on someone else's map. mat_specular 0 turns reflections off, which also makes the checkerboard disappear. The clean solution is a corrected version of the map.