Light Properties

From The DarkMod Wiki
(Redirected from Lighting A to Z)
Jump to navigationJump to search


For Doom 3 (and subsequently, The Dark Mod), there are 4 different types of lights at our disposal. Each has their own advantages and drawbacks, and hopefully this article will help to familiarize The Dark Mod hopefuls with their use. For information on creating lights and a lot of other useful information, see A - Z Beginner Full Guide Start Here!

Light Volume Properties

Point Light

A point light is the default light (also the default for fog). No option must be checked to make a light a point light. A point light casts light, and subsequently shadows in all directions evenly, falling off after a distance defined by the light texture. This works best for most small indoor and outdoor lighting, like lamps, candles, fireplaces etc. For this reason, it is going to be the most used type.

  • Note, a misconception about Point Light is that they project spherically. The box shaped bounding volume in Dark Radiant is no mere simplification, it is the literal area affected by the light for calculation purposes. Point Light volumes should be perceived as cylindrical prisms that on one axis are shaped by the silhouette of the projection texture (think of a stack of cheese cut with a cookie cutter) and the other axis (z-axis) traditionally determines the distance from origin brightness (usually vertical... or how tall you make your cheese stack) with the LightFalloffImage.
  • Note 2, as of TDM 2.05 cubicLight lights offer true spherical falloff.

Projected Light

Projected light is just as the name suggests. It is probably more intuitive and easier to use than a parallel light and is better for things like projecting a window-shaped light on the floor of a room or a spotlight on a wall. To make one, select projected instead of the default omni option at the top of the light inspector.

This creates a triangular prism as the bounding box for the light (instead of a rectangular prism like a regular light), with the point ending right at the entity itself. This can be rotated using any of the XYZ rotation buttons or manually using DarkRadiant’s rotation tool (shortcut R).

You can also manipulate the projected light via the vertices (shortcut V to enable vertices dragging). By dragging the vertices in the center of the projected square, you can lengthen and change the angle of the projection while keeping the projected square the same size. To resize the projection, use the two side vertices in the correct XYZ grid view. Making the bounding box flat against a surface (like a floor) is usually unnecessary (for example, making a moonlight window light on a floor or wall), because with shadows enabled and making the projection long enough to intersect the plane on which the shadow is to be cast, the full shadow will be cast (its simple geometry and just requires minor toying).

As with all the lights, projected lights have a full range of color and texture options to let the mapper find just the effect they need, allowing you to create a great atmosphere for your map.

  • As of TDM 2.06, cubicLight entities do not work properly with Projected lights. Please only use cubicLight with Point lights.

Parallel Light

A light is said to be parallel when the parallel checkbox is checked in the light inspector. It is subject to all the same options as a point light, but it has a few distinct differences. A parallel light tends to not care exactly where the entity itself is placed. The most important thing is where the light_center vertex is placed and where the light entities bounding box intersects with elements in your map.

The light_center vertex starts right in the middle of the entity. The main difference between the parallel and point lights is that a parallel light does not radiate from the origin around the entity itself. What controls the direction that shadows are cast is the placement of the light_center vertex. Shadows will run parallel (hence the name) to a line between this vertex and the light entity itself. This makes it an excellent choice for sunlight or moonlight. As such, it has some of the elements of a point light and a projected light, it can seem to radiate in a circle (if you use the appropriate texture) whilst casting a shadow in any direction preferred.

Switch to Vertex mode in DarkRadiant to drag the light_center vertex of your selected light entity.

Posted by Greebo: Also, note that a parallel light will only light surfaces "matching" the direction of the "light vector"
(origin minus light_center). All other surfaces will stay completely unlit, therefore it should be combined with an ambient light to
achieve good lighting effects. [1]

Parallel-sky light

The main problem with parallel light is that: while it does not radiate light rays from the light origin, the origin still matters when engine flows light rays through visportals. An ordinary parallel light always works properly in the visleaf where its origin is located. In addition to that, it takes effect in all the other visleafs which can be reached from the starting visleaf through visportals by travelling along the direction of the light. So in order to create a global moon/sun light which will light many outdoor areas, one has to create a separate visleaf above the outdoor areas, which would contain the light and have portals leading down to every outdoor area below. It is quite complicated.

In TDM 2.08, a new spawnarg parallelSky was added. If you add it to a parallel light and set value "1", then the light will emanate from every visleaf containing surfaces with textures/smf/portal_sky material. This usually includes all outdoors area automatically. Note that other (i.e. indoors) areas are also included if they can be reached from outdoors areas through open visportals, so the light should work correctly indoors if someone opens a door.

Troubleshooting Parallel Lights

I added a parallel light but I can’t see any light at all!

Parallel lights can have some quirks. The light seems to fail and do nothing when intersecting multiple walls that are parallel to the face the light is actually casting on. It seems the light will work as long as it doesn’t intersect a face parallel to the one it is casting light on.

I have a parallel light but it casts a jagged light on my floor!

Similar to above, a parallel light can sometimes have anomalies when intersecting multiple walls and a floor. Since having the light intersect multiple walls when it can only cast on one of them, having a massive bounding box is pointless anyways so pay attention to what the light is touching and you should be fine.

Light Interaction Properties

Normal Light

This is the default light type. It performs all the surface interaction stages and shadow calculations. It has the heaviest performance impact.


New as of TDM 2.05, it is similar to Normal Light but accepts a cubemap as the projection image and uses a spherical z-falloff pattern rather than a falloff image.

The shader was originally developed by Sikkpin the author of the soft shadows mod for Doom 3 "Sikkmod". Duzenko ported portions of it to GLSL.

CubicLight projection is used in many 3D engines with the most common parlance being "Cookie Lights". Unity "Cookie Lights" can be used as a reference.
(For comparison, I am not aware of any 3D engine other than id Tech 4 that used the 1D + 2D projection images.)

As of TDM 2.06, GLSL versions of this shader will only perform Point light (omni) operations. Projected is broken.

Ambient Light

Ambient light is really just a lighting texture, but it is also a specific item that is needed in practically every map, so for those purposes it will be treated as if it were its own subset of lights.

Properties: No shadows, No specular, Bumpmapping or Directionality (Note: The "Enhance Ambient" does add Bumpmapping )

Use the ambientLight keyword.

An ambient light can be any form: it can be a point, parallel or even projected (though projected would probably be useless).

The only requirement of an ambient light is to use one of the available ambient light textures, accessible by opening the light inspector (with the shortcut L in DarkRadiant, and get used to using it), and selecting ambientlightnfo from the list.

  • To understand The Dark Mod's unique ambient light detection system see: Virtual Darkness


New as of TDM 2.05. This is intended to provide an effect similar to Valve's "Precomputed Radiance Transfer" lighting in Half Life 2. It was originally developed by Sikkpin the author of the soft shadows mod for Doom 3 "Sikkmod".

In TDM 2.06, the new GLSL version of the shader (developed by Duzenko) accepts (industry standard) irradiance cubemap images.

  • A new image program "makeIrradiance" was also created to use existing skybox cubemap images.

Fog Light

This applies Doom 3's style distance fog to a light volume. The texture applied will become more opaque with distance away from the viewer. There is a variant called No Portal Fog which will not apply opaque fog to Portal areas in view. ( Beginner Tutorial: Fog )

In rare cases, you may wish for some surface inside a fog-volume to be fog-free. You can use the "noFog" keyword in the material definition for the texture applied to this surface to keep it from being "fogged".

Very thin fog (or BlendLight ) can also be used to soften the apparent light interactions near surfaces in a similar manner to the Post Process shader effect but with more mapper control. You can fake certain radiosity effects simply by amplifying small ambient light with small thin fog volumes.

Use the fogLight keyword.


Fog lights don't actually paint mist in the air, which would slow down performance quite a bit. They achieve their effect by fogging out the colour of the surfaces that they hit, proportionate to the depth of fog that lies between the player and the surface. In addition, if there is no surface between the player and the edge of the fog volume, they paint fog on the invisible walls of their own bounding volume. That's needed for a large open scene, for example, where there might be no surface between the player and the edge of the fog volume. If you're in a misty forest, and there happened to be no tree visible in a certain direction, you'd expect to see grey fog rather than clear space between the fogged trees.

Sometimes you don't want that to happen, for example if you're using a very large but very light fog to simulate atmospheric perspective in a town. You want the colour and detail of buildings to fade with distance, but you don't want heavy fog blocking the view of the sky in the gaps between buildings where you see to the very edge of the big fog light. You can use spawnarg "noFogBoundary" for that. It lets fog paint on solid surfaces, while leaving empty space and caulk sky free of fog effects.

noFog ( new 2.07 )

As of TDM 2.07, you can apply a noFog global material flag to the material def or the noFog entity spawnarg to the entity def and this will prevent fogging on these surfaces or entities.
Most visual fog issues are in cases where fog is "not" applied somewhere. Therefore, this is mostly a performance related argument or can be used as a special effects.

Blend Light

Blend lights can be considered to be like volumetric decals. They do not perform most of the interaction shader operations and merely apply a texture to a volume using an OpenGL Blend Mode. Blend lights have the least performance impact. Blend lights can also be used to create "negative light".

Example negative light shader:

 lightFalloffImage makeintensity( textures/blackdog/blendlight_falloff_inverse.tga )
 blend gl_zero, gl_one_minus_src_color
 map textures/blackdog/blackdog_icon_inverse.tga

Use the blendLight keyword.


You may use the "spectrum" keyword to isolate specific lights to specific materials which have the same spectrum value in their material definition. Spectrum Keyword at Modwiki
Note: Currently spectrum light is exclusive. This means that anywhere the the spectrum light does not touch (shadowed surfaces) will be completely black.
To avoid this issue, you would need to create an ambient light (basically a duplicate of ambient_world) with the same spectrum value as the target surface(s).

Light Settings

There are several settings with which to customize your lights. These settings allow the mapper to customize the look of a light (or a combination of lights) into a near infinity of looks. All are accessed through the light inspector (shortcut of L in DarkRadiant)


The color palette allows the mapper to pick the color of the light emitted, arguably one of the most useful controls the mapper has over a light. To access it, click the button under the “Colour” heading. From there, adjust the settings until you find a correct color (can take some trial and error). In a game like The Dark Mod or Doom 3, where darkness is often more prevalent than light, the color picked often needs to be darker than expected. Without a direct brightness option, the color takes on this task. For a low level ambient light, the color picked would be almost pitch black. A pitch black light would not cast any light, but anything less than pitch black will cast a faint light. As such, it can take some trial and error to find the correct light for a situation, as intiailly, one is likely to pick a seemingly correct color only to find it is far too bright.

Remember: changing light settings or adding lights (and models) does not require re-compiling the map!


The 'radius' of your light can be changed by dragging its corners around in the 2d windows. Doom 3 lights do not have an actual radius, they are actually square lights and will light up everything they touch inside their bounding box in the editor. They will evenly light everything to their edges. While square lights might seem fairly odd there are options to make them more believable and have a nice fade, namely the 'texture' applied.

Tip: you can rotate a light so only one corner will touch a wall and make a triangular shaped light. 
Or rotate it so 2 corners touch a wall and make a line of light.

Changing Radius of Light Entity:

If you put a premade light entity into your map, the radius of the light won't be visible.

To change it, use the following syntax (and whichever value you wish):

 "set _color on flame" "0.9 0.8 0.7"
 "set light_radius on flame" "250 250 250"

With lanterns and such use 'light' and with torches and candles etc use 'flame'.

 "set _color on light" "0.9 0.8 0.7"
 "set light_radius on light" "250 250 250"

(Copied from Baddcog's old "Lighting A to Z" article)


Selecting this option turns the light into a parallel light (as opposed to a point or projected light). See Parallel Light

Do not cast shadows (fast)

As the name suggests, this setting causes the light to not cast shadows on any object. This can cause the light itself to not be confined by walls, which can sometimes be beneficial and sometimes not. The main purpose of enabling this option is performance. Shadows are processor intensive and are not needed in some cases, so removing them wherever not beneficial to gameplay can vastly improve performance. Note that ambient lights never cast any shadows. Another way to improve performance similarly is to set the entity property on a model or func_static (this doesn’t work on worldspawn) noshadows to 1.

Skip Specular Lighting

Specular Lighting refers to a texture's specular map, wherein a flat surface (such as a wall) is painted with a texture that has a specular component. This causes a surface to have shinier and duller parts on a flat surface based on the darkness of the corresponding location on the specular map. Not all textures have specular maps. Checking this option could improve performance or remove the effect if it is not wanted. [2]

Skip Diffuse Lighting

Like Specular lighting, diffuse lighting also references an attribute of a texture, the Diffuse Map. Diffuse Maps determine the intensity and color of the light reflected off of the different elements of a texture (an example being the difference between bricks and the mortar in between, as well as different bricks having different properties as well giving a less bland appearance). [3]

Other light settings

AI sight

Spawnarg ai_see controls whether the light is visible to AI. It defaults to "1", i.e. the light does help AI to see. You can set this spawnarg to "0" to make accent lights that will (1) not affect the player's lightgem, and (2) won't make suspicious objects like rope arrows more visible to AI.


Typically chandeliers are setup with multiple particle flames, but just one light entity (for better performance). Bind the candles to the chandelier, then if one is doused, all will extinguish. (See the prefab for an example.)

Lighting Textures

Rich_is_Bored's Example

The lighting textures are also accessed in the light inspector.

Lights can be modified by two different texture types:

  • Projection Image - This is the texture that is projected on the surface
  • LightFalloffImage - This texture varies the intensity of the light through the volume along the Z Axis
  • (Notes: While the Falloff Image is a 2D texture it is rendered as 1D (one dimensional). You will notice that almost all Falloff Images are thin strips with perpendicular stripes. Traditionally, Falloff will be used to diminish the light with distance to the source but you can violate the physics of real lights and have the intensity increase with distance or vary intensity from bright to dim to bright... etc. )

These textures allow the mapper to change the intensity and falloff of a light.

Light textures with the addition of material keywords like scroll,rotate, etc. will grant lights the ability to animate and produce special effects such as;

  • A moving light for a fireplace
  • A candle or torch
  • A light flickering along with sound volume.

One can also apply a fog texture to the light (the only way built into Doom 3 to create fog). Color is of a similar concern when creating fog, as noted in Color

  • A typical "Light Shader" material definition


  lightFalloffImage makeIntensity( textures/My_Custom_Light1_Z ) // Falloff Image

  map textures/My_Custom_Light1_XY // Z-Projection Image


(For advanced detail and techniques see Light Textures and Falloff Images )

Further reading