lights.txt File Format

The lights.txt file is a file of light names and directions for X-Plane’s rendering engine. It is absolutely not meant for editing by the user and we take no responsibility for crashes or the file being overwritten during updates.

It is an ASCII .txt file with a header and body.

All text including and after a ‘#’ is a comment. There are no leading or trailing whitespace allowed.

lights.txt Header

Similar to other Laminar Research file formats, the lights.txt header is as follows

NEWLINE (A)

VERSION (850)

LIGHT_SPECS

TEXTURE <filepath to texture file>

lights.txt Body

• Each line of the body consists of a RECORD TYPE, a light name that may be shared with other records, and the contents of that RECORD TYPE.
• Light names match “[A-Za-z0-9_]+” and represent only 1 light – no “my_test_light” representing a red spill and a blue strobe.
• Each element of the line is separated by (usually 1) tab for readability. Spaces (please use 4) may be used but are strongly discouraged.
• All light’s “front” face is to the south (0, 0, 1) – if you are standing south of a light, looking north you’ll see it. Parameters for DX, DY, and DZ can change this.

RECORD TYPEs

There are two record types: OVERLOAD or LIGHT_PARAM_DEF. A light_name must have at least 1 OVERLOAD and may have 1 LIGHT_PARAM_DEF. Records should be grouped by light_name, bounded by an empty line. A LIGHT_PARAM_DEF must precede all OVERLOADs.

OVERLOADs

OVERLOADS are in the form of <OVERLOAD TYPE> <light_name> <matching number of arguments for prototype>

Arguments may be

– a number (in decimal notation), convertible to a float
– a dataref or NOOP to replace DREF, no surrounding quotes
– a parameterization-argument: One of the parameters from the light’s LIGHT_PARAM_DEF. Can be in any order in the arguments list and be used multiple times in the arguments list as long as the light has a LIGHT_PARAM_DEF.

Overload Type | Order of arguments and likely parameters used (spacing for readability, not to indicate an altered start index)
---------------|--------------------------------------------------------------------------------------------------------------------
BILLBOARD_HW   | <R> <G> <B> <A> <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL> <DX> <DY> <DZ> <WIDTH> <FREQ> <PHASE> <AMP> <DAY>
BILLBOARD_SW   | <R> <G> <B> <A> <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL> <DX> <DY> <DZ> <WIDTH>                            <DREF>
SPILL_HW_DIR   | <R> <G> <B> <A> <SIZE>                               <DX> <DY> <DZ> <WIDTH>                      <DAY>
SPILL_HW_FLA   | <R> <G> <B> <A> <SIZE>                                                      <FREQ> <PHASE> <AMP> <DAY>
SPILL_SW       | <R> <G> <B> <A> <SIZE>                               <DX> <DY> <DZ> <WIDTH>                            <DREF>
SPILL_GND      |                 <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL>
SPILL_GND_REV  |                 <SIZE> <CELL_SIZE> <X_CELL> <Y_CELL>

light_name has been omitted. (Although LIGHT_PARAM_DEF and an OVERLOADs params and arguments lists look like a function declarations and partially applied functions, the names are just for humans. The order used is what truly matters. To keep consistent, the format specifies our conventions.)

OVERLOAD Types

• BILLBOARD_HW – A hardware accelerated billboard.
• BILLBOARD_SW – A dataref driven billboard, NOOP may be used.
• SPILL_GND, SPILL_GND_REV – old v8-style quads-on-the-ground light spill for runway lights.
• SPILL_HW_DIR, SPILL_HW_FLA – hardware spill, directional’ or flashing. We can’t have both due to a lack of light params.
• SPILL_SW – dataref driven spill, NOOP may be used

OVERLOAD Parametrization Restrictions

The following are tables of what columns of an OVERLOAD’s prototype are allowed to be parameterized. The column names are conventions only based on common uses of these columns. This is unrelated to the content and order of LIGHT_PARAM_DEFs or the overload’s argument.For example

A light has SIZE in the LIGHT_PARAM_DEF and a BILLBOARD_HW overload with “SIZE” 1st column (commonly known as the R column) and 1.24 in the 5th column (commonly known as the SIZE column). The common labels for the columns and their contents are meaningless.

LIGHT_PARAM_DEFs

LIGHT_PARAM_DEFs are in the form of LIGHT_PARAM_DEF <light_name> <count greater than 0> <parameters list of count length>. Every parameter must be unique. A LIGHT_PARAM_DEF’s params list can be in any order but is strongly suggested to follow the order in each OVERLOAD type.

Regular Parameters

These are: R, G, B, A, SIZE, DX, DY, DZ, WIDTH, FREQ, PHASE, INDEX, and DIR_MAG. INDEX represents the index in the light’s dataref’s array. It is only used in airplane_ lights. DIR_MAG is only used in airplane_nav_left/right/tail_size to indicate it is using the “directional magnitude” method of calculating the WIDTH column, instead of the usual method.

Special “Hint” Parameters

Some parameters give clues to tools and X-Plane on what their values should be, despite being parameters. They can be used multiple times (by appending a '_' for each duplicate).

• UNUSED: Replacement placeholder for deprecated parameters, commonly replaced with 0.
• NEG_ONE, ZERO, ONE: Some light’s parameter’s only ever make sense to use a hard coded value like -1, 0, or 1. A prime example is airplane/generic/landing/taxi lights’ RGB parameters which are actually used for aiming the light, but the light should only ever be aimed at (0, 0, -1). Tools and X-Plane can use this metadata to avoid making artists know this obscure fact.

An example: old_light’s parameters list was once LIGHT_PARAM_DEF old_light 9 R G B A SIZE DX DY DZ WIDTH, but now is expressed as LIGHT_PARAM_DEF example_light 9 ZERO ZERO_ NEG_ONE UNUSED UNUSED_ DX DY DZ UNUSED__. This way tools and X-Plane knows only DX DY DZ matters anymore, and “each parameter is unique” is satisfied in an easy to read and parse way. Software can help the artist and user accordingly.

ARGUMENTS explained

• R, G, B, A – The color tint applied to the light spill or billboard. Since light is additive, A is really just a master dimmer.
• SIZE – The total size in meters for spill, or a ‘size constant’ for billboards you’ll have to play around with to get right.
• CELL_SIZE, CELL_ROW, CELL_COL – A triplet of ints (size, row, column where 0,0 is the lower left) for billboards. Size is a power-of-two multiplier for cell size. Thus a double-size cell in the top right corner is 2 7 3 (because the 1024 x 512 texture can be divided into a 8 x 4 grid of 128×128 pixel cells).
• DX, DY, DZ: Direction vector for directional billboards and spill lights – should be normalized
• WIDTH: For billboards, a constant term between 0 and 1 that makes a billboard more omni directional the closer it gets to 1. For spill lights: cos(1/2 * view_angle).
• FREQ, PHASE, AMP, DAY: Frequency, phase offset, amplitude, and day/night flag for flashing lights
• DREF: For software lights, the dataref that “processes” the light.

NOTE: if a hardware or software billboard has negative size, then it is axial. In this case: the direction is the axis of rotation (the billboard hangs off in that
direction. The axis should be normalized. The ‘width’ parameter is used as a scaler, e.g. larger numbers are more focused.

More notes on frequency:

1.  “frequency” of flashing in Hz ( number of flashes per second, 0.2 mean a flash every 5 seconds)
2. “Phase offset” in seconds (so you can make two flashing lights that don’t flash at the same time, this value controls how late the flashing pattern starts from light OFF
3. “amplitude” of the flash, flash is a triangle wave, but with amplitude 1.0 the lights pulse (going from 0 to 1 and back to 0)
   but if you pick a huge amplitude like 10.0 x-plane will automatically subtract 9 (to keep the light from going crazy) the result is….a strobe!
   if you set the amplitude to 0.5 then x-plane will add a bit so even at its DARKEST the light will still be 50% ON, so you can make some tricks with the amplitudeALEX SAYS: Flash amplitudes GREATER THAN 1000 now invoke a square-wave flash behaviour. The pulse width ratio is calculated as (amp – 1000)/1000 %.
   In other words, every integer over 1000 represents one millicycle. E.g. amp = 1500 gives a pulse width of 50%, amp = 1020 gives a pulse width of 2% etc.
   Amplitudes less than 1000 still invoke the existing “strobe” scheme.
4. parameter: “daytime vs night-time” ratio. if it is 1 the light will be ON during the day and night, if it is 0 light will be ON only at night.