You can download the example plane here: File:Example beacons.zip.
Overview
This example plane demonstates some of the airplane exterior lighting features that are possible in X-Plane 9:
- Left and right landing lights are separately controlled.
- Landing lights have two intensity levels (low and high).
- Landing lights illuminate the fuselage of the airplane.
- Logo lights illuminate the tail (billboards are visible on the wing-tips).
- Strobe pattern is customized.
- Front and rear wing strobes flash separately.
- The two rotating beacons rotate at different rates.
This tutorial covers the following X-Plane material:
- Parameterized Lights
- Datarefs for light control
- Use of ATTR_light_level
You Should Already Know
To understand this example plane, you should already know:
- How to model a plane in Plane-Maker.
- How to create a panel, including generic instruments.
- How to build the exterior out of OBJ files from a 3-d modeler.
- How to attach “named lights” to create lighting billboards.
This tutorial focuses mostly on billboards and halo effects; you can build light fixtures in a 3-d modeling program.
Landing Lights
X-Plane simulates up to 16 separately controllable landing lights (plus one taxi light). You can use named lights to map any number of billboards to any of these simulated lights.
If any of the 16 landing lights is on, X-Plane will draw a landing light halo effect on the runway in front of the airplane. (The quality of this effect will vary with hardware capability.)
The location of the landing light halo effect on the pavement is determined by the landing light location in the Plane-Maker view dialog box’s exterior lights tab.
Note: Even if you do not enable the landing lights in this tab, the location of the halo will be determined by this. X-Plane draws only one halo, so if you do not enable these lights, set the first light’s location to something appropriate for the centerline of the airplane.
Data Refs
The dataref
sim/cockpit2/switches/landing_lights_switch
is an array of floating point values that you can use to turn the landing lights on and off. The landing light switch is a ratio with 0 being off, 1.0 being full intensity, 0.5 being 50% intensity, etc. Each landing light can be set to a different intensity, or be individually turned off and on.
The dataref
sim/flightmodel2/lights/landing_lights_brightness_ratio
Tells the actual effective brightness of the landing light for visual effects – it takes into account electrical system and landing light failures, as well as the delay for the bulb to warm up and cool down. It is also an array of 16 floating point values – 0.0 is off, 1.0 is full brightness.
There are two legacy datarefs:
sim/cockpit/electrical/landing_lights_on sim/cockpit2/switches/landing_lights_on
That date back to older versions of X-Plane. Use the newer datarefs for more control – these datarefs will turn all of the landing lights on and off at once.
3-Way Panel Switches
X-Plane comes with a built-in “landing light” switch – don’t use it. It will only affect the first landing light. Instead, use generic instruments to write to the sim/cockpit2/switches/landing_lights_switch switch.
In our plane, we use a 3-position rotary. A key frame table matches the 3 positions to off, 50%, and 100% brightness.
Customizing the Landing Light Billboards
For the billboards under the wings, we do not use the built-in landing lights from the view dialog box of Plane-Maker. Instead we attach parameterized lights to our OBJ.
A parameterized light is like a named light: it is a billboard attached to your object at an XYZ location. The name defines what the billboard will look like. But unlike a named light, a parameterized light lets us customize the look of the light. Our object contains this:
LIGHT_PARAM airplane_landing_size -0.822960 -0.152400 1.737360 1.5 -3 0 LIGHT_PARAM airplane_landing_size 0.822960 -0.152400 1.737360 1.5 -3 1
The first 3 numbers are the location in meters relative to the attachment point of the fuselage object that the lights are part of. The next numbers meanings depend on the type of parameterized light. In our case (landing light by size) they are:
- The size of the billboard (1.5). Billboard sizes don’t correspond to meters – you’ll have to experiment to find appropriate sizes.
- The tightness of focus. Negative values are visible from the front of the plane, positive from the rear. Larger magnitude numbers make a light that is visible from a smaller angle.
- The index number of the light. So the first billboard on the left side is tied to landing light #0, the second one is tied to landing light #1. (Array indices for datarefs count from 0.)
Thus the two landing lights are independently controllable.
Note that you can make many light billboards (with LIGHT_PARAM or LIGHT_NAMED) for a single x-plane landing light. So for example, you can model a landing light in a wing with several bulbs.
Adding Halos To The Fuselage
To create the illusion of the landing light shining on the fuselage, the _LIT texture for the fuselage object has the lighting halos for the two landing lights and tail drawn in.
We can use ATTR_light_level to control the brightness of the light texture for a certain set of triangles. What makes things difficult is that we can only have one _LIT texture. So it is important that we design our lights with no overlapping regions. (We have no way to select one of multiple halos that would intersect in the LIT texture.) In our object we have this:
ATTR_light_level 0.000000 1.000000 sim/flightmodel2/lights/landing_lights_brightness_ratio[0] TRIS 0 882 ATTR_light_level 0.000000 1.000000 sim/flightmodel2/lights/landing_lights_brightness_ratio[1] TRIS 882 669 ATTR_light_level 0.000000 1.000000 sim/flightmodel2/lights/generic_lights_brightness_ratio[0] TRIS 1551 435
The mesh is divided into three parts, and each part has its lit level tied to one of the brightness ratios – two for the landing lights, one for the tail logo lights (see below).
Note that we do not use the switch datarefs, we use the filghtmodel2/lights/ datarefs to get the actual brightness. This way if our electrical system dies, the halo effect will disappear from the fuselage even if the switch is turned to the “on” positions.
Tail Logo Lights
The tail logo lights basically repeat the strategy we used for the landing lights, but with one difference: we don’t want a halo to appear on the runway because the logo lights are turned on. But we get a halo on the runway if any landing light is turned on. Clearly we can’t “recycle” one of our 14 remaining landing lights for the tail.
Fortunately, X-Plane also provides 64 “generic” lights. A generic light is a bulb simulated in X-Plane, similar to a landing light, but without producing a halo effect on the runway. We can use them for any purpose. In our case we will use a generic light to simulate logo lights projecting back from the wing tips to the tail.
Something to note: while our plane appears to have two logo lights (one on each wing tip lighting each side of the tail) we only use one generic light for both. This is because we don’t model turning the left and right logo light on separately. Thus we can just use one generic light, and use two billboards. There is no requirement to use one generic light in X-plane for each real-world bulb on the plane.
Data Refs
Like the landing lights, two datarefs control the generic lights. The switch position is also a ratio from 0.0 to 1.0:
sim/cockpit2/switches/generic_lights_switch
and the brightness (taking into account the electrical system, etc. is found in
sim/flightmodel2/lights/generic_lights_brightness_ratio
where 0.0 is off and 1.0 is full brightness.
3-Way Panel Switches
There is no pre-made instrument switch for generic lights – we must use a generic instrument (in our case another 3-way rotary) to map to sim/cockpit2/switches/generic_lights_switch.
Adding Halos To The Tail
Like the landing lights, we use ATTR_lit_level to fade the _LIT texture on the tail.
Adding Billboards To The Wing Tips
We want to put a pair of billboards on the tails so that when a user looks from the tail to the wing-tip, the bulb appears. Once again we use parameterized lights so we can customize the light’s properties a bit. But here we have a problem: the parameterized lights only face forward or backward. How do we angle the lights inward toward the tail?
The answer is animation. Directionally sensitive billboards in X-Plane are affected by animation. We can build a “static” animation (an animation whose animated position never changes) to “aim” the billboard at the tail.
ANIM_begin ANIM_trans -4.906825 0.121920 2.7 -4.906825 0.121920 2.7 0.000000 0.000000 none ANIM_rotate 0 1 0 250 250 0 0 none LIGHT_PARAM airplane_generic_size 0 0 0 1.5 -3 0 ANIM_end ANIM_begin ANIM_trans 4.906825 0.121920 2.7 4.906825 0.121920 2.7 0.000000 0.000000 none ANIM_rotate 0 1 0 120 120 0 0 none LIGHT_PARAM airplane_generic_size 0 0 0 1.5 -3 0 ANIM_end
The lights are being rotated around an arbitrary point, 250 degrees for the first light, and 120 degrees for the second.
Beacons And Strobes
For our airplane, we want to accomplish a few specialized effects with the beacons and strobes:
- We want the strobes to flash in an irregular pattern (short long, short long).
- We want the first flash to come from the front of the wing, and the second one to come from the back of the wing.
- We want the two red rotating beacons to flash at different rates.
X-Plane 940 models four separate strobes and four separate beacons. Normally they will all flash or rotate in sync in a preset pattern. But we can use a plugin to take over the behavior and program our own pattern. So we have a 2-part task:
- Program our own pattern, and
- Use parameterized lights to place strobes and beacons on our airplane OBJ that respond to the right strobe or beacon number.
Parameterized Lights For Beacons and Strobes
Once again, we will not use the built-in exterior lights; instead we will place our own in an OBJ. In the exterior lights tab of the view dialog box in Plane-Maker, all of the specific lights are off, and the options to have Plane-Maker place lights for us is off too.
In our fuselage object file we have:
LIGHT_PARAM airplane_beacon_size 0.000000 0.643128 0.000000 1.5 0 0 LIGHT_PARAM airplane_beacon_size 0.000000 1.594104 3.383280 1.5 0 1
This is a pair of rotating beacons; these are parameterized lights. The first parameter is size. The second parameter (0) makes the light omni-directional. And the third light is the index number of the 4 beacons. So the second beacon is on the tail, the first is on the fuselage.
(Note that unlike landing lights, all four beacons simulated in the system are controlled by one switch. The same applies for the strobes.)
Our nav lights on the wing tips are simple named ilghts
LIGHT_NAMED airplane_nav_left -4.906825 0.121920 2.197132 LIGHT_NAMED airplane_nav_right 4.906825 0.121920 2.197132
Finally, the strobe wings. We have two on each wing-tip.
LIGHT_PARAM airplane_strobe_size -4.906825 0.121920 2.097132 2 -0.25 0 LIGHT_PARAM airplane_strobe_size 4.906825 0.121920 2.097132 2 -0.25 0 LIGHT_PARAM airplane_strobe_size -4.906825 0.121920 2.397132 2 0.25 1 LIGHT_PARAM airplane_strobe_size 4.906825 0.121920 2.397132 2 0.25 1
The first parameter is size, the second directionality (again, negative means “visible from the front”, and smaller numbers are less directional), and the last number is the index of the strobe. So the front strobe is index 0, the back strobe is index 1.
Again, note that the number of strobes that the sim simulates is not the same as the number of billboards. We have two strobes, but we have two billboards for each (one on each wing). So the system simulates two strobes (for a two-stage flash) but we see four billboards.
DataRefs And Plugin
Without the plugin, the strobes would flash all four in sync, once a second, and the beacons wouild flash in unison. We use a fat plugin in the aircraft’s plugins folder to override this behavior.
The full source of the plugin and complete downloadable project files an be found on the X-Plane SDK website://www.xsquawkbox.net/xpsdk/mediawiki/Beacons_and_Strobes.
These are the datarefs that affect strobe and beacon operation:
sim/flightmodel2/lights/override_beacons_and_strobes
When you set this dataref to 1, you take control away from X-Plane and manage the strobes and beacons yourself. You must manage both – there are not separate overrides for beacons and strobes. Be sure to set the dataref back to 0 when your plugin is unloaded!
X-Plane will set these datarefs to be 1 if the beacons and strobes have power and 0 if they do not:
sim/cockpit/electrical/beacon_lights_on sim/cockpit/electrical/strobe_lights_on
Use these datarefs (and not the raw switch datarefs) to decide whether the strobes and beacons should light up – that way your strobes and beacons won’t work if the battery or electrical system fails.
These datarefs are updated by X-Plane once per frame, unless you override the beacons and strobes; in that case your plugin must update them.
sim/flightmodel2/lights/beacon_brightness_ratio sim/flightmodel2/lights/strobe_brightness_ratio sim/flightmodel2/lights/strobe_flash_now
The brightness ratios are 4-item float arrays – 0 means off, 1.0 means full brightness. The default beacons and strobes that Plane-Maker creates always show index 0, but you can use parameterized lights to show the other indices.
strobe_flash_now is an int – set it to 1 if any of the strobes is flashing; X-Plane checks this dataref and creates a “flash” effect in the cockpit when you are in the clouds or fog and the strobes are on.