Learn what X-Plane datarefs do, where DataRefs.txt is stored, how to find custom refs, and why commands and private refs need different handling.
X-Plane datarefs are named variables through which the simulator and plug-ins expose data such as airspeed, switch positions, weather and system status. The main list for your installed version is Resources/plugins/DataRefs.txt inside the X-Plane folder; aircraft- and plug-in-specific datarefs must usually be found at runtime or in the add-on's documentation.
Where is the X-Plane DataRef list?
The most reliable DataRef list is the copy supplied with your exact X-Plane installation.
- Open the X-Plane installation folder. This is the directory containing the X-Plane executable or application and the
Resourcesfolder. - Go to
Resources/plugins. - Open
DataRefs.txt. A plain-text editor is sufficient; use its search function to find terms such asgear,autopilotorweather. - Check the entry carefully. Confirm its type, access status, units and description before using it in code or a hardware profile.
The official X-Plane SDK documentation also provides a searchable DataRef reference. Make sure its simulator generation matches the version you are targeting. When an online reference and your installation disagree, use the installed DataRefs.txt as the guide for that build.
Do not confuse this file with Settings > Data Output. The Data Output screen contains groups intended for on-screen or network output; it is not the complete SDK DataRef list.
What does a dataref contain?
A dataref exposes a specific piece of simulator or add-on state under a unique, case-sensitive name.
Stock X-Plane datarefs generally use the sim/ namespace, with paths such as sim/flightmodel/position/latitude. A plug-in or sophisticated aircraft can register its own namespace after it loads, so those custom names will not normally appear in the stock text file.
A DataRef entry tells you several things:
- Name: the exact path that a script or plug-in requests.
- Type: commonly an integer, float, double, array or block of data.
- Access: whether clients may only read the value or may also write to it.
- Units and meaning: essential when values use ratios, radians, metres or another unit rather than the cockpit unit you expected.
Array datarefs need the correct element index. Deprecated datarefs may remain for compatibility, but new work should use the supported replacement named in the description where one is provided.
Are datarefs the same as X-Plane commands?
No. A dataref represents state, while a command represents an action with start, continue and stop phases.
| What you need to do | Use | Reason |
|---|---|---|
| Read altitude, switch position or system status | Public dataref | You need the present value. |
| Press a button, move a selector one step or hold a control | Command | The aircraft may need to run logic rather than accept a raw value. |
| Control a custom aircraft system | Its documented dataref or command | Stock controls may not drive the custom simulation. |
| Alter an undocumented visual or rendering value | Supported setting or public interface | Private datarefs can change or disappear without compatibility guarantees. |
A mistake we see constantly is writing directly to a cockpit dataref when the aircraft expects a command. The displayed value may snap back, the animation may move without changing the underlying system, or nothing may happen.
Datarefs are also not a shortcut for ordinary avionics operation. To enter and fly a route, use our guidance on programming the X-Plane FMS; for the default glass cockpit, follow the proper X-Plane 12 G1000 operating procedure.
How do I find aircraft or plug-in-specific datarefs?
Custom datarefs must be identified after the aircraft or plug-in that creates them has loaded.
- Load the target aircraft and plug-ins. Some datarefs are not registered until the aircraft finishes initialising or electrical power is applied.
- Read the add-on documentation. The developer may publish supported commands and datarefs specifically for cockpit builders, scripts and hardware integrations.
- Use a live dataref-inspection plug-in. A DataRef editor or inspection tool can search registered names and display changing values while X-Plane runs.
- Operate one control at a time. Move the switch or knob, watch which values change, then verify whether the useful interface is a dataref, an array element or a command.
Not every changing value is safe to write. One dataref may drive only the animation while another represents the actual system state. This distinction is especially common in complex aircraft found alongside other X-Plane aircraft, plug-ins and utilities.
Can I add or change datarefs by editing DataRefs.txt?
No. DataRefs.txt is reference documentation, not a configuration file.
Adding a line does not create a dataref, and changing a description does not alter X-Plane. A new dataref must be registered programmatically by a plug-in or aircraft system through X-Plane's supported interface.
Why does an X-Plane dataref not work?
Most dataref failures come from using the wrong interface, version, access mode or units.
- The name is missing: confirm spelling and letter case, then check that the required aircraft or plug-in has loaded.
- The value will not change: it may be read-only, or the operation may require a command instead.
- The value snaps back: X-Plane's flight model or the aircraft's systems are recalculating it each frame. Do not fight that logic with repeated writes; use the documented control or override mechanism.
- The result is wildly wrong: check units, scaling and array index. A ratio from zero to one is not a percentage from zero to 100.
- It worked in another X-Plane release: consult the
DataRefs.txtsupplied with the target installation for deprecations or changed behaviour. - The path begins with a private namespace: treat it as unsupported. Private datarefs are implementation details and can break after an update.