Env cubemap

Source Engine

Source 2

edit

A cubemap example containing the white static prop car, a sprite and decals. Note that the blue physics prop car is not visible in the cubemap because it is not static.

env_cubemap is an internal point entity available in all Source games. It specifies a location for which a cubemap will be generated when the buildcubemaps console command is executed. Materials with $envmap will use the nearest cubemap as their reflection.

Note:This is an internal entity. When the map is compiled by VBSP, it is processed and then removed; it does not exist when the map is running.

Warning:Cubemaps will contain static props, sprites and decals.

However, it also includes the following unwanted items that can ruin a cubemap:

• Gunfight decals such as explosions, blood and bullet impacts.
• A users spray image, as its also a decal.
• The Flashlight's projected texture, which can cause bright spots in dark rooms if you happen to be in it while building cubemaps.
• Any screenspace & post-processing effects such as: Damage indicating red tint, white flash of a detonating weapon_flashbang or the camera flash of npc_cscanner.
• Textures applied via r_screenoverlay.
• Sprites that are part of prop_dynamic/NPC's. Including, but not limited to: the sprite attached to a npc_combine_camera, or the sprites of the C130 plane in Dead Air

Therefore you might want to prepare the map before building cubemaps by turning off your flashlight and using the following console commands:
ent_fire npc* kill, ent_fire prop* kill, and ent_fire env_sprit* kill to delete all sprites and NPC's/props that might have sprites, followed by r_cleardecals to remove blood and bullet decals.

You could use the following as a .cfg to either run it via exec or alias its execution to something like "Buildcubemaps2" in your autoexec.cfg:

ent_fire npc* kill
wait 20
ent_fire prop* kill
wait 20
ent_fire env_sprit* kill
wait 20
r_cleardecals
wait 20
buildcubemaps

Keyvalues

Cubemap Size (cubemapsize) <choices>

The resolution of each face of the cubemap. Remember that the actual number of pixels stored will be your selection times six (or seven, depending upon engine branch), so higher numbers will make for very large file sizes!

Comparison of reflection quality.

• 0: Default (usually 32x32, depending on the game)
• 1: 1x1
• 2: 2x2
• 3: 4x4
• 4: 8x8
• 5: 16x16
• 6: 32x32
• 7: 64x64
• 8: 128x128
• 9: 256x256
• 10: 512x512 ¹ !FGD
• 11: 1024x1024 ¹ ² !FGD
• 12: 2048x2048 ¹ ² !FGD
• 13: 4096x4096^[confirm] ¹ ² ³ !FGD

¹ - To render higher resolution cubemaps than 256x256, see below.
² - Higher resolution (1024px or higher), may not work in some games. See #Higher_Resolution_Cubemaps.
³ - Building cubemaps on 4096x4096 requires the game runs on 16K resolution (which requires very powerful GPU (such as RTX 4090) with large VRAM to handle).

Brush faces (sides) <sidelist>

An optional override for individual brush faces, forcing them to use this cubemap instead of one closest to them. To select faces, press the Pick button then click on them in the 3D view. Hold Ctrl to toggle a face on or off.

Note:For MDL models, use the lightingorigin KV on the specific entity to point to an entity in the same location as the env_cubemap (not the env_cubemap itself!). Note that for models other than per-vertex lit or lightmapped static props, this will also affect the model's lighting!

Cubemap Bounds (parallaxobb) <targetname> (only in Strata Source and Mapbase games)

Optionally assigns this cubemap a bounding box for parallax correction (brush entity tied to parallax_obb). This means the cubemap reflection will move as the camera moves, similar to func_reflective_glass.

Name (targetname) <string>

Name of this entity. Displayed in Hammer's 2D views and Entity Report. No effect in-game, nor in map compilers.

Higher Resolution Cubemaps

Simply type in a value 10 or more (you don't need to disable SmartEdit). That will give the resolution corresponding to the next powers of 2 (512x512, 1024x1024, 2048x2048).

Warning:In and (as of its 20th Anniversary update) trying to build a 1024x1024 cubemap will result in an Engine Error.

Note:Building cubemaps requires your screen to be at least 4 times in each dimension as big as the cubemap's resolution. If your screen is smaller than that, use Dynamic Super Resolution (DSR) to build them.

If you have a monitor less than 4K and DSR only allows resolution up to 4K, you will also need Custom DSR Tool to build cubemaps at 1024x1024 (requires resolution above 4096x4096), or 2048x2048 (requires resolution above 8192x8192).

Note:Having high resolution cubemaps can significantly increase the map file size. So use it sparingly for things like mirrors and marble surfaces, if you're concerned about file size / client download time for multiplayer maps at least. High resolution cubemaps will also looks more noticeably unrealistic without Parallax Corrected Cubemaps.

Placement

Declaring areas for cubemaps to cover is simple, just place an env_cubemap point entity inside the space of a map. When the map is compiled with VBSP, world geometry surfaces automatically associate themselves with the nearest env_cubemap and will use the cubemap generated from it. Entities associate themselves with the env_cubemap closest to their origin (alternatively, a cubemap can be applied to specific brush faces in the cubemap's properties); moving entities will dynamically change which cubemap they use. It is important to choose env_cubemap positions properly for both aesthetic and performance issues.

Cubemaps are used in a few specific ways, and should be placed accordingly. Some cubemaps are used for reflections on static world geometry. Others are used with player entities, including NPCs. And the rest are used for any non-player reflective entities. The optimal placement of env_cubemap entities corresponds with each of these uses, to ensure the maximal benefit, visually and in performance. Here are a few simple heuristics to follow:

• If a cubemap is intended for NPCs or the player, the env_cubemap should be placed at eye-level (usually 64 hammer units) above the ground. This way, the cubemap will most accurately represent the world from the perspective of the player.

Tip:You can achieve this by copy-pasting env_cubemap entities around the map floor and then use Hammer's Entity Report function to select all env_cubemap entities and then moving them 64 units upward by using the Transform tool Ctrl+M.

• If a cubemap is intended for static world geometry, the env_cubemap should be a fair distance (as a rule of thumb, 16 Hammer units) away from all brush surfaces.
• A different cubemap should be taken in each area of distinct visual contrast. A hallway with bright yellow light will need its own env_cubemap, especially if it is next to a room with low blue light. Without two env_cubemap entities, reflections and specular highlights will seem incorrect on entities and world geometry in one of the areas.
• Location changes, such as one room-to-room, room-to-outside and general location changes with great visual changes need env_cubemap entities with equal distance in both locations to the transition point. For example 16 units away from the doorway into each rooms. That way the cubemap transition between locations is smooth. This will prevent the cubemap from showing the outside location inside the room and vice versa.
• Cubemaps set in a very dark area, as well as cubemaps outside of the playable area can use very small resolutions. Dark cubemaps barely reflect anything but the few bright spots to begin with, Using smaller ones barely makes any visual difference.

Warning:Placing cubemaps inside instances will break the "Face assignment" that would allow you to deliberately assign a specific brush face to the cubemap. The face ID assigned in the env_cubemap will be changed when placed as an instance in the map.
But otherwise, cubemaps in instances work as intended.

Example of an env_cubemap that is equidistant to two door frames at once, with a fitting env_cubemap on the other side of each doorframe.

Example of what misplaced cubemaps do.
The trailer and rifle scope reflect a cubemap from inside the building. Which makes reflective surfaces appear to glow in the night.

Building Cubemaps

For general and game specific information about building cubemaps, visit the Cubemaps page.

See also

• Cubemaps
• $envmap
• weapon_cubemap
• parallax_obb