If you are creating an airplane or scenery pack and you need to create a fully customized spill light (visible in HDR mode only in v10) there are two ways to do it.

First, we have a parameterized light called “full_custom_halo” that takes nine parameters, e.g.

LIGHT_PARAM full_custom_halo 0 20 0   1 0.5 0.5 1    50  0 -1 0   0.5

(Phew!)  The first 3 numbers 0,20, are the XYZ position (this light is 20 meters above our object origin).  The next four are the RGBA color (100% red, 50% yellow, 50% green, 100% brightness*), so it’s a very light red.  RGB colors for spills are in linear space, so you’ll have to experiment to get your colors perfect.  The size is 50 meters (a huge light throw), and it points in the direction 0, -1, 0 (straight down).  0.5 is the “semi-width” of the cone – 60 degrees in this case.  Basically cosine(cone width * 0.5) gives you this width parameter, or pass 1.0 for an omnidirectional light.

This light is on all the time – use full_custom_halo_night for the night version.

There’s a second option: OBJ files have a custom spill command:

LIGHT_SPILL_CUSTOM 0 20 0   1 0.5 0.5 1    50  0 -1 0   0.5  your/dataref/here

The position and 9 light parameters all have the same meanings, but in this case you get to provide a dataref.  The dataref must be a float-array dataref of size 9; when your dataref callback is called, the array is pre-initialized to the 9 params, and you can change them at will.  With this dataref, your plugin can change the light parameters in real-time.

Which technique should you use?

  • Use LIGHT_SPILL_CUSTOM if you need the dataref to do clever customization.
  • Use the PARAM_LIGHT with the nine params if you don’t need the dataref.

For scenery the param-light version may be notably faster when used many times in an object.  So if you’re building a light used a lot (a streetlight, a taxiway light, an airport lighting fixture) you really want that param version.

Update: this was not documented at the time, but if you are using datarefs with LIGHT_CUSTOM_SPILL, the dataref format does not match the OBJ8 format.  This page now documents the right format for plugin objects!

* The mathematically minded will note that there is no need to have an alpha on lights because they are additive.  This is true – just set alpha to 1.0 and use darker colors!

About Ben Supnik

Ben is a software engineer who works on X-Plane; he spends most of his days drinking coffee and swearing at the computer -- sometimes at the same time.

2 comments on “Customizing Spill Lights – Two Ways”

  1. Let me get this straight. Create a light, say, in ac3d. Edit light type to LIGHT_SPILL_CUSTOM and add the parameters and dataref in a text editor. I suppose the plugin must initialize the dataref with the same values, then rewriting any parameter, the x-position, for example, would move the light?

    1. Pretty close. For the dataref, you do not need to init the dataref with the same values as the light – rather in your XPLMGetDatavf callback, you need to simply change the values that you wish to change and leave the rest alone.

      See here.

      //wiki.x-plane.com/Custom_Lights#Usage_Models_for_Custom_Lights_and_Datarefs

      It’s the same idea for custom spills and custom billboards – dataref gets a chance to change all, some, or none of the 9 params.

      And…XYZ is _not_ part of the 9 params. If you want to change the XYZ, just use animation. You don’t even need the full custom lgiht for this!

Comments are closed.