Datarefs

In XLua, you can:

X-Plane Datarefs

To use X-Plane datarefs in your Lua code, you need to first "fetch" (go get) the dataref by its string name and assign it to a Lua variable name (typically called a DR handle). XLua supports number, strings and array type datarefs. XLua does not distinguish between int and float types, both are simply a number type.

When you fetch an X-Plane dataref, then your DR handle type will either be string or number depending on the dataref type you fetch. Once you have fetched your X-Plane dataref you can use it by simply using the handle name like any other variable name. Note that same X-Plane datarefs are not writable.

Check out X-Plane Dataref Browser to search for default X-Plane dataref names ,their types, descriptions and whether or not they are writable.

Single Value Datarefs

The example below creates a new X-Plane dataref handle (xdr_view_ext) that accesses a single dataref value.


xdr_view_ext    =   find_dataref("sim/graphics/view/view_is_external")

if  xdr_view_ext == 1   then
        --  do something here
end

Array Datarefs

For array type X-Plane datarefs, there are two ways to access the array indicies.

  1. Fetch the Dataref by string name WITHOUT an index value, and only supply the index when you access the dataref (read/write) --OR--

  2. Include the index value when you fetch the dataref.

The following code shows both methods of fetching and using an array type dataref.


xdr_bus_volts       =   find_dataref("sim/cockpit2/electrical/bus_volts")       ---OR---
xdr_bus_volts_0     =   find_dataref("sim/cockpit2/electrical/bus_volts[0]") 

if xdr_bus_volts[0]  > 14.0 then   --OR--  ( if xdr_bus_volts_0 == 0 )
    -- equipment is powered and functional
else
    --  equipment has lost power and non-functional
end

xdr_bus_volts[0] = 24.0  --OR--  xdr_bus_volts_0 = 24.0
CAUTION:

Raw data (byte/string) arrays are treated as strings in Lua. Once you have fetched the byte/string type dataref, simply read/write to it as a Lua string.


xdr_tail_number     =   find_dataref("sim/aircraft/view/acf_tailnum")           --  byte[40] string type
xdr_livery_index    =   find_dataref("sim/aircraft/view/acf_livery_index")      --  integer/number type

if  xdr_livery_index    == 1    then

    xdr_tail_number = "N944XS"

elseif xdr_livery_index == 2    then

    if xdr_tail_number == "N1234"   then
        xdr_tail_number = "N234MA"
    end

end

Custom Datarefs

There are three types of custom datarefs you can create which are shown in the table below. Each of these types may be either read only or read / write. In all cases, custom datarefs are created with XLua's create_dataref function, which receives either TWO or THREE function arguments, two for read only custom DRs and three for read/write custom DRs.

DR type Description
"number" creates a single number dataref, init to 0
"string" creates a string dataref.
"array[5]" creates an array of numbers, initialized to 0

Read Only Datarefs

Read only custom datarefs are mostly commonly used to drive 3D OBJ animations, and are created by supplying the following TWO arguments to XLua's create_dataref function:

Both of these arguments are supplied in quotation marks as shown below. You may read and write the Lua handle value from within your Lua code, but neither X-Plane, nor any other plugin can write to the dataref itself, only read it. If you try to set the value of a read only dataref using Dataref Editor (DRE) or Dataref Tool (DRT), you will not be able to do so. Read-Only datarefs are commonly used to drive 3D OBJ and generic EFIS graphic animations in X-Plane. The following example creates read only custom datarefs and then sets their dataref handles to some values.


cdr_myCustomDataref_number  = create_dataref(“example/dataref/name_number”,     ”number”)
cdr_myCustomDataref_string  = create_dataref(“example/dataref/name_string”,     ”string”)
cdr_myCustomDataref_array   = create_dataref(“example/dataref/name_array”,      ”array[4]”)

cdr_myCustomDataref_number      =   23.12
cdr_myCustomDataref_string      =   "Hey Bubba, watch this!")
cdr_myCustomDataref_array[3]    =   12

Write Datarefs

Write Custom datarefs are most commonly used with manipulators in 3D cockpits. In this application, X-Plane writes to your dataref whenever your manipulators are clicked in 3D. Write datarefs are created by supplying THREE arguments to the create_dataref function:

Your write callback function is executed whenever the dataref is written to by another plugin, including X-Plane, which is just another plugin as far as XLua is concerned. The most common use for a custom read and write dataref is to accomodate custom cockpit manipulators, where you click on a manipulator and X-Plane writes a value to your dataref and then executes your callback function so you can take some action based on that value.

Other plugins that commonly write to custom datarefs are Dataref Editor (DRE) and Dataref Tool(DRT) by Lee Baker. They write to your dataref value any time you change your DR value via their interfaces. If you want to be able to change your dataref values using DRE or DRT, then your dataref must be a write type with a callback function. It is perfectly fine for a write callback function to be empty and do nothing.

The following code below creates a custom read and write custom dataref and also defines its callback function. Note that the callback function is defined first and that the 3rd argument of the declaration, the write callback function name, is not in quotation marks. 


    --  Define the write callback function for cdr_batt_key_position
    function    cdr_batt_key_position_handler()
        if cdr_batt_key_position == 1 then
            -- turn on X-Plane's battery, either by command or setting dataref here
        end
    end

    --  Declare the custom dataref params
    cdr_batt_key_position =     create_dataref("laminar/Baron/battery_key_position",  "number",  cdr_batt_key_position_handler)