Datarefs / Commands

[TODO: Finish this page]

General

For aircraft developers, Datarefs and Commands are the "bread and butter" of aircraft development and as such, demand their own section here. Datarefs are X-Plane values that are given a unique name and made available outside of X-Plane's own code so everybody can see what X-Plane is doing under the hood. Datarefs provide values like indicated airspeed, engine RPM, where a switch is positioned, the voltage level on a bus etc., and that is just the obvious stuff. There is hardly any value in X-Plane that is not exposed through a dataref. There are over 8000 datarefs available, displaying values most would never even think about. There is even a dataref for how high the sun is above the horizon. The image below shows a partial listing of datarefs and their associated values.

Dataref String Names

Dataref Editor plugin (DRE) by Laminar Research

Datarefs have names and these names resemble text based folder paths, where each word between the / characters could be said to be a field. Using a filepath style naming convention allows for the logical grouping and organization of datarefs. With over 8000 datarefs available, it is important to be able to find the dataref value you need quickly. Dataref names are commonly referred to as dataref strings, dataref string names or just simply datarefs. The value of a dataref is exactly that, a dataref VALUE and is discussed in the next heading. Here is a sample dataref name.

sim/operation/failures/hydraulic_pressure_ratio

A dataref name is not required to follow any format, a plugin author can create a single field custom dataref named bob if they like, but that is bad practice. The shorter the dataref name, the more likely it is to be duplicated by some other 3rd party developer and that can create headaches nobody wants. The dataref name should be very clear as to its origin and purpose. For default X-Plane dataref names, every single one of them will begin with the sim/ prefix field.

It is common to refer to prefixes and suffixes when discussing dataref names. The suffix is always the last field of the dataref name, so in the above example, the suffix is:

hydraulic_pressure_ratio.

Everything before the suffix is the prefix; however, which fields of the prefix one chooses to consider can vary. For example, we can say something like, ".....the failures datarefs", and we would be referring to all datarefs with the full prefix: sim/operation/failures/*. Likewise, we may say something like, "...the cockpit2 datarefs or the flightmodel2 datarefs. Using these types of abbreviated prefix names are the most common way developers refer to groups of datarefs. Everybody knows that for default X-Plane datarefs, the names always include sim/ at the beginning.

A bit of care must be exercised though when referring to suffixes only, as some dataref suffix fields are exactly the same, but with differing prefixes, like so:

sim/cockpit2/controls/yoke_roll_ratio
sim/joystick/yoke_roll_ratio
sim/multiplayer/controls/yoke_roll_ratio[n]

Dataref Value Types

A dataref can hold one of three types of values.

  1. An integer (no decimal)
  2. A real number (with decimal), commonly called a float.
  3. A single character

Text strings made up of multiple characters, such as the tail number of an airplane, "N844X", is comprised of a sequence of characters contained in an Array Dataref type which is discussed next.

Array Datarefs

Online Dataref Browser

Custom Datarefs

We do not discuss custom datarefs in this manual except to point out that custom datarefs may be created via a compiled plugin or script using one of several scripting engine plugins available for X-Plane (XLua, SASL, Gizmo, XPPython, FlyWithLua, etc.) For more information on creating compiled plugins with X-Plane's SDK, see [TODO: SDK link]

Dataref Editor