$lightmap

Stub

This article or section is a stub. You can help by adding to it.

$lightmap is a material shader parameter available on the VertexLitGeneric shader in the following Source games or engine branches:
Source 2013 Multiplayer and  Garry's Mod. It defines a lightmap to be used to light the MDL model's material, instead of the per-vertex lighting used by prop_static or point lighting used by other models.

This parameter does not usually need to be added manually, as VRAD will generate model lightmaps automatically if generatelightmaps is enabled for the prop_static and -StaticPropLighting is enabled in VRAD. Nonetheless, it can still be added manually, such as for using a lightmap on a prop_dynamic, or if a prop_static has multiple materials (as VRAD can only generate lightmaps for the first material.

Tip: VRAD has a -dumppropmaps option, which will create external TGA versions of the generated static prop lightmaps which can be converted to VTF and manually defined as a $lightmap.

Todo: What about converting static prop lightmaps from already-compiled maps? They are stored as PPL files, which have a slightly different header from VTF or TGA.

VMT syntax

$lightmap <texture>

models/lightmapped/example.vmt

vmt

VertexLitGeneric { $basetexture "models/lightmapped/example_base" $lightmap "models/lightmapped/example_lightmap" }

Limitations and caveats

Warning:Models use the same UVs for lightmaps as $basetexture; as such, lightmapping on models with overlapping or tiling UVs may not appear as intended!

Warning:Lightmaps for models with multiple materials do not compile properly in VRAD!^[Clarify]

Workaround: Define a pre-baked $lightmap in the VMT of the VertexLitGeneric material.

Warning:Model lightmaps generated with VRAD are compiled as RGBA8888, which can result in noticeable color banding when brightly lit in HDR mode.

Workaround:

• Define a pre-baked^[How?] RGBA16f $lightmap in the VMT of the VertexLitGeneric material.
• Increase lightmap resolution (results may vary).

Note:This issue may also appear when placing any light source too close to a surface.

Warning:Models using $bumpmap cannot receive lightmaps, they will fall back to vertex-lighting.

Note:There is an in-engine check that confirms whether or not the $bumpmap parameter is defined for a material, a custom shader cannot simply use both as there are a dozen technicalities that have to be overcome.

If $bumpmap or $phong is defined, the engine will not send the lightmap data to the shader.
For $bumpmap, a workaround for this is to use a differently named parameter. ( $NormalTexture ) to get the normal map and undefining $bumpmap.
However no static lighting data can be received by the shader, if the $bumpmap parameter is not set to anything. This refers to lights that are not named and are not inherently dynamic.
This may be prefered as the static light information is ALREADY prebaked in the lightmap, however it means you cannot receive direction information from the lights.
No light direction means no bumped lighting from the lightmap. Aka no specular highlights.
A fix for this would be modifying VRAD to spit out a lightmap that is *2 the size on the U axis and then storing an average light direction there or doing some other smart technique to 'memorize' light directions.

This in-engine check also exists for $phong, however getting around the issue is more tricky. The default value of the integer parameter will be 0 even if not set in the vmt. Thus making $phong always be defined in a way.