View source for General information about Black Mesa new lights

{{TabsBar|main=Black Mesa Deferred Lights}}
This page covers general information about new lighting system from {{bms|4}}, that was added since {{xe|4}} update and often used by the game and modifications with map packs. Read this page before reading information about all the new light entities, this will help reader to better understand how the system is done and used by the entities. Entity pages stores information specific to these entities, such as keyvalues. There is also subpage about bugs/limitations for the systems and entities, it is also recommended to read first (after this main page).
{{note|This page doesn't cover purely theoretical information, only information can be used when working with new light entities.}}

==Deferred lighting==
Deferred lighting is a dynamic lighting rendering method with high quality and low performance reduce. Used gbuffer and multiple rendering passes to apply lighting properly, this makes it possible to achieve more realistic lighting without forward rendering. Supported reflections with refractions and other second cameras. Unlike [[light_dynamic|dynamic lights]] from [[Source SDK]], this lighting doesn't use [[lightmaps]]. The lighting uses bump-aware shading (generated by [[Bump map|normal maps]]), this allows lighting properly illuminating models and world geometry. This lighting also provides realistic light falloff compared to {{ent|env_projectedtexture}}. All lightmap dynamic lights from Source SDK are replaced with new deferred lighting, projected texture entity is removed, flashlight is using deferred lighting.
<gallery mode=packed heights=310px>
File:deferredlight_dlight0.jpg| frame |Dynamic light from {{hl2|4}} (the sprite shows current light position).
File:deferredlight_dlight1.jpg| frame |Dynamic light from {{bms|4}} (the sprite shows current light position).
</gallery>

The lighting also provides various effects, dynamic shadows (by using shadowmaps) and lightcookies.

==New light entities==
The main entities used in {{hammer|4}} are {{ent|newLight_Point}} and {{ent|newLight_Spot}}, {{code|newLight_Point}} used for omnidirectional light, {{code|newLight_Spot}} used for spot cone light. Both provide lots of settings, many of them are exclusive. There is also {{ent|light_dynamic}} entity, a more simple version of {{code|newLight_Point}}, there are many entities with the ability to create code generated new lights, weapons for examples.

There is also {{ent|newLight_Dir}} entity for the godrays in 2D skybox, {{ent|newLights_settings}} to change various lighting keyvalues, {{ent|newLights_Spawner}} to spawn many light sources in multiple rows, {{ent|newlights_gbuffersettings}} to set some gbuffer settings.

See relevant pages for more information about these entities and keyvalues.

==Lightcookies==
===What is a lightcookie texture ?===
Lightcookie (a. k. a. "Texture Light") a texture or mask applied to a light source. It is usually used to shape the light's output or fake shadows with specific patterns (which, unlike shadowmaps, can be translucent and look more accurate). It also can be used for stuff like projectors, cautists, disco spheres, etc.

In Black Mesa, it can be used via "'''Texture name for TexLight''' ''(texName)''" property (to specify the texture) and "'''Enable Texture Light''' ''(bTexLight)''" (to enable the feature). 

This game used lightcookies mainly for fake shadowmaps and cautists. They are used for some entities by default ([[Item battery (Black Mesa)|batteries]] and grunt pods for example).

<gallery mode=packed heights=290px>
File:lightcookie0.jpg |Lightcookie is disabled.
File:lightcookie1.jpg |Lightcookie is enabled.
</gallery>

Lightcookies are disabled with 2 ('''Low''') value for {{cmd|nr_shadow_quality}} ('''Dynamic Shadow Quality''').
===Texture mask===
The texture mask defines which pixels will display the lighting and also affects their color. Black pixel color will not render the light at all, white will render the light and its color value, other colors (red, blue, yellow, etc.) will be mixed with the light color value, depending on their intensity and how close they are to white. Alpha channel doesn't affect anything, so make sure you don't use it in your texture. 

Point lights requires "Environment Map" texture to work with lightcookies, because point lights are using 6 separate faces, so each face requires separate texture. Follow [[$envmap#Creating_a_custom_static_cubemap_texture|these steps]] to create "Environment Map" texture.

Spot lights can use any texture basically.

It is recommended to use '''No Mipmap''' and '''No Level Of Detail''' flags for your [[VTF]] file, so the texture will not cause aliasing issues.

<gallery mode=packed heights=290px>
File:lightcookie_aliasing.jpg |Two point lights with two different lightcookie textures. The left don't use the flags, unlike the right texture.
</gallery>

{{important|Lightcookies are not using [[VMT]] materials, you only need texture.}}

===Animation===
{{ent|newLight_Spot}} entity also supports 2 different animation types, which allows to animate a texture in two different ways.

====Texture Cookie FPS====
In this mode, a spot light will split image into specified amount of frames (so called atlases) and change frames with specified speed (FPS).

The splitting of specified texture into separate parts is done using two-dimensional arrays (in this context, this can also be called a two-dimensional table). The value from '''TexCookieFramesX''' (''TexCookieFramesX'') creates the specified number of rows, the value from '''TexCookieFramesY''' (''TexCookieFramesY'') creates the specified number of columns. 

The final number of frames is the value from '''TexCookieFramesX''' multiplied by '''TexCookieFramesY'''. For example, value 3 in both '''TexCookieFramesX''' and '''TexCookieFramesY''' will split image into 9 parts.

<gallery mode=packed heights=290px>
File:Background01.jpg |''console\background01.vtf'' original image.
File:background01_lightcookie_spit.jpg |''console\background01.vtf'' splitted into 9 parts (3 by 3).
</gallery>

The spot light will change frames from top to bottom and left to right. The frames from the top row are shown first, the spot light passes over them from left to right, then moves down to the next row. If it showed the last frame, it will restart the process. The amount of time it takes to move to the next frame depends on specified value from '''TexCookieFps''' (''TexCookieFps'').

====Texture Cookie Scroll Mode====
In this mode, lightcookie texture can scroll in X and Y directions. This feature can be enabled with '''Tex Cookie Scroll Mode''' (''bTexCookieScrollMode'') property.

X direction controlled by '''ScrollSpeedU''' (''fScrollSpeedU'') property. Y direction controlled by '''ScrollSpeedV''' (''fScrollSpeedV'') property. Both takes a float value. The default X direction is left, Y is up. Using a value multiplied by -1 will reverse direction, this allows you to use 8 different scroll directions. 0 means don't move in this direction. The size of the value affects the scroll speed.

Here is the [https://youtu.be/FkUFF6CLTq8 video] showcase of all 8 directions and how the feature look like.

{{note|Combing this mode with previous will result in using first atlas frame for scroll mode.}}

==Shadow Mapping==
To cast dynamic shadows, Black Mesa uses {{WP|shadow mapping}} (shadow maps for short) technique for new point and spot light entities when '''HasShadow''' property is enabled. Used local shadowmap camera and [[Depth buffer|depth buffer]].
<gallery mode=packed heights=310px>
File:BmsShadowMapBuffer.jpg| frame |Flashlight's shadowmap camera in depth buffer.
File:BmsShadowMapFinnal.jpg| frame |The final image.
</gallery>
Spot light uses only one camera, while point lights 6 for 6 different directions to make more accurate shadows for omnidirectional light, this is why it takes 6 shadowmap slots ([[NewLight_Point#Shadow_map_slots|see below]]) and 6 times the cost of new spot light. You can disable each shadowmap individually for a new point light entity.

The shadowmaps stored in a large shadowmap atlas, which makes having lots of shadowmap textures a lot cheaper for GPU. There is two of them, one for static shadowmaps ([[NewLight_Point#Static_shadow_maps|see below]]) and one more for dynamic shadowmaps.
<gallery mode=packed heights=410px>
File:BmsShadowMapAtlas.jpg| frame |One of the shadow atlases.
</gallery>

Because shadowmap is a texture with limited amount of pixels in it, distance from the light source and objects makes it less accurate a distance.
<gallery mode=packed heights=410px>
File:BmsShadowMapDist1.jpg| frame |Small distance between the light source and [[Npc barney|Barney]]'s model.
File:BmsShadowMapDist2.jpg| frame |Large distance between the light source and [[Npc barney|Barney]]'s model.
</gallery>

Shadow [[Field of View|FOV]], which can be changed with '''OuterAngle''' property or '''ShadowFOV''' property, also affects shadowmap quality. Due to the pixels spread, shadows are less accurate with large FOV values.
<gallery mode=packed heights=410px>
File:BmsShadowMapFovQ1.jpg| frame |60 '''OuterAngle''' value.
File:BmsShadowMapFovQ2.jpg| frame |170 '''OuterAngle''' value.
</gallery>

There is 3 shadowmap resolutions, small (256), medium (512) and big (1024). Higher values create sharper, more accurate shadows, but cost much more to render. Sharp shadows may not be appropriate for all situations either, sometimes soft shadows look more accurate. They are defined by '''ShadowMapLOD''' property, which uses hard coded choice (0, 1, 2), this is why it's not possible to use custom shadowmap resolutions. Each shadowmap resolution takes one shadowmap slot.
<gallery mode=packed heights=310px>
File:ShadowMapLOD256.jpg| 510px | 256
File:ShadowMapLOD512.jpg| 510px | 512
File:ShadowMapLOD1024.jpg| 510px | 1024
</gallery>
The edges of the shadows can be made smoother (or more stepped) with '''ShadowRadius''' property. It determines the radius of shadow edges for soft shadows. If its value is negative, code will auto assign a value depending on ShadowLod. These code based values can be adjusted via convars {{command|nr_shadow_rad_High}}, {{command|nr_shadow_rad_Med}} and {{command|nr_shadow_rad_Low}}.
<gallery mode=packed heights=290px>
File:ShadowRaduis1.jpg| 510px | ShadowRadius - 0.0001
File:ShadowRaduis2.jpg| 510px | ShadowRadius - 1
File:ShadowRaduis3.jpg| 510px | ShadowRadius - 5
</gallery>

The '''NearZ''' distance used by shadowmap camera (distance at which the light source will start cast shadows) can be controlled with '''NearZ''' property. The '''FarZ''' distance uses value from '''Range''' property.

Console variable {{cmd|nr_shadow_quality}} sets shadow quality and enable/disable shadows for all or certain objects. Controlled by Dynamic Shadow Quality option. Only 5 values are available for it:
* 0 (Disabled) - Shadows and lightcookies are completely disabled.
* 1 (POTATO) - Shadows are available for world geometry and displacements, only for Static and Stationary light types. The shadows are very pixelated. The player's flashlight also gets very simple shadows with "stairs".
* 2 (Low) - Added brush entities and static props in shadowmaps, only for Static and Stationary light types. Enabled lightcookies.
* 3 (Medium) - All the shadows are also available for Dynamic light type.
* 4 (Hight) - Added dynamic models in shadowmaps for Stationary and Dynamic. 

Console variable {{cmd|nr_shadow_res}} affects the quality of shadows. Controlled by Dynamic Shadow Memory option. Only 4 values are available for  it: 
* 0 (Hight) - Hight quality.
* 1 (Medium) - Medium quality.
* 2 (Low) - Low quality.
* 3 (POTATO) - Very low quality. 

{{bug|hidetested=1|If there are too many shadowmaps in a frame, this can lead to laggy shadow atlas update.
{{todo|How many ?}}
}}

===Shadow filtering===
Versions of the game before Necro Patch uses PСF filter. The shadow edges are sharper and exhibit a more distinct transition. There are visible aliasing artifacts, particularly on the edges. Shadows from small or thin objects were also indistinguishable. However, it was pretty good for shadows with low resolution, because they looked blurry. The shadows are somewhat similar to those that can be seen from the [[projected texture|projected textures]] in {{portal2|4}}.
<gallery mode=packed heights=410px>
File:shadowfilter_old.jpg| frame |Barney's hand with old shadow filtering.
</gallery>
The Necro Patch replaced PСF filter with PCSS filter. The shadow edges appear smoother and less jagged. The transition from the shadow to the lit area has more gradient-like softening. Shadows have become more detailed for small objects. Because of this, you have to adjust the shadows more carefully.
<gallery mode=packed heights=410px>
File:shadowfilter_new.jpg| frame |Barney's hand with new shadow filtering.
</gallery>
This filter has one significant issue: there is now noticeable noise in the shadows. This is mostly noticeable in low resolution shadows, this spoils them quite a lot (although it makes them more detailed). There is no way to disable this effect. The noise also makes the shadows more similar to shadows from flashlight in {{hl2|4}}. It is worth noting that such thing exists in more modern engines ([https://en.wikipedia.org/wiki/Unreal_Engine Unreal Engine 5] for example, even though they are not easily visible due to [[Anti-aliasing#TAA/TSSAA|temporal anti-aliasing]] smoothing the artifact), so you can ignore the noise if it's not very noticeable, especially on shadows with high quality.

The noise is adjusted via ShadowRadius and ShadowMapLOD values, mainly via ShadowRadius; you even can disable the noise with 0 value, but this will make your shadows will look like stairs/pixels. 
<gallery mode=packed heights=310px>
File:shadowfilter_new1.jpg| frame |The noise example.
</gallery>
{{note|It is not entirely clear which term is correct, '''PCSS''' or '''PCCS''', since it could be orgography, but it is possible (though unlikely) that they created their own filter.}}

===Static shadow maps===
If our light source remains in the same position and never changes it, we expect that shadows from world geometry, [[displacement]], {{ent|prop_static}} and even [[bmodel|bmodels]] (brush entities) are completely static, this means that we don't need to update shadows for them every frame, so it would be nice to bake shadows for all such objects to save performance. This is why we need static shadow maps. 

When your light appears, static shadow maps skip all the dynamic models in their pass and take 1-6 pictures of everything mentioned above, then static shadow maps applies to the lighting from the light source and never change again (until save reload).

This doesn't happen if your light source is disabled, so you need to keep it enabled on spawn around 1 second. If you need disabled light source - set intensity value to 0 and then after 1 second turn off light source (don't forget to set required intensity value).

Static shadow maps are used for Static and Stationary light type. For Stationary type, engine also disable shadows passes in dynamic shadows for everything mentioned above, so that the use of static shadow maps makes sense (this still saves performance quite well). Dynamic light type don't use static shadow maps at all, because it can move, so we need to have dynamic shadows for everything.

Important to note that bmodels are also in static shadows maps, including {{ent|func_physbox}}, {{ent|func_door}}, {{ent|func_breakable}}, etc. This is true, despite the fact that such objects can be removed or moved. Most likely this is due to {{ent|func_detail}}, which is very similar in principle to regular world geometry, but cannot be removed or moved, unlike all other brush entities. It gives some problems, because shadows from lab doors or elevators will remain static, while these objects are moving. There are 2 good ways to workaround this issue, "lazy" method and " time-consuming" method. The first is very simple and quick, just use Dynamic light type, this will reduce performance but will completely fix the problem and save your time. The second is using [[Propper]] with converting your brush to model, you'll need spend time on {{ent|propper_model}} setting and brush replacing, but this will also save performance and solve the problem.

===Shadow map slots===
Shadow map slots is how many lights with shadows you can have per level. There are 3 separate shadow map slots, <code>High</code> (for lights with <code>1024</code> value for <code>ShadowMap LOD</code> property), <code>Medium</code> (for lights with <code>512</code> value for <code>ShadowMap LOD</code> property) and <code>Low</code> (for lights with <code>256</code> value for <code>ShadowMap LOD</code> property).

In <code>High</code> and <code>Medium</code> you can have 48 separate shadow maps, for <code>Low</code> you can have 47 separate shadow maps (143 shadow maps in total).

Each spot light with shadows takes 1 shadow map slot, so you can have 48/47 spot lights with shadows, if they are using the same value for <code>ShadowMap LOD</code> property.

Each point light with shadows takes 6 shadow map slots, because point light uses 6 separate shadow maps to render shadows. This means that you can have 8 point lights with shadows, if they are using the same value for <code>ShadowMap LOD</code> property. You can increase this value if you need, just disable shadows for one of the shadow face properties.

If one of the shadow map slots is full - you will not be able to have shadows for more lights with such shadow quality, you will need to use other value for <code>ShadowMap LOD</code> property.

Point lights and spot lights doesn't counts separately. You can't have 48 spot lights with 8 point lights, but you can have 6 spot lights with 7 point lights.

You can free up shadow map slots with <code>Kill</code> input. So, you can place triggers which will <code>Kill</code> lights that player can't see and spawn new lights via {{ent|point_template}} (uncheck the second flag for {{ent|point_template}}, this prevents some bugs). This helps a lot when you want to have many dynamic lights in different areas.

Important to note that due to some engine bugs you can't use many lights with shadows. Some tests show that 9th point light cause lights with shadows to be very glitchy. This can be done with spot lights as well. So don't be surprised if at some point you find something like this.
<gallery mode=packed heights=410px>
File:manyshadowslotsbugg.jpg| frame |The bug example.
</gallery>

It looks like you can workaround it if you will switch <code>ShadowMap LOD</code> property values from higher to lower.

{{tip|You can use {{command|nr_debug_print_shadow_slots_info}} to get full info about shadowmap slots.}}

===Shadow map passes per frame===
Instead of using the current value from the [[FPS]], shadows use the value from {{cmd|nr_shadow_max_passes_per_frame}} console variable. It stagger the updation of shadow maps, for both static and dynamic, over a few frames. This feature adjustable via '''Dynamic Shadow Memory''' graphics settings. This solution preserves performance, since instead of using 300 from FPS value, the shadow will be updated only 24 times per second, which is enough to display most scenes in dynamic shadows.
{{bug|hidetested=1|'''"End Game"''' chapter crashes at some moment with 29 and higher values.}}

===Shadows behavior with [[VIS]] and [[areaportals]]===
====Static type====
Static type is the most stable, since its shadows are baked in and updates only with save loads or while lighting  turning on. It shows all shadows even with closed [[areaportal]].
<gallery mode=packed heights=410px>
File:staticlight_0.jpg| frame |Areaportal is open.
File:staticlight_1.jpg| frame |Areaportal is closed.
</gallery>
====Stationary type====
Shadows for static props and brushes are baked, but not for physics props and other dynamic models. This means that shadows from dynamic models will disappear if they are hidden by a closed areaportal or if [[VIS]] is hiding such objects. Shadows for static props and brushes will not disappear.
<gallery mode=packed heights=410px>
File:stationlight_0.jpg| frame |Areaportal is open.
File:stationlight_1.jpg| frame |Areaportal is closed.
</gallery>

In some cases, this can be noticeable if dynamic model creates a large shadow.
<gallery mode=packed heights=410px>
File:Theboxshadow_0.jpg| frame |Areaportal hides the box, note that there is no shadow.
File:Theboxshadow_1.jpg| frame |Areaportal shows the box, now there is a shadow of the box.
</gallery>
With {{command|mat_wireframe|1}}.
<gallery mode=packed heights=410px>
File:thewireboxshadow_0.jpg| frame |Areaportal hides the box.
File:thewireboxshadow_1.jpg| frame |Areaportal shows the box.
</gallery>

====Dynamic type====
Shadows for static props and world geometry are baked, but not for dynamic models and brushes. This means that shadows from dynamic models and brushes will disappear if they are hidden by a closed areaportal or if [[VIS]] is hiding such objects. Shadows for static props and world geometry will not disappear. Moving lighting will update shadows for static props and world geometry, even with closed areaportal.
<gallery mode=packed heights=410px>
File:dynlight_0.jpg| frame |Areaportal is open.
File:dynlight_1.jpg| frame |Areaportal is closed.
</gallery>

===Player spawn and areaportals===
If player spawned in position where areaportal don't hide objects - shadows will be fine. Otherwise, static shadowmap will not see models with [[bmodel|bmodels]] and will bake shadows only for world geometry and displacements. This problem is not relevant only for Dynamic light type. The problem disappears after save reload from proper position.
<gallery mode=packed heights=410px>
File:psaa_0.jpg| frame |Player spawned in position where areaportal don't hide objects. The columns are {{ent|func_detail}}, the pipes are {{ent|prop_static}}.
File:psaa_1.jpg| frame |Player spawned in position where areaportal hide objects. Note that the columns and pipes don't have any shadows.
</gallery>

===Shadows behavior with start/end fade dist for prop_static===
This mechanic has some issues with static shadowmaps. It seems that there are limitations that don't allow to fix these issues, or this issues was not noticed at the development stage.
====Static type====
If player spawns in fade radius - shadows will never disappear (until save reload if out of radius).
<gallery mode=packed heights=410px>
File:fadepropstaticlight_1.jpg| frame |In radius.
File:fadepropstaticlight_0.jpg| frame |Out of radius.
</gallery>
If player spawns out of radius. - shadows will never appear (until save reload in radius).
<gallery mode=packed heights=410px>
File:fadepropstaticlight_3.jpg| frame |
</gallery>
The same for props with both Start and End fade dist.
====Stationary type====
The above mentioned issues are also available for this type.

Appears issue for prop_static with both Start and End fade dist.

If player spawns in Start fade radius - shadows will never disappear (until save reload if out of radius). The same happens if player spawns in End fade radius.

If player spawns out of radius - shadows will appear if you are in End fade radius and disappear if you are in Start fade radius (until save reload in radius). This happens because prop_static actually disappears completely, and creates a separate object as a fading model (this is also why decals disappear if player is out of Start fade radius).

<gallery mode=packed heights=210px>
File:fadepropstatiorlight_1.jpg| frame |In radius.
File:fadepropstatiorlight_2.jpg| frame |Out of Start fade radius.
File:fadepropstatiorlight_3.jpg| frame |Out of End fade radius.
</gallery>

====Dynamic type====
Dynamic type don't use static shadowmaps at all. This means that there is no problems with fading prop_static at all.
{{important|All the issues are also available for {{ent|func_lod}}.}}

==Godrays==
===Implementation===
Godrays in this game are based on [[Sprite|sprite]] entities and not [[Volumetric lighting|volumetric lighting]]. They are a post-processed 2D plane that always turns to player's camera. The size of such plane is consistent with the screen size making it appear larger at a distance, in comparison to the world, similar to how '''Glow''' render mode works for {{ent|env_sprite}}, but unlike the render mode, such plane is rendered so that the sprite will cut through any surrounding geometry, similar to how '''Additive''' render mode works for {{ent|env_sprite}}.
<gallery mode=packed heights=210px>
File:grandsprite_0.jpg| frame |Sprite.
File:grandsprite_1.jpg| frame |Godrays.
</gallery>
This plane is also not affected by VIS, which means that the player will always see it, even if the area in which the light source is located is closed by an areoportal.
<gallery mode=packed heights=290px>
File:cRaysDraw.jpg| thumb | left | 510px |  
</gallery>
Such implementation has several  consequences that limits amount of cases when you can use it.

Godrays are available as an optional parameter for {{ent|newLight_Point}} and {{ent|newLight_Dir}} entities. {{ent|newLight_Point}} can include both, godrays and lighting with shadowmaps. Both entities provide many keyvalues to control how godrays interact with world in screen space, they also provide '''ColorRays''' keyvalue to set the color.

A single map can handle 40 point lights with godrays and 1 directional light with godrays. Exceeding the limit will cause the game crash with engine error. The limit can be extended by removing old lights with '''Kill''' input and spawning new using {{ent|point_template}}.

===Disk===
Godrays are using 2 disks which is implemented primarily to emit sun circle, without using {{ent|env_sun}} or other tricks. The first disk is outer disk, the main disk. The second disk is inner disk, displayed in outer disk radius.

The size of outer disk is defined by '''DiskRadius''' keyvalue, this is percent of the screen space the disk will take.  The size of outer disk the outer disk size multiplied by percent of the place that will take inner disk, the percent  is defined by '''DiskInnerSizePercent''' keyvalue.

The color for outer disk is controlled by '''ColorInner''' keyvalue, the color for inner disk is controlled by '''ColorOuter''' keyvalue.

Disks can be disabled by setting 0 value for their size parameters.'''RenderInWorldSpace''' can be used for the same effect (if {{ent|newLight_Point}}).
<gallery mode=packed heights=290px>
File:DiskInnerSizePercent0point7.jpg| thumb |Inner and outer disks example. The inner is red, the outer is white.
</gallery>

===Types===
There are 2 types of godrays (and disks), '''Normal''' and '''Fancy'''. Normal godrays are regular godrays effect. Fancy godrays can be used for {{ent|newLight_Point}} entity only, they are spinning pulsing rays with lot of keyvalues for them.
<gallery mode=packed heights=290px>
File:cGodRaysTypeNormalAlt.jpg| thumb | Normal
File:cGodRaysTypeFancyAlt.jpg| thumb | Fancy
</gallery>

===Limitations and use tips===
Local point light godrays can "leak" (example on the pictures), since nothing limits the rendering and the size of the plane. The only you can do is place triggers that will turn on/off godrays, but this also basically means  you can't use godrays in multiplayer levels, because multiple players can be located in different places of your map (there is no way to disable godrays for each client separately).
<gallery mode=packed heights=310px>
File:godraysleak0.jpg| frame |
File:godraysleak1.jpg| frame |
</gallery>
Because godrays always turns to player's camera, make sure you are using this effect in areas where view angle for player is very limited. The reason is showed in this short video [https://youtu.be/YvhWpE_X4RU clip], note how battery stops processing at some moment.
<gallery mode=packed heights=310px>
File:godrayslimiting0.jpg| frame |Bad example, player's view angle is not limited, the player also can walk around in any direction. Both factors are making godrays leaking and bad clipping most of the time.
File:godrayslimiting1.jpg| frame |Good example, player can look at the godrays forwardly only. The player also can walk only back or forward in this area. Both factors making the godrays nice looking.
</gallery>
{{note|Everything mentioned is this paragraph here also applies to the disks.}}

==Lighting effects==
There are various effects for deferred lighting, some of them optional and customizable.

===Specular===
If this feature is enabled, deferred lighting will create [[PBR]] styled specular glossy effect, which can be seen on smooth, polished surfaces, like metal. Deferred lighting creates it on materials with enabled [[$phong]] or the [[$specmap texture|new specular]] shader. While [[$phong]] works only with models, new specular can also be applied to world geometry. Comparing to [[Cubemaps|cubemaps]], specular from deferred lighting is physically accurate, this means that the gloss effect position and shape directly depends on current player and light source position, it is also affected by dynamic shadows and specular from other light sources.
<gallery mode=packed heights=512px>
File:NewSpecular=.jpg |New specular shader, example in <code>bs_c3m0d</code> map from Black Mesa: Blue Shift. Note how the floor reflects the red light source, the same for the floodlight.
</gallery>
The new specular shader primarily uses [[specularmap]] mask and has 3 different modes.

See [[$specmap_texture]] page for more information about the shader and how to use it.
{{note|Most code generated lights (temporary entity lights for instant) are not using specular effect for better performance.}}

===Halflambert===
There is [[$halflambert]] effect for deferred lighting separately, this adds a fake ambient lighting to a model. It is activated by default (only if {{command|nr_lights_quality}} is 3 and higher and if [[$phong]] is enabled), that's why there is {{ent|$halflambert_gbuffer_off}} parameter that allows to turn this effect off. Although it is enabled by default, it is recommended to disable it for most cases, due to issues with shadows. This effect looks good for objects that never cast any dynamic shadows, such as {{ent|blackmesa_viewmodel}} or entities with permanent attached lights such as {{ent|npc_plantlight}}.

See [[$halflambert_gbuffer_off]] page for more information.
<gallery mode=packed heights=290px>
File:gbufferhalflambert_on.jpg|Gbuffer's half lambert is enabled. Shadows are disabled.
File:gbufferhalflambert_off.jpg|Gbuffer's half lambert is disabled. Shadows are disabled.
</gallery>

===Warping===
Deferred lighting and new specular are using custom warping implementation for diffuse lighting and specular. It's similar to [[$lightwarptexture]] material parameter, but uses global atlas for the texture and combos made of the atlas.

See [[$warpindex_diff|$warpindex_diff / $warpindex_spec]] page for more information and how to use warping.

<gallery mode=packed heights=290px>
File:gbufferWarping_off.jpg|Specular warping is disabled. Unused.
File:gbufferWarping_on.jpg|Specular warping is enabled. Used combo number 6.
</gallery>

==Optimization==
Deferred lighting provides high performance, better than {{ent|env_projectedtexture}} and {{ent|light_dynamic}} from [[Source SDK]]. The only factors that directly affects performance are lighting range and amount of lights in frame. Unlike lightmapped lights, any light style/appearance can be used with no harm for performance.

The lighting also uses [[Bounding box|BBOX]] volume to disable itself if the player don't see the '''BBOX''' anymore. The '''BBOX''' size for point light is the same as range for the light/ For spot light it uses math to set up proper '''BBOX''' size and position for it, the size and position depends on spot light position, angle direction and range.

For shadowmaps, it depends on their quality, amount of shadowmaps in atlas, amount of dynamic shadows, amount of rendered objects and shadow passes per frame.

Godrays are using samples with no ability to change the amount of samples. Large amount of samples in a single frame can significantly reduce performance, it directly depends on the amount of samples in the frame.

==General use tips==
These are tips for level designers and level creators.

===Static lightmapped lights are remaining the main lighting in the level===
New lights don't replace lightmapped lights, they are only additional lights that can look better when need beautiful dynamic shadows, moving lights, or rare cases when lightmap doesn't look good enough.

===Don't use more range when needed===
The intensity may not lit rest of the range, but range will still use increased [[Bounding box|BBOX]] and render more in gbuffer when needed, this can affect performance.

===Remove or turn off lights with shadows===
Shadowmaps have hardcoded limit, they also reduce performance because they're updated every certain amount of frames. Use ''TurnOff'' input to disable the light or ''Kill'' to remove the light entity entirely, the ''Kill'' is also needed when required a new lighting source with shadows spawn.

===Use {{ent|point_template}} to workaround hardcoded shadows limitation===
This is useful if needed many lights with shadows for different areas. Don't use this tip in multiplayer maps if multiple players are able to be located in different map areas.

===Don't use high quality shadows if not needed===
Sometimes the 256 value or 512 looks good enough, but also saves performance.

==Dedicated [[ConVars]]==
{{varcom|start}}
{{varcom|nr_allow_hammer_nerfs|0|[[Integer]]|Allow new lights nerfs via {{ent|Newlights_gbuffersettings}} entity.

0 - Disabled.

1 - Allowed.

2 - Enabled/Forced.
}}
{{varcom|nr_allow_hammer_nerfs_4ways|0|Integer|Allow {{code|Enable4WaysFastPath}} property from {{ent|Newlights_gbuffersettings}} entity.

0 - Disabled.

1 - Allowed.

2 - Enabled/Forced.
}}
{{varcom|nr_shadow_max_passes_per_frame|16|[[Float]]|Frame per second in shadowmaps. The higher the value, the smoother and faster the shadows from objects can change. The recommended value is 24-28, not higher.}}
{{varcom|nr_shadow_quality|4|Integer|Sets shadow quality and enable/disable shadows for all or certain objects. Controlled by '''Dynamic Shadow Quality''' option. Only 5 values are available here.

0 (Disabled) - Shadows and lightcookies are completely disabled.

1 (POTATO) - Shadows are available for world geometry and displacements, only for '''Static''' and '''Stationary''' light types. The shadows are very pixelated. The player's flashlight also gets very simple shadows with "stairs".

2 (Low) - Added brush entities and static props in shadowmaps, only for '''Static''' and '''Stationary''' light types. Enabled lightcookies.

3 (Medium) - All the shadows are also available for '''Dynamic''' light type.

4 (Hight) - Added dynamic models in shadowmaps for '''Stationary''' and '''Dynamic'''.
}}
{{varcom|mat_unlock_gfx_highend_unsupported|0|[[Bool]]|When enabled this convar will unlock extreme graphics options. There will be a significant FPS drop when running game on ULTRA or INSANE configs. Game will consume upto 3 gigs of VRAM when some of the extreme graphics options have been enabled. These high end graphics config options are not officially supported. Don't enable this unless you have at least 3.5 GHZ quad core CPU with GTX 1080. These options are mainly for debugging and modders.}}

{{varcom|nr_lights_quality|4|Integer|Sets lights quality, state (for specific entities), enable/disable effects. Controlled by '''Dynamic Light Quality''' option. Only 7 values are available here.

0 (POTATO) - Disabled muzzle flash light (regardless of {{command|muzzleflash_light}}), lighting from batteries (regardless of {{command|cl_battery_dlights}}), light sources from [[dynlightscript.txt]], dynamic lights are also disabled for some other entities. Halflambertion is disabled. New specular is disabled. Bumpmaps are disabled. Lights are disabled completely in secondary cameras (monitors, water, etc). Overlaying on viewmodel looks pretty broken. Light is not smoothed out (most noticeable in the least bright areas).

1 (Low) - Allowed muzzle flash light, lighting from batteries, enabled light sources from [[dynlightscript.txt]], other dynamic lights are also enabled for some other entities. Enabled bumpmaps for models.

2 (Medium) - Enabled bumpmaps for brushes. Lights in secondary cameras, but most effects is disabled.

3 (Hight) - Halflambertion with new specular is enabled. Fixed overlaying on viewmodel. Light is smoothed out.

4 (Very Hight) - Bumpmaps are also uncompressed, this makes lighting on surfaces more detailed.

5 (INSANE) - All the effects is enabled in secondary cameras.

6 (DevOnly) - This one for developers only. Includes uncompressed buffers and 32-bit depth. Don't use if you are general player or modder.
}}
{{varcom|nr_shadow_res|0|Integer|Affects the quality of shadows. Controlled by '''Dynamic Shadow Memory''' option. Only 4 values are available here.

0 (Hight) - Hight quality.

1 (Medium) - Medium quality.

2 (Low) - Low quality.

3 (POTATO) - Very low quality.
}}
{{varcom|nr_shadow_res_dkvk|0|Integer|It doesn't seem to work.}}

{{varcom|r_4way_minimal_mode_override|-1|Integer|Enable/disable bumpmaps for {{ent|Lightmapped_4WayBlend}}. Since one material of this shader provides 4 bumpmaps at once, disabling them will significantly affect performance.

-1/0 - Enabled.
1/2 - Disabled.
{{note|This cvar needs {{command|mat_reloadallmaterials}} to see changes.}}}}
{{varcom|np_gr_quality|2|Integer|Enable/disable godrays. Controlled by '''God Rays''' option or '''Enable God Rays''' button (if used [[VGUI]]).

0 - Disabled.

1/2 - Enabled. 1 supposed to enable godrays only for {{ent|newLight_Dir}}, 2 for both point lights and {{ent|newLight_Dir}}, but currently both values enable both types.}}
{{varcom|np_gr_quality_sample_count|3|Integer|Amount of samples for godrays. This affects the quality/detail of the rays. Controlled by '''God Rays''' option, although the original game never changes the value (always 3). Min value is 0, max is 4. The max value is not recommended, it has a huge impact on frame rate, at the same time it does not create a big difference in the game.}}
{{varcom|np_gr_quality_pass_count|1|Integer|Pass count. Not very clear what exactly this affects, but it significantly reduces performance, and Fancy Rays also become pretty buggy. Controlled by '''God Rays''' option, although the original game never changes the value (always 1). Min value is 0, max is 4. Use the default value only.}}

{{varcom|nr_gbuffer_for_reflection_enabled|1|Bool|Enable/disable gbuffer for water reflections.}}
{{varcom|nr_gbuffer_for_refraction_enabled|1|Bool|Enable/disable gbuffer for refractions.}}
{{varcom|nr_gbuffer_for_secondary_cams_enabled|1|Bool|Enable/disable gbuffer for secondary cameras (monitors, etc).}}
{{varcom|nr_gbuffer_for_secondary_cams_quality|-1|Bool|New lights quality in secondary cameras and water reflections. With -1 it will use quality from {{command|nr_lights_quality}} cvar. With 0-5 it will use itown quality settings (in the same way as {{command|nr_lights_quality}}).}}

{{varcom|nr_shadow_filter_quality|2|Integer|Sets shadow filter quality. Min value is 0, max is 3.

0 (POTATO) - Shadow filter disabled.

1 (Medium) - Medium quality.

2 (Hight) - Hight quality.

3 (INSANE) - Best filter quality.

}}

{{varcom|nr_shadow_rad_Low|1.0|Float|Sets shadow filter quality scale for lights with 256 ShadowLOD value.}}
{{varcom|nr_shadow_rad_Med|1.5|Float|Sets shadow filter quality scale for lights with 512 ShadowLOD value.}}
{{varcom|nr_shadow_rad_Hight|1.5|Float|Sets shadow filter quality scale for lights with 1024 ShadowLOD value.}}

{{varcom|nr_shadow_biasoverwrite|0|Bool|Used by [[New Lights Editor]]. Allows/disallows to overwrite bias related values.}}
{{varcom|nr_shadow_nearz_overrite|-1.0|Float|Used by [[New Lights Editor]]. Changes NearZ value for all new lights.}}
{{varcom|nr_shadow_rad_override|0|Bool|Used by [[New Lights Editor]]. Allows/disallows to overwrite shadow radius related values.}}
{{varcom|nr_shadow_fov_overrite|-1|Float|Used by [[New Lights Editor]]. If the value of this convar is higher than -1 it will overrite FOV for shadowed lights.}}
{{varcom|nr_shadow_biasdepth|0.0002|Float|Used by [[New Lights Editor]]. Changes Depth Bias value for all new lights.}}
{{varcom|nr_shadow_biasnormaloffset|1|Float|Used by [[New Lights Editor]]. Changes Normal Bias value for all new lights.}}
{{varcom|nr_shadow_biasslope|0.2|Float|Used by [[New Lights Editor]]. Changes Slope Depth Bias value for all new lights.}}
{{varcom|nr_shadow_active|666|Integer|Sets max active shadowmaps. The value seems hardcoded.}}


{{varcom|nr_debug_print_shadow_slots_info||[[Void]]|Prints text to the console about shadowmap slots and their light sources.

It prints light type (point or spot) with their index, shadowmap enabled state (for each face), shadowmaps number, new light's targetname and position of it.

Below it also prints information about free shadowmap slots for each shadow resolution.
}}


{{varcom|nr_debug_force_shadowmap_res|-1|Bool|Only for debugging. Forces all new lights to use specified shadowmap resolution. -1 means use value from the property.}}
{{varcom|nr_debug_force_dynamic_on_all_stationary_lights|0|Bool|Only for debugging. Forces all stationary new lights to be fully dynamic and update even baked shadows.}}
{{varcom|nr_debug_force_lightstyle|0|Integer|Only for debugging. Forces all new lights to use specified appearance/light style. Possible values are 0-13. 13 for custom style from {{command|nr_debug_force_lightstyle_custom_string}}. 0 means use use value from the property.}}
{{varcom|nr_debug_force_lightstyle_custom_string|1|[[String]]|Only for debugging. Forces all new lights to use custom appearance/light style. Works the same as with lightmapped lights.}}
{{varcom|nr_debug_shadow_render_internal_disable|0|Bool|Only for debugging. Forces all new lights to disable shadowmaps rendering.}}
{{varcom|nr_debug_shadow_print_indices_assignment|0|Bool|Only for debugging. Prints text to the console about all new light sources and shadowmaps after level/save loading.}}
{{varcom|nr_debug_lights_mesh|0|Bool|Only for debugging. Enable/disable new lights mesh.}}
{{varcom|nr_debug_lights_mesh_fullscreen|0|Bool|{{todo|}}}}
{{varcom|nr_debug_light_mesh_volumesize_large|0|Bool|Only for debugging. Enable/disable new lights large mesh volume size mesh.}}

{{varcom|nr_debug_cull_deferred_lights|1|Bool|{{todo|}}}}
{{varcom|nr_debug_cull_deferred_code_lights_via_bsp|1|Bool|{{todo|}}}}

{{varcom|nr_dev_shoot_lights_enabled|0|Bool|Enable/disable point lights on each shoot. Only for player and only for bullet weapons. Shotgun can create several at once. Disappears after save reload.{{warning|Kills performance.}}}}
{{varcom|nr_dev_lights_quality_override|0|Bool|Enable/disable light quality override. Required for some cvars with {{code|nr_dev_}} prefix.}}
{{varcom|nr_dev_gb_debug_type|4|Integer|0 - DepthOnly. 1 - GBuffer_Fast 2 - GBuffer_Fast2. 3 - GBuffer_Fast3. 4 - Gbuffer_Slow.}}
{{varcom|nr_dev_gb_quality|2|Integer|Changes gbuffer quality.}}
{{varcom|nr_dev_lb_quality|1|Integer|0 is broken. 1 - default mode. 2 - debug materials with new specular.}}

{{varcom|nr_disable_setting_auto_reload|0|Bool|{{todo|}}}}

{{varcom|nr_fps_spam|0|Bool|For devolopers only. Spamming in the console performance values. Numbers aren't accurate.}}

{{varcom|nr_light_spot_bbox_optimizie|2|Intenger|Sets BBOX type for spot lights. Min value is 0, max is 3. There are note that 1 is broken. 3 makes BBOX size very small, so spot light sources will disappear even if they are in the player's field of vision.}}
{{varcom|nr_light_spot_mesh_volumesize_large|0|Intenger|This makes BBOX larger than it needs to be.}}

{{varcom|nr_lights_info||Void|Used by the game when you launch it. Prints in the console info about hardware support for texture formats, allocated formats and quality settings.}}

{{varcom|nr_lights_vol_check_threshold|10|Float|{{todo|}}}}
{{varcom|nr_light_settings_transition_exp|2|Integer|Affects the quality of the transition for changes from {{ent|newLights_settings}}. 0 - no transition. 1 - transition. 2 - smooth transition.}}

{{varcom|nr_lights_procedural_disable_all_lights|0|Bool|Disable all proceduraly created new lights ({{ent|npc_zombie_hev}}, {{ent|item_battery}}, weapons, etc).}}
{{varcom|nr_lights_procedural_enable_lights_priority_check|1|Bool|If enabled - all the code based procedural lights will go through priority based check before adding to render queue.}}

{{varcom|r_nr_deffered_debug_normals|0|Bool|Enable/disable normals debug.}}
{{varcom|r_nr_deffered_force_diffuse_only|0|Bool|Forces new lights to use diffuse texture only.}}
{{varcom|r_nr_deffered_lights_hlslclip_range_on|1|Bool|Enable/disable actual new light range in normals debug.}}
{{varcom|r_nr_deffered_lights_hlslclip_dir_on|0|Bool|{{todo|}}}}


{{varcom|r_nr_deferred_AA_fix_multiplier|1|Bool|Fixes anti aliasing issues.

:{{expand|title=Example|
<br>
<gallery mode=packed heights=500px>
File:deferred_AA_fix_multiplier0.jpg| thumb | left | 510px | Disabled.
File:deferred_AA_fix_multiplier1.jpg| thumb | left | 510px | Enabled.
</gallery>
}}
{{varcom|sv_ignite_light_mode|2|Integer|Sets fire light source availability for ignited objects. Min value is 0, max is 3.

0 - Fully disabled.

1 - Available for marines, doesn't work.

2 - Available for all NPCs.

3 - Available for everything, including physics objects and player.
{{bug|Doesn't work with {{ent|env_shooter}}.|hidetested=1}}

}}
}}

{{varcom|end}}
{{note|
* It's not full list.
* Some of these console variables needs save reload for changes.
}}

==Bugs/Limitations==
See the [[/Bugs and limitations|subpage]].

==See Also==
This page takes a major part of the information from articles by Chetan, the programmer responsible for creating new graphics features in Black Mesa.
* [https://chetanjags.wordpress.com/2023/07/18/blackmesa-xenengine-part-4-lighting-shadows/ BlackMesa XenEngine: Part 4 – Lighting & Shadows] - page from Chetan (lead programmer for Black Mesa) about new lights.
* [https://chetanjags.wordpress.com/2023/07/11/blackmesa-xenengine-part2-how-a-frame-is-rendered/ BlackMesa XenEngine: Part2 – How a Frame is Rendered] - page from Chetan (lead programmer for Black Mesa) about how a frame is rendered.
* [https://chetanjags.wordpress.com/2022/06/01/blackmesa-xenengine-part1-a-heavily-modified-source-engine/ BlackMesa XenEngine: Part1 – Heavily Modified Source Engine]  page from Chetan (lead programmer for Black Mesa) about {{xe|4}}.