Lightmap
SplitA lightmap is a generated texture applied to brush faces to simulate lighting. The color values in the surface's diffuse or albedo are multiplied by the color values in its lightmap.
Lightmaps are created by VRAD each time a map is compiled, although VBSP allocates the lightmaps. They are static and cannot change, though it is possible to switch lightmap 'pages' on and off (see Naming Lights).
In November 16, 2024, with the release of Half-Life 2 20th anniversary update, lightmaps are now Bicubic filtered if the player set the video options to "Very High". This can be toggled independently with the r_lightmap_bicubic cvar.
Note:
Source 2013 Multiplayer and 
Garry's Mod also support lightmaps on MDL props using VertexLitGeneric.Prop lightmaps are capable of being higher resolution than brush or displacement lightmaps, but come with their own share of complications; see $lightmap and prop_static for specifics.
Bug:
Lightmap seams can sometimes occur at brush face subdivisions when MSAA is enabled. As subdivision size (chopping) is affected by luxel scale, this is more noticeable at lower luxel scales (higher-resolution lightmaps). Engine modifications and a modified VBSP are required to reduce face subdivisions at lower luxel scales. [todo tested in?]Scale
Note:Lightmap scale can only be directly controlled in Source 1!
- In vanilla
GoldSrc, lightmap scale is always 1 luxel for every 16 texels (not units), regardless of texture scale. This means that smaller texture scales will result in allocblock being used up faster.
Code Fix:A custom renderer can use the DecoupledLM BSPX lump to store higher resolution lightmaps separate from texel scale; ericw-tools can create GoldSrc BSPs with this lump.
- In
Source 2, individual faces can be biased, giving them priority over other faces. The actual scale is dictated by total lightmap resolution, which is controlled separately.
The lightmap scale of a face defines the resolution of its lightmap. The default scale of 16 makes each lightmap pixel ("luxel") 16 units across, while a lightmap scale of 1 makes one luxel equal one unit. The Hammer Face Edit Dialog is used to change the value per-face.
Lowering scale will make lightmap shadows sharper, but leads to larger map filesize, slightly slower rendering and exponentially slower compiles (that at very low scales start to eat up shocking amounts of system memory).
When generating lightmaps, VRAD does not create penumbras. The effect can be done by placing multiple lights near each other to simulate a non-point source of light, and/or increasing lightmap scale (which is why the relatively large value of 16 is the default).
Note:Each compiled brush polygon can host a maximum of 31x31 luxels in , or 15x15 luxels (240x240 texels) in . HLBSP/VBSP will chop faces to get extra luxels on if it needs to.
- This limit is 124x124 luxels on displacements, which can't be automatically chopped by VBSP; see Displacement Luxel Density.
- The limit for brushes is increased to 127x127 luxels in
.
Tip:
- Fog in reality increases atmospheric scattering, making all shadows a lot more diffuse. Look at light_environment's sun spread angle
- Luxel scale does not need to be a power of two; it does not directly correspond to lightmap resolution. Any integer value can be used, but even scales are preferred to avoid seams; odd values may be also more prone to Engine Hunk Overflow[confirm].
Important:Faces which have lightmap scale set to 0 are treated as being set to 16 by VBSP, but Hammer rounds up the value of such faces to 1 instead. This affects VMFs which are exported from Jack.
Optimization
Lightmap optimization can be done by eye with the aid of a compiled map: faces with low lighting contrast can have their scales increased, and vice versa faces with high contrast should be considered for lower scale. Just beware of setting a face's scale so high that it ends up a 'blob' of light that doesn't blend with its neighbors (use mat_fullbright 2 to spot this).
Remember to take into account the size of a face, too. Moving a very large face even one point up or down can have a huge impact. Don't be afraid to split the face up if that helps, or to drop a bit of detail from huge floor or wall faces.
Hammer View
Clicking the camera control in the top-left of a 3D view in Hammer provides the option of "3D Lightmap Grid". This view textures each brush surface with a grid that represents its lightmap scale (shown in the last section).
Tool brushes are textured like any other in this mode, despite being invisible in-game, so switch them all off from their auto-visgroup.
Bicubic lightmaps
In Half-Life 2, since 20th Anniversary Update, includes "Very High" shader detail options, which would enable Bicubic filter on lightmaps, smoothing out the aliased (stair-step) effect. This can be also toggled independently with the r_lightmap_bicubic cvar.
The image below compares between disabled and enabled.
Console Commands
The following are all cheats, except r_lightmap_bicubic:
mat_fullbright 2- Replaces all albedos with a grey tone, leaving just lighting information.
mat_luxels <bool>- Display luxels on all brush surfaces and props with prop lightmaps. Note:Distorts on displacements, this is not a bug.
- Bug:This command appears to be broken in
Source 2013 Singleplayer. [todo tested in?] mat_filterlightmaps <bool>- Control whether luxels are smoothed together in the same way as texels.
r_avglightmap <bool>- Doom mode! Averages lightmap values across each polygon.
mat_showlightmappage <int>- Unwraps each lightmap into a small, tessellating display in the top left of the screen. Not terribly useful to modders.
r_lightmap <int>- Specifies the light style index to compute and display the lightmap for. If set to
-1(default), computes for all light styles. Primarily used for debugging and inspecting specific light styles' effects on the lightmap. r_unloadlightmaps <bool>- Controls whether lightmap data is unloaded from memory after being updated. When set to
1, the engine unloads lightmap data to save memory. Useful for debugging or when frequent changes to lighting occur. r_lightmap_bicubic<bool> (only in
)- Enable bi-cubic (high quality) lightmap sampling.