View source for $lightmap

{{this is a|shader parameter|shader=VertexLitGeneric|name=$lightmap|game=Source 2013 MP|game1=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 {{ent|prop_static}} or point-based vertex lighting used by other models.

This parameter does not usually need to be added manually, as [[VRAD]] will generate model lightmaps automatically if {{mono|generatelightmaps}} is enabled for the [[prop_static]] and {{mono|-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 and skin).
{{tip|<ul><li>{{src13mp}} [[VRAD]] has a {{code|-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 {{mono|$lightmap}}.
<li>For already-compiled maps, the lightmaps are stored as [[PPL]] files. These can be converted to [[VTF]] using [https://files.gamebanana.com/bitpit/proptexelvtf.exe Ficool2's proptexelvtf.exe (direct download)].
<li>If {{code|$lightmap}} is used to manually define lightmaps for a {{ent|prop_static}}, disable vertex lighting for the prop ({{code|disablevertexlighting}}) to prevent [[VRAD]] from wasting time calculating lighting for the prop and generating a [[VHV]] file that will ultimately go unused and waste space.
</ul>}}
{{codenote|The [[VertexLitGeneric]] shader code for lightmapped props from {{src13mp}} can be backported to {{src13sp}}, but the lightmaps will need to be explicitly defined in the VMT, rather than generated as [[PPL]] files by [[VRAD]].}}
{{bug|tested={{dods}}|Sometimes $lightmap won't load.}}
__TOC__
==VMT syntax==

 $lightmap <[[texture]]>

{{codeblock|lang=vmt|src=models/lightmapped/example.vmt|<!--
-->[[VertexLitGeneric]]<nowiki>
{
	</nowiki>[[$basetexture]]	"models/lightmapped/example_base"<nowiki>
	</nowiki>'''$lightmap'''		"models/lightmapped/example_lightmap"<nowiki>
}</nowiki> }}

== Limitations and caveats ==

{{warning|Models use the same UVs for lightmaps as [[$basetexture]], and the model's lightmap is affected by [[$basetexturetransform]]; as such, lightmapping on models with overlapping or tiling UVs may not appear as intended!<br>VRAD cannot create lightmaps for UVs outside of the 0-1 UV space.<br>Additionally, shadows may appear on UV seams; this is more noticeable on lower-resolution lightmaps.}}<!--
-->{{bug*|Lightmaps for models with multiple materials do not compile properly in [[VRAD]]! A lightmap will only be compiled for the first material on the model, that is a combined version of all the UV's used by all materials.<!--
    -->{{workaround|Define a pre-baked {{ent|$lightmap}} in the [[VMT]] of the [[VertexLitGeneric]] material (can be obtained using {{code|-dumppropmaps}} in [[VRAD]]).}}<!--
-->}}

{{warning|Model lightmaps generated with [[VRAD]] are compiled as RGB888 (24-bit SDR) [[PPL]] files which can result in noticeable color banding when brightly lit in HDR mode.<!--
    -->{{workaround|<ul><li>Define a pre-baked RGBA16161616f {{ent|$lightmap}} in the [[VMT]] of the [[VertexLitGeneric]] material. A custom-coded compiler would be required to this accurately (and could also create RGBA16161616f PPL files instead, which will work with vanilla shaders).<!-- Technically a lightmap could be baked in Blender, but that would be a pain to set up. --><!--
    --><ul><li>{{gmod|4}}'s [[VRAD]] now bakes RGBA16161616f [[PPL]] files in addition to the traditional 24-bit SDR RGB888 PPL files.{{ref|1}} [[VRAD]] bakes and packs both PPLs in maps (during the {{code|-hdr}} and {{code|-ldr}} stages respectively) and will swap between them depending on the client's currently selected HDR mode. {{code|-dumppropmaps}} has also been updated to output [[PFM]] files in addition to the traditional [[TGA]]s, both being dumped to a new folder located at {{path|steamapps\common\[[gmod|GarrysMod]]\garrysmod\sp_lightmaps}}.</li></ul><!--
    --><li>Increase lightmap resolution (results may vary).<li>Move light source further away from the lit surface.</ul>}}<!--
-->}}

{{warning|Models using [[$bumpmap]] cannot receive lightmaps, they will fall back to vertex-lighting based upon the models' origin or [[$illumposition]].<!--
    -->{{codenote|There is an in-engine check that confirms whether or not the {{ent|$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.

{{Expand|noborder=1|title=Technical|
If {{ent|$bumpmap}}, {{ent|$normalmap}}, or {{ent|$phong}} is defined, the engine will not send the lightmap data to the shader.<br>
For $bumpmap, a workaround for this is to use a differently named parameter. ($NormalTexture) to get the normal map and undefining $bumpmap.<br>
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.<br>
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.<br>
No light direction means no bumped lighting from the lightmap. Aka no specular highlights.<br>
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.}}
{{workaround|This can be sidestepped by modifying VRAD to bake the normal map data directly into the lightmap via a {{code|%NormalMap}} texture, akin to {{idtech3}} [https://github.com/Garux/netradiant-custom/tree/master/tools/quake3/q3map2 Q3Map2's] {{code|q3map_normalImage}}. The lightmap will need to be as high resolution as the normal map, but this is made up for by the normal map never entering VRAM (in fact, it won't even need to be shipped with the map!).}} }}<!--
-->}}

== See also ==
* {{ent|$detailblendmode|8}} - Can be used on the [[UnlitGeneric]] shader to simulate lightmaps in all Source engine branches.
* {{ent|Modulate}} - A shader that can be used to fake lightmaps or vertex coloring in all Source engine branches. It can bypass some of the limitations of {{code|$lightmap}}, but requires additional setup to look convincing.

{{references|1=
{{ref2|cite id=1|These features were implemented following {{code|garrysmod-requests}} issue [https://github.com/Facepunch/garrysmod-requests/issues/2464 #2464]
}}
}}

[[Category:Shader parameters|l]]