HDRI to Source engine skybox

Source Skyboxes is a site we also maintain. It hosts a library of free Source engine skyboxes. Each sky comes as a VTF/VMT bundle and as the original 32-bit EXR file.

What the export produces

The Source Skybox Bundle export turns the loaded panorama into a complete materials/skybox/ folder. For each of the six cube faces, the export writes two versions: a standard LDR version and an HDR version. Source uses the HDR version when the player has HDR lighting switched on. Each version is a .vtf texture paired with a .vmt material file. Every file is named from the sky name you choose.

Source identifies the faces by a two-letter suffix. With a sky name of sky_dusk, the LDR textures have these names:

There is no separator between the sky name and the suffix. That is the Valve on-disk convention. The HDR version of each face inserts _hdr before the suffix. Every .vtf has a matching .vmt:

materials/skybox/
  sky_duskft.vtf        LDR texture
  sky_duskft.vmt        LDR material   (UnlitGeneric)
  sky_dusk_hdrft.vtf    HDR texture
  sky_dusk_hdrft.vmt    HDR material   (Sky)
  plus the same four files for bk, lf, rt, up, dn
  = 24 files, packed as sky_dusk_skybox.zip

Step by step

1. Open the converter and load your equirectangular panorama. Equirectangular is the standard 2:1 wraparound layout. The file can be .exr, .hdr, .png, or .jpg. Only .exr and .hdr hold true HDR range. If you do not have a panorama, download the EXR for sky_sunset010_hdr from Source Skyboxes. Use it for the steps below.
2. Optional: use the Look tab to set the sky before exporting. It has controls for tone mapping, exposure, white balance, and environment rotation.
3. In the sidebar, open the Export tab and set Mode to Source Skybox Bundle.
4. Enter a Sky Name. It becomes the prefix for every filename in the bundle. The rules are in the next section.
5. Choose an HDR Compression mode. Compressed packs the HDR range into a small 8-bit texture. It is the format Valve uses for its own skyboxes. Uncompressed keeps a true 16-bit float per channel. The files are larger, but the values are exact.
6. Pick a Face Size: 256, 512, 1024, or 2048 pixels per face. The size closest to your source resolution is marked with a dot.
7. Optional: tick Apply current adjustments to export. This bakes the exposure, tone mapping, and white balance from the Look tab into the LDR textures. The HDR textures keep the original light values either way. That lets Source run its own exposure on them.
8. Click Render skybox bundle and save the zip.
9. Unzip the archive into your game or mod folder. The files are already nested under materials/skybox/, so they unpack into the correct folder. Then set the map skybox as the next section describes.

Choosing a sky name

The sky name is the prefix for every file in the bundle. It is also the name the map points at. There are four rules:

• Start with a letter or a digit.
• Use only letters, digits, hyphens, and underscores. No spaces, dots, or slashes.
• Keep it to 64 characters or fewer.
• The input strips any disallowed character as you type. A rejected name is therefore hard to submit by accident.

Source ships its own skyboxes with a sky_ prefix. A name like sky_harbor_dawn fits that convention. The map refers to the skybox through its skyname keyvalue. In Hammer, that keyvalue lives in Map Properties on the worldspawn entity. The engine adds the six face suffixes for you. The skyname value must not include ft, bk, or any other suffix.

One detail matters for HDR maps. The bundle ships two material sets. The skyname you set decides which one the map loads. Point it at the _hdr name, sky_harbor_dawn_hdr, to load the HDR-aware Sky materials. Those materials carry both the standard and HDR textures. They render correctly whether or not the player has HDR enabled. Use them for any HDR map. The plain sky_harbor_dawn loads the LDR-only set. That set fits only a map that does not use HDR.

Common pitfalls

• Standard-range source. A .png or .jpg holds nothing brighter than white. It has no HDR range to capture. The bundle still writes the HDR files. From a standard-range source, those files carry the same range as the LDR set. For a skybox that gains from HDR, such as a bright sun or an overbright sky, start from a .exr or .hdr file.
• Wrong folder. The files must sit under materials/skybox/ exactly. The zip already nests them that way. Unzip at the game or mod root and leave the folder structure intact.
• Deleting the HDR set. Both the LDR and HDR versions ship on purpose. Source picks between them based on whether the player has HDR rendering enabled. Deleting the HDR files breaks the sky for anyone playing with HDR on.
• Oversized faces. A 2048-pixel bundle is twelve large VTF files. For most Source maps, 512 or 1024 is enough. The recommended dot points at a sensible default.
• Sky-name mismatch. The skyname must never include a face suffix. The engine adds ft, bk, and the rest itself. For an HDR map, use sky_dusk_hdr. Do not use sky_dusk_hdrft.

Coming from Blender

If you are building the panorama in Blender, render it as a 2:1 equirectangular image first. Save it as a .hdr or .exr file. Then load it into the converter and follow the steps above. The HDRI in Blender guide covers the camera and World setup.