Learn what X-Plane 12 datarefs are, how to find, read and safely write them, and why scripts return nil, wrong values or ignored changes.
X-Plane 12 datarefs are named variables that expose simulator or add-on state, such as indicated airspeed, switch positions and aircraft location. You use them through a plugin, FlyWithLua script or hardware interface to read values and, only where a dataref is documented as writable, change them.
What does an X-Plane dataref contain?
A dataref is a typed variable registered with X-Plane and addressed by a slash-separated name. The name resembles a folder path, but it is not a file on disk.
Common dataref forms include:
- Integers for discrete states such as on/off selections.
- Floats and doubles for positions, speeds, angles and other continuous values.
- Integer or float arrays for repeated items such as engines.
- Byte arrays for text or blocks of data.
Each dataref also has access rules. Some are read-only; others allow writing. Units and valid ranges are not encoded consistently in the name, so confirm them in the dataref documentation or an inspection tool rather than guessing.
Simulator datarefs normally use the sim/ prefix. Aircraft and plugins can register custom names under their own prefixes, and those custom datarefs may exist only while the relevant aircraft or plugin is loaded.
How do you find and use X-Plane 12 datarefs?
The safe method is to inspect the live value first, verify its type and units, and only then connect it to a script, plugin or controller.
- Decide whether you need state or an action. Use a dataref to observe a value. If you want to operate a switch or trigger an event, first check whether X-Plane or the aircraft provides a command instead.
- Load the correct aircraft and add-ons. Aircraft-specific datarefs will not necessarily be registered from the main menu or while another aircraft is active.
- Search the live registry. A compatible inspection plugin such as DataRefTool or DataRefEditor can search names and display changing values. Record the exact path, data type, array index, units and writable status.
- Test a read-only connection. Move the control or change the aircraft state and confirm that the displayed value responds as expected. This catches similarly named datarefs and unit mistakes before they affect the aircraft.
- Choose the right interface. FlyWithLua suits small automations and experiments; a native plugin is better for compiled integrations, custom datarefs or high-frequency processing. Hardware-mapping software may also expose datarefs directly.
- Test after an aircraft reload. Check
Log.txtin the X-Plane folder for missing datarefs, script errors and plugin conflicts.
If the plugin or script is not loading, follow our instructions for placing plugins and scripts in the correct X-Plane folders before troubleshooting the dataref itself.
FlyWithLua read-only example
A FlyWithLua script can bind an X-Plane dataref to a Lua variable. The following test reads the pilot's indicated airspeed and periodically writes it to Log.txt:
dataref("ias_kts", "sim/cockpit2/gauges/indicators/airspeed_kts_pilot", "readonly")
function report_ias() logMsg("IAS: " .. tostring(ias_kts)) end
do_often("report_ias()")
Place the script in the standard Resources/plugins/FlyWithLua/Scripts folder. Remove the logging callback after testing; repeated diagnostic messages needlessly enlarge Log.txt.
To change a value, the dataref must be explicitly documented as writable and bound in writable mode. Changing readonly to writable does not make a read-only dataref writable.
Using datarefs in a native plugin
A native plugin finds the dataref with XPLMFindDataRef, checks that a valid handle was returned, and uses the matching XPLMGetData* or XPLMSetData* function for its type. Find and cache handles outside the flight-loop callback rather than searching for the same name every frame.
Custom datarefs need extra lifecycle handling. If their aircraft or provider plugin changes, do not assume a previously obtained handle is still usable; check availability and reacquire it when appropriate.
What is the difference between a dataref and a command?
A dataref represents state, while a command represents an action with begin, continue and end phases.
| Requirement | Preferred interface | Reason |
|---|---|---|
| Read airspeed, position or switch state | Dataref | You need the present value. |
| Toggle gear, press a button or move a guarded switch | Command | The command lets the aircraft run its normal control logic, animation and sound. |
| Set a continuous target or ratio | Writable dataref | Use only when the dataref is documented for direct control. |
A mistake we see constantly is writing a cockpit dataref when a command is available. The displayed value may change briefly, then snap back because the aircraft's systems code still owns it. With complex add-on aircraft, using the supplied command is usually the only way to trigger every associated system.
Do the same datarefs work with every aircraft?
Standard simulator datarefs are broadly available, but they do not guarantee identical behaviour in every aircraft.
A sophisticated aircraft may use custom datarefs for switches, displays and system logic while exposing only part of that state through standard sim/ datarefs. If an integration works with a default aircraft but not an add-on, look for the aircraft's documented custom command or dataref rather than forcing the standard value.
The same distinction applies to raw flight-model values and cockpit indications. A flight-model dataref may contain the simulated physical value, while a cockpit dataref may include instrument failures, power state or display processing. Choose the one that matches what the integration is meant to represent.
Why is an X-Plane 12 dataref not working?
Most dataref failures come from a missing provider, the wrong type or units, a read-only value, or another system immediately overwriting the change.
- Not found or nil: check the spelling, load the required aircraft or plugin, and confirm that the dataref was not renamed or removed. Custom datarefs may be registered only after the provider finishes loading.
- The value looks wrong: verify whether it uses knots, metres, radians, degrees or a zero-to-one ratio. For arrays, confirm the correct element and the indexing rules of your chosen interface.
- A write has no effect: the dataref may be read-only even if the script can locate it. Use its documented command or writable interface.
- The value snaps back: X-Plane or the aircraft is probably writing its own value during each update. Writing more frequently creates a control fight rather than fixing the interface.
- Two add-ons disagree: multiple scripts can write the same dataref, producing flickering controls or unpredictable results. Disable them one at a time to identify the competing writer.
- The script stops: inspect
Log.txtfor Lua errors, unavailable datarefs or compatibility warnings. Some FlyWithLua configurations stop or quarantine a faulty script rather than continuing with partial execution. - Frame rate falls: avoid searching the registry, formatting text or writing log messages every frame. Cache handles and poll only as often as the device or feature requires.
Should you use sim/private datarefs?
No—avoid sim/private/ datarefs for anything that must remain reliable across X-Plane updates.
Private datarefs expose implementation details rather than a supported public interface. Their names, meanings and availability can change without compatibility guarantees, which is why older visual, weather and FlyWithLua scripts often fail under X-Plane 12 even though they worked in an earlier simulator release.
Prefer a documented public dataref or command. If an add-on has no public interface, treat any private-dataref solution as version-specific and make the script fail safely when the value is absent. Our guidance on checking free add-on and script compatibility with X-Plane 12 explains why private-dataref modifications need particular care.
Do dataref changes persist after restarting X-Plane?
Dataref writes do not provide general persistence; they normally change the live simulation state only.
An aircraft or plugin may separately save some settings, but that is its own feature rather than a property of the dataref. If a script must reapply a value, wait until the aircraft and its systems have loaded, then set it through the supported interface. Applying it too early often fails because the aircraft's initialisation code overwrites it moments later.
Datarefs are also local unless an integration explicitly transmits them. Multiplayer software, an external application or another computer will not automatically receive every dataref merely because it changed in X-Plane.