This document explains the key features to understanding lighting parameters and their affect on the rendering system. This page is taken from the BF2_lighting.doc in the ModTools documentation.

Getting Light Into The Game

There are two ways in which a light can be placed into a game:
-Through an attached ODF
-By placing a light in the editor.
The preferred method for adding lights is through the editor so we have all the lighting information in one place. If you need a light to be animated then it is better to attach the light to animatable object through the objects ODF.

Attached Lights

In order to create a light in the game there must be either an associated light ODF or .fx file. The ODF or .fx file holds all the parameters for a light. Lights can then be attached to hard points on an object through ODF parameters. Light ODFs or .fx files are also responsible for putting a light beam or light flare on a light. The follow lists all the different type of light parameters that can be used. Parameters and values for ODFs are such that Parameter = Value and for .fx files such that Parameter(Value) where Value doesn't take quotes for multiple values but instead separates them with commas.

Parameter Value Description
Color "<red[0-255]> <green[0-255]> <blue[0-255]> <alpha[0-255]>" Color of the light; alpha used to modulate the brightness without distorting the hue but is not required.
OmniRadius <radius in meters> Sets the radius of the point light. Radius of 0.0 will turn off the point light, but leave the light beam and flare active.
Static <0 or 1> If specified, the lighting system will assume this light has already been burned into the terrain and any vertex lit objects in the area. It will only affect non-vertex lit objects like vehicles and soldiers.
BeamIntensity <intensity[0.0-1.0], 0.0 disables> Sets the brightness of the light beam effect, independent of the point light or light flare effect.
FlareIntensity <intensity[0.0-1.0], 0.0 disables> Sets the flare brightness relative to the light. Flares have some performance cost, so disable when possible.
FlickerType <value>
0 or None
1 or Strobe
2 or StrobeRandom
3 or StrobeFade
4 or Pulse
5 or Flicker
no flicker
on/off regularly every <FlickerPeriod> seconds
on/off randomly 0 to <FlickerPeriod> seconds
on and fade out every <FlickerPeriod> seconds
fade up/down every <FlickerPeriod> seconds
randomly chooses an intensity every <FlickerPeriod> seconds
FlickerPeriod <period in seconds> Controls the period for the FlickerType
ConeLength <length in meters, 0.0 disables> Sets the length to the inner arc of vertices (start of fade)
ConeInitialWidth <width> or "<width x> <width z>" for oblong head Sets the light beam effect to be cone shaped with the specified with in meters at the light source end.
ConeWidth <width> or "<width x> <width z>" for oblong tail Sets the light beam effect to be cone shaped with the specified width in meters at the far end.
ConeFadeLength <length[0.0-1.0] in meters> Sets the light beam effect to be cone shaped with the given percentage of the length used for fading out; defaults to 0.2. Larger values will create a rounder end; smaller values will create a squarer end.
ConeFadeFactor <fade[0.0-1.0]> Sets the light beam effect to be cone shaped with the given intensity fade factor at ConeFadeLength from the light source end; defaults to 0.2. Larger values will create a sharper or looking end on the beam.
HaloRadius <radius in meters, 0.0 disables> Sets the light beam effect to be halo shaped – i.e. round regardless of the view direction – with the given radius in meters before the final fade out.
HaloFadeLength <length[0.0-1.0] in meters> Sets the light beam effect to be halo shaped with the given percentage of the length used for fading out; defaults to 0.5. Larger values will enlarge the bright center with a correspondingly smaller fade out band.
HaloFadeFactor <fade [0.0-1.0]> Sets the light beam effect to be cone shaped with the given intensity fade factor at HaloFadeLength from the center; defaults to 0.2. Larger values will brighten the halo in the ring between the center and the outside edge.
DrawDistance <distance> Sets the distance at which this light beam will fade out. EntityLights always fade out by the end of the near scene, but may fade out sooner if needed.

Below shows the comparison of the BF2_ModTools/assets/worlds/HOT/odf/hothlight2.odf, an elliptical light beam, in its ODF form to what it would look like in .fx form.

ClassLabel            = "Light"

Color                = "65 65 30"
ConeLength            = 8
ConeWidth            = "4.0 6.0"
ConeInitialWidth        = "0.8 3.0"
ConeFadeFactor            = 0.3
ConeFadeLength            = 0.1
FlareIntensity            = 0
FlickerType            = 0
FlickerPeriod            = 1.0
OmniRadius            = 0
Color(65, 65, 30);
ConeWidth(4.0, 6.0);
ConeInitialWidth(0.8, 3.0);

Below are some examples of various types of lights and effects along with the light ODF parameters. These examples only show snippets of the ODF parameters, such as color and radius, that can be set to whatever the user desires.

Example 1

FlareIntensity = 1.0
BeamIntensity = 0.0
OmniLightRadius = 0.0
ConeLength = 1.0
ConeWidth = 5.0
ConeInitialWidth = 1.0

Turns off the light beam and light, but leaves a flare. The ConeInitialWidth and ConeWidth parameters control the size of the flare when looking at it from the side versus directly down the axis, respectively.

Example 2

ConeLength = 10.0
ConeFadeFactor = 0.3
ConeFadeLength = 0.6

Creates a beam with a very diffuse rounded end. You probably want to decrease the fade factor a bit if you make the fade length small.

Example 3

ConeLength = 10.0
ConeFadeFactor = 0.05
ConeFadeLength = 0.05

Creates a beam with a very square bottom edge. You probably want to decrease the fade factor a bit if you make the fade length small.

Example 4

ConeWidth = "2.0 4.0"
ConeInitialWidth = "0.5 1.0"

Specifies an oblong light beam which has aspect ratio 2.0. If you only specify one value, you'll get a circular source or cone.

Editor Lights

There are 4 types of lights: ambient (includes top and bottom), directional light, point (omni) light, and spot light. There are some common parameters to all lights types and each type has additional parameters that affect only that type.

Light Parameters

Editor Parameters


Dir Light Icon Size
Spot/Omni Icons
Show Real Lighting


the size of the directional light icon
whether or not to display in wireframe or solid mode
turns lighting on and off

Common Parameters


Casts Shadows
Wrap Mode
Blend Mode (PS2 only)


whether or not the light should cast shadows
whether the light has been burned into ALL "-vertexlighting" objects (this is explained more in the section below)
a texture that acts as a mask for the light
the wrap mode for the texture
how the light texture should be blended
the color of the light

Directional Parameters


Bounding Region


the name of a region. Only objects in the region will be affected by the light. The name should be the region name you type in the "Type" edit box. If no name is specified it will affect all objects.

Omni Parameters




the size of the omni light

Spot Parameters




the length of the spot light
the inner cone angle of the light
the outer cone angle of the light
whether or not the spot light should have a double cone (useful for light becon

Global Light Settings

The global light settings are lights that are always present unless excluded by a "Shadow" region. The global light settings are described below.


Directional Light 1
Directional Light 2
Top Ambient
Bottom Ambient
Environment Map


The name of the directional light that should be considered a global light
the name of a second directional light that should be a global light
The ambient color that comes from the top of the world
the ambient color that comes from the bottom of the world
the environment/reflection map that environment mapped objects should use

Shadow Regions

A shadow region redefines how to interpret the global light settings. You can create a shadow region by placing a region and setting its type to "Shadow". The shadow region properties let you attenuate each directional light, set new ambient colors, and assign a new environment map for that region.

Misc Topics

  • Each object can only be affected by at most 1 ambient light, 2 directional lights, 4 omni lights (3 on PS2) and 1 spot light. If more lights affect an object then a heuristic is used to choose the "best" lights to use.
  • Statically lit objects (any msh tagged with -vertexlighting) take lighting from non-static lights (any light that isn't marked as static). However it is required that these objects are vertex lit offline. Static lights include ambient light. Start by painting all vertices the ambient color and then selectively add areas of light.
  • Shadowed lights should not overlap
  • Areas that have local shadows should be more tessellated for better shadow fading

Glow (or HDR)

Glow will bloom bright light sources that you specifically tag under the lighting drop down box in the edit flags. The HDR effect is off by default. All parameters are adjustable from the console with the prefix "HDR." Below is a description of all the parameters along with their default values:

Enable(0)               // whether or not the hdr effect should be enabled
DownSizeFactor(0.25)    // what fraction of the back buffer to use when bloom (smaller means 
                        // better framerate - don't go below 0.25)
NumBloomPasses(5)       // the number of blur passes higher numbers means bigger blooms and
                        // is more costly
MaxTotalWeight(1.2)     // the amount to over-brighten the glow areas
GlowThreshold(0.5)      // value at which a pixel is considered to be blooming lower values
                        // mean more pixels will be blooming
GlowFactor(1.0)         // a factor used to dim the overall appearance of the bloom (probably
                        // better to use less bloom passes or less total weight)

Attaching lights to materials

This is used for when you want some emissive polygons to animate according to the light intensity. In the mesh option file specify the following:

-attachlight "<nodename> <lightname>"

<nodename> is the name of the xsi node that contains the geometry you want to animate
<lightname> is the name of the light (you specify the name of the light in the light odf - see docs)

NOTE: the quotation marks are needed!

Removing/Adding light to a vertex lit object

This is used if you already vertex lit a mesh and you want to brighten/darken it. You can specify how much light to add/subtract in the mesh option file using the following option:

-ambientlighting "r=<-1.0-1.0> g=<-1.0..1.0> b=<-1.0..1.0>"

The r,g,b parameters specify how much light to add/subtract from each color channel.

NOTE: the quotation marks are needed!

Shadow parameters

I added some parameters that globally effect shadows. Below is a description of the parameters along with the default values:

Enable(1)               // whether or not shadows should be enabled
BlurEnable(0)           // whether or not to blur the shadows
Intensity(1.0)          // intensity of the shadow


Blur will be off by default now if you want to enable it add it to the .fx file. It would be better if it was not used because it is expensive, not worth the cost and it is better to enable features such as HDR and soft shadows. I'm considering removing it from the game because the HDR effect does similar processing.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License