This document describes the parameterized lights available in OBJ files for the use on aircraft. Please first read “Billboard and spill lights for objects” if you are unfamiliar with the concept of billboard and spill lights, or named and parameterized lights in an OBJ file.
This document lists only the parameters for a given parameterized light, e.g. if the document lists:
happy_light <red> <green> <blue>
you would actually have
LIGHT_PARAM happy_light <x> <y> <z> <red> <green> <blue>
in your OBJ file. Most 3-d programs only require you to enter the name and params, so that is what is listed.
General Conventions for Aircraft
X-Plane supports the following types of external lights:
- Landing lights – used to provide runway illumination and visibility to other traffic in the air. They are very bright!
- Taxi lights – used to light up the ground in front of the aircraft while taxiing. Often the taxi light steers with the nose gear to illuminate the ground in front of them.
- Generic lights – these are bright external lights that can be used for any purpose. (They are ‘generic’ – you pick their use.) Typical uses would include: leading edge lights, tail logo lights, engine inlet lights, etc.
- Anti-collision strobes – these are bright strobes, typically on the wing tip used to make the aircraft visible to other traffic in flight.
- Rotating/strobing beacons – these are red beacons on the top and bottom of the aircraft, typically turned on when the engines are on. Some planes use rotating beacons, while others use strobing beacons. X-Plane provides different light types for each.
- Navigation lights – these are small lights: red for the left wing, green for the right wing, and white for the tail, that allow pilots to tell the direction and orientation of another plane in flight. (“Red on right, dead on sight”, because a red light on the right means the plane is headed directly toward the viewer.)
X-Plane supports the following internal lights for the cockpit:
- “Panel” lights, meant to simulate a flood, post, or some other exterior light source that illuminates part of the cabin. Map lights and flood lights fall under this category.
- Instrument lights – these control the brightness of specific instruments. Authors sometimes use instrument lights to control the brightness of back-lit text on an overhead panel, or even to simulate post lights.
For exterior lights, X-Plane always provides separate billboard and spill parameterized lights. Use one of each to create the complete lighting effect. Having the billboard and spill separate allows you to:
- Use two billboards for one spill to make a light ‘cluster’. Overlapping spills can hurt frame-rate, so it is best to use one large spill, not several small ones. For example, an airliner with two bulbs in the wing-mounted landing light would be a good candidate for two billboards, one spill.
- Use a spill without any billboard. For example, a billboard might not be desirable for a light where the actual bulb is recessed.
By convention, spill lights usually end in the suffix _sp.
For interior lights, only spills are provided; at this time we recommend not using billboards on the inside of the aircraft. (Use a _LIT texture to create the lighting of the light source itself. Under most viewing conditions, the user will not be able to see the interior from far away enough to justify a billboard light.)
Systems and Visualization
X-Plane’s lighting is broken into two pieces: a systems model that calculates how bright the light is, and a set of parameterized lights that you attach to a model to ‘see’ those lights on your aircraft. The brightness of the light is affected by the output of the systems.
The systems data can be used to drive LIT textures via ATTR_light_level (or even animations), as well as the parameterized lights. The systems data can also sometimes be customized via a plugin.
Systems Modeling and Aircraft
X-Plane provides a fixed number of simulated lights; however, you can attach as many (or few) lights to your OBJs as you want.
In many cases, the X-Plane systems simulation models more than one of a given type of light. For example, X-Plane supports up to 16 independent landing light simulations in its systems model.
The purpose of these separate ‘systems’ is to allow individual lights to be turned on and off. For example, any of the 16 simulated landing lights can be on or off, drawing electricity or not.
However, it is critical to understand that you, as the modeler and artist of your aircraft, can tie any light billboard to any system. The systems are a simulation, but the OBJ lights are a way to visualize it. So all of these configurations are legal:
- A Cessna has one landing light on the wing, created with a single pair of parameterized spill and billboard, tied to systems landing light index zero. The user has one switch on the panel.
- A Kingair has two landing lights (one on each wing), created with two pairs of spill/billboards. The left wing is tied to system landing light 0, and the right wing is tied to system landing light 1. There are two switches on the panel (one for system 0, one for system 1) and the lights can be turned off and on independently.
- A Baron has two landing lights (one on each wing), created with two pairs of spill/billboards. All of the lights are tied to system 0. There is only a single switch on the panel that turns off and on all lights.
- A 747 has four landing light spills and eight billboards – each “light” on the wing has two billboards to create a particular billboard shape, but only a single spill. Each cluster (two billboards, one spill) is tied to a different system, numbered 0-3. There are four switches on the panel. Thus each of the four switches turns on two billboards and one spill. The user experiences independent landing lights; the paired billboards create a particular ‘wide’ halo effect.
The key point here is that one systems simulation of a light can be tied to one or more parameterized lights. This is accomplished by specifying (in the parameterized lights) which system it is “listening” to.
The same principle applies to strobe lights; all of these configurations work well.
- The author does not customize X-Plane’s strobe light behavior; the aircraft has four strobe lights (two on each wing tip), each listening to the systems simulation strobe index 0. All four strobes light up at once. (This configuration is: one system, four lights.)
- The author has written a plugin to customize the strobe sequence; strobe index 1 fires after strobe index 0. The two forward strobes (left and right) listen to system index 0, the two rear ones listen to index 1. The plugin can thus fire strobe index 0 and then 1 with a data ref for a forward-to-aft strobe order. Since the left and right strobes listen to the same system, the plugin can only turn off the strobes as a whole. (This configuration is: two systems, four lights.)
- The author has written a plugin to customize the strobe sequence: all four strobes are using different system indices. The plugin sets strobes 0 and 1 on at the same time, then 2 and 3 after them. The plugin can fire only strobes 1 and 3 to ‘fail’ the left wing strobes but keep the right wing strobes turned on. (This configuration is: four systems, four lights.)
Systems are always numbered starting at 0. X-Plane currently provides:
- Up to 16 landing lights.
- One taxi light.
- One spot light.
- Up to 64 generic lights.
- Up to 4 independent strobes.
- Up to 4 independent beacons.
Directionality of Lights
A spill light can cast light omnidirectional (a sphere lighting all directions) or in a directional cone. When a spill light is directional, a direction vectors specifies where the center of the cone points to. The direction vector should be a ratio such that the length of the vector is 1.0.
The axes correspond to the coordinate system of an OBJ file. If your OBJ is attached to your aircraft with no rotations, then the positive X axis points to the right wing, the positive Y axis points up, and the positive Z axis points to the tail.
A billboard light is drawn as a square facing the camera; directionality is simulated by making the light dimmer or smaller depending on the angle of the light to the viewer. For example, a landing light billboard that “faces forward” will be brightest when the airplane is viewed head on; the light may be dimmer when viewed from the side, and the billboard will completely disappear when viewed from behind. The direction vector in this case represents the direction from which the billboard is largest/brightest. (If the direction vector faces forward, e.g. 0,0,-1 then you must face the nose of the plane to see the billboard. Thus the direction vector of the billboard and spill should be roughly the same.)
Some lights do not have direction vectors in their parameters; when this is the case, the light (if directional) will face forward, as if its direction vector was 0,0,-1.
All lights are modified by OBJ animation, so one way to modify the direction of the light is to put it inside an animation and use a rotation. Thus you can use an OBJ animation to ‘aim’ a light that does not have parameters for direction.
Spill Lights on Airplanes and Lighting Groups
Objects attached to airplanes in Plane-Maker have a number of properties – see this document for detailed information. In particular, Plane-Maker objects can be in any of three lighting groups: interior, exterior, and glass.
The object’s lighting group affects both which global lights receive light from the airplane and from the world and which other objects the attached spill lights send light to.
In particular, “interior” objects are only lit by spill lights from other “interior” objects and the interior spill lights in Plane-Maker. “Exterior” objects are only lit by other “exterior” objects, the Plane-Maker exterior lights, and scenery lights.
(The goal of this system is to allow the author to isolate the interior of the airplane from exterior lights – in real life it is unlikely that the apron floods or taxi lights make direct contributions to the interior of the airplane. See this blog post for more info.)
“Glass” objects are not lit by HDR spill lights at all and should not have HDR lights attached to them!
Cone Width for Spill Lights
Spill lights have a ‘width’ or ‘focus’ parameter that specifies the shape of the cone of light cast. Use a value of 1.0 for an omnidirectional light.
For directional cone lights, the width parameter is the cosine of half of the cone. (E.g. the angle from the center of the light cone to the edge.) This table lists some common widths:
Cone angle Angle From Center Width 170 85 0.08715 160 80 0.17364 140 70 0.34202 120 60 0.50000 100 50 0.64278 90 45 0.70710 80 40 0.76604 70 35 0.81915 60 30 0.86602 50 25 0.90630 40 20 0.93969 30 15 0.96592 20 10 0.98480 10 5 0.99619
The width value must be larger than zero; spill lights are thus restricted to a cone of less than 180 degrees.
Cone Width for Billboard Lights
For billboards, the cone width formula is:
width = cos(angle) / (cos(angle) - 1)
Where angle is the angle from dead-on viewing to the edge of the cone where the light is invisible.
When making a billboard directional, the direction vector must be scaled by a factor calculated as:
scale = 1 - width
Thus more-directional billboards will have longer direction vectors and larger negative width numbers.
The following table lists some common widths for billboards:
Cone Angle Width Scale
Angle from
center
360 180 0.50000 0.50000
340 170 0.49617 0.50383
320 160 0.48445 0.51555
300 150 0.46410 0.53590
280 140 0.43376 0.56624
260 130 0.39128 0.60872
240 120 0.33333 0.66667
220 110 0.25485 0.74515
200 100 0.14796 0.85204
180 90 -0.00000 1.00000
170 85 -0.09548 1.09548
160 80 -0.21014 1.21014
140 70 -0.51980 1.51980
120 60 -1.00000 2.00000
100 50 -1.79945 2.79945
90 45 -2.41421 3.41421
80 40 -3.27432 4.27432
70 35 -4.52951 5.52951
60 30 -6.46410 7.46410
50 25 -9.67325 10.67325
40 20 -15.58172 16.58172
30 15 -28.34774 29.34774
20 10 -64.82305 65.82305
10 5 -261.79124 262.79124
5 2.5 -1049.66472 1050.66472
Note that the width 0.5, scale 0.5 does not make an omnidirectional light: it makes a directional light that just becomes invisible when viewed from behind. To get a truly omnidirectional light, use a direction vector of 0,0,0 and a width of 1.0.
Standard Units for Parameterized Lights
Parameterized lights use numeric parameters to customize the look of the light. The units of those parameters are consistent and often standardized among all of the aircraft lights.
RGB colors: RGB colors are represented as ratios from 0.0 to 1.0. So white is 1,1,1, red is 1,0,0 and a dark blue might be 0,0,0.3.
Systems Index: lights often take an index number for which light in the systems model they track. These indices start at 0 for the first system, and match the indices in data refs. For example, a light controlled with sim/cockpit2/switches/landing_lights_switch[2] should use 2 as its index in the named lights.
Billboard size: billboard size is an arbitrary number – it does not correspond to a physical unit like meters. You will have to experiment to find appropriate sizes.
Spill sizes: the size of a spill is the distance in meters that the spill throws light until it is completely dark. Because the ‘edge’ of the spill light has very low light levels, your size will have to be larger than the size of the spill you want on the ground by some extra factor.
Performance Tip: keep spills as small as possible; the cost in fps of a spill light is a function of the area it covers. So a very large (but dim) spill light uses more GPU power than a small bright one.
Cone Withs: directionality of spills is referred to as “width” or “w” and follows the first table above; directionality of billboards is referred to as “focus”; if a billboard has directionality but no direction vector, use the “width” value from the table but ignore the “scale” value.
Related DataRefs: Each set of lights lists two datarefs: the dataref used to turn the light on/off (in sim/cockpit2) and the light that reflects the current light brightness, which can be used for ATTR_light_level.
List of Named Lights
Each light is listed with its parameters in order. All parameterized lights have an XYZ location before the light-specific parameters.
Landing, Taxi, Spot and Generic Lights
The landing, taxi, spot and generic lights all have the same composition, and are listed together. They differ only in what systems they reference, and in the texture of their billboards.
airplane_landing_core X Y Z INDEX SIZE airplane_landing_glow X Y Z INDEX SIZE airplane_landing_flare X Y Z INDEX SIZE airplane_landing_sp R G B INDEX SIZE W
Switch Dataref: sim/cockpit2/switches/landing_lights_switch[INDEX]
Brightness: sim/flightmodel2/lights/landing_lights_brightness_ratio[INDEX]
airplane_taxi_core X Y Z INDEX airplane_taxi_glow X Y Z INDEX SIZE airplane_taxi_flare X Y Z INDEX SIZE airplane_taxi_sp R G B INDEX SIZE W
Switch dataref: sim/cockpit2/switches/taxi_light_on
Brightness: sim/flightmodel2/lights/taxi_lights_brightness_ratio[INDEX]
airplane_spot_core X Y Z INDEX SIZE airplane_spot_glow X Y Z INDEX SIZE airplane_spot_flare X Y Z INDEX SIZE airplane_spot_sp R G B INDEX SIZE W
Switch data ref: sim/cockpit2/switches/spot_light_on
Brightness: sim/flightmodel2/lights/spot_lights_brightness_ratio[INDEX]
airplane_generic_core X Y Z INDEX SIZE airplane_generic_glow X Y Z INDEX SIZE airplane_generic_flare X Y Z INDEX SIZE airplane_generic_sp R G B INDEX SIZE W
Switch Dataref: sim/cockpit2/switches/generic_lights_switch[INDEX]
Brightness: sim/flightmodel2/lights/generic_lights_brightness_ratio[INDEX]
X, Y, Z: Billboards take a direction vector that defines the direction in which the billboard is brightest. The length of the XYZ vector defines the level of directionality; see the “scale” table above for how to make a longer vector for a more directional light.
R, G, B: Each spill light takes an R,G,B color that is used to tint both the spill.
INDEX: this is the index into the systems data-ref array that the light uses to calculate its brightness.
SIZE: the size of the billboard or spill. Spill is in meters, billboards are in arbitrary units.
W (width): spill-only the width of the light cone. The cone width for the billboards is pre-determined.
airplane_XXX_core – a small billboard that represents the bulb itself.
airplane_XXX_glow – A larger ambient glow billboard that represents the illumination of moisture around the light.
airplane_XXX_flare – A very large star-shaped billboard pattern that appears when looking _directly_ at the light.
airplane_XXX_sp – a spill light to cast a light cone.
The taxi and spot light datarefs are ints – they are on or off. The landing and generic light switches are floating point – you can set landing lights to half-power by setting this to 0.5.
All brightness datarefs are floating points; as the taxi light comes on, for example, it will ‘ramp up’ from 0.0 to 1.0 in brightness over a second or two.
Beacons
There are separate lights for rotating beacons vs. strobing beacons.
airplane_beacon_rotate PERIOD PHASE airplane_beacon_rotate_sp PERIOD PHASE SIZE WIDTH
A rotating beacon – the first light is the billboard, the second is the spill.
PERIOD: the period in which the beacon makes a full rotation. So 2.0 means the beacon rotates once every 2 seconds; 0.5 means it rotates twice per second.
PHASE: the phase offset of the beacon as a ratio (0.5 means 180 degrees out of phase). Use this to create multiple beacons that don’t all face the user at the same time.
SIZE: spill-only, the size of the spill cast by the rotating beacon, in meters.
WIDTH: spill-only, the width of the cone – see the above table for spill widths.
airplane_beacon_strobe SIZE INDEX airplane_beacon_strobe_sp SIZE INDEX
A strobing beacon – it flashes when the systems model says the beacon is ‘on’. SIZE: the size of the billboard and spill.
INDEX: the index into the beacon data ref that the beacon tracks.
Switch data ref: sim/cockpit2/switches/beacon_on
Brightness: sim/flightmodel2/lights/beacon_brightness_ratio[INDEX]
Anti-Collision Strobes
The anti-collision strobes have two billboard definitions: one for billboards visible from all angles and one for billboards only visible from some angles.
airplane_strobe_omni I1 I2 I3 INDEX SIZE airplane_strobe_dir X1 Y1 Z1 INDEX SIZE X2 Y2 Z2 W2 airplane_strobe_sp R G B INDEX SIZE X Y Z W
I1, I2, I3: these are ignored; please set them to zero.
Index: the index of the strobe data ref that the light tracks.
Size: the size of the billboard or spill.
X1, Y1, Z1: for a directional billboard strobe, this direction vector fades out the strobe (with translucency) – the magnitude of X1,Y1,Z1 forms the focus of the effect. Recommendation: do not use faded strobes – set these to 0,0,0!
X2,Y2,Z2, W2: for directional billboards, this fades out the term; W2 sets how much of the strobe is visible at any direction and should be set to 1 – length(x2,y2,z2).
R, G, B: for spills, the color of the spill.
X, Y, Z: for spills, the direction of the spill – this should be normalized.
W: for spills: the cone angle of the strobe (use 1.0 for omnidirectional spills.)
Switch dataref: sim/cockpit2/switches/strobe_lights_on
Brightness: sim/flightmodel2/lights/strobe_brightness_ratio[INDEX]
sim/flightmodel2/lights/strobe_flash_now (goes to 1 if any strobe is flashing)
Navigation Positional Lights
airplane_nav_tail_size SIZE FOCUS airplane_nav_left_size SIZE FOCUS airplane_nav_right_size SIZE FOCUS airplane_nav_sp R G B INDEX SIZE X Y Z W
Billboards: size is the size of the billboard; focus is the ratio that describes how visible the light is off-angle from the table above. The billboards are already colored red, green and white – pick the billboard name that matches the position light you want.
Spill: RGB tints the spill light – there is one spill light for all navigation positions.
Index: this is ignore and should always be set to 0.
Size: the size of the spill in meters.
XYZ: the direction the light points – use 0,0,0 for omni-lights.
W: the width of the light cone from the table above, or 1.0 for an omnidirectional light.
Switch dataref: sim/cockpit2/switches/navigation_lights_on
Brightness: sim/flightmodel2/lights/nav_lights_brightness_ratio[0]
Internal Cockpit Spill Lights
Two parameterized lights provide spill lighting inside the cockpit that follows the panel and instrument light datarefs.
airplane_panel_sp R G B INDEX SIZE X Y Z W
Switch dataref: sim/cockpit2/switches/panel_brightness_ratio[INDEX]
Brightness:
sim/cockpit2/electrical/panel_brightness_ratio_auto[INDEX]
sim/cockpit2/electrical/panel_brightness_ratio_manual[INDEX]
airplane_inst_sp R G B INDEX SIZE X Y Z W
Switch dataref: sim/cockpit2/switches/instrument_brightness_ratio[INDEX]
Brightness:
sim/cockpit2/electrical/instrument_brightness_ratio_auto[INDEX]
sim/cockpit2/electrical/instrument_brightness_ratio_manual[INDEX]
Use airplane_panel_sp to tie a spill light to the flood/panel light datarefs; use airplane_inst_sp to tie a spill light to the instrument light data refs.
RGB: the color of the light.
INDEX: the index into the dataref to set the brightness.
SIZE: the size of the light in meters.
XYZ: the direction the light faces, or 0,0,0 for omnidirectional
W: the width of the light cone from the table above or 1.0 for omnidirectional lights.
Auto vs. manual: in aircraft cockpits, some instruments will contain a light sensor that automatically adjusts the display brightness of the instrument to match the ambient lighting. For example, a Bendix King radio stack will turn the brightness of the radio LEDs up during the day (so that they are readable in full sunlight) and down at night (so that they are not annoyingly bright during bright flight.
X-Plane provides two versions of the cockpit/panel brightness levels in two sets of datarefs.
- The _manual datarefs simulate a light that stays the same brightness under all conditions. Such a light will typically be either too dim during the day or annoyingly bright at night if the user does not manually adjust it. (The dataref is named _manual because a pilot must _manually_ adjust it for comfort.) This datare’fs value will stay constant during all times of day.
- The _auto datarefs simulate a light that is tied to a photo-cell and automatically becomes brighter during the day. Lighting that follows this dataref will appear ‘bright and readable’ during the day and night without user intervention. If you change the time of day you will see this dataref take on very large values during the day (as the photo-cell indicates more light is needed) and then go back down to normal values at night.