How do I use DataRefTool in X-Plane?

DataRefTool is an X-Plane plugin for finding, watching and testing datarefs and commands. Install it under Resources/plugins, restart X-Plane, open DataRefTool from the Plugins menu, then search by name or use change detection while operating a cockpit control. Edit only datarefs reported as writable; use commands when available.

How do I install DataRefTool in X-Plane?

DataRefTool must sit directly inside X-Plane’s plugins directory, with its supplied folder structure intact.

1. Quit X-Plane completely. Do not install or replace the plugin while the simulator is running.
2. Extract the downloaded archive. Locate the actual DataRefTool folder containing the plugin files, rather than an outer archive or release folder.
3. Copy it into the simulator. The resulting path should resemble X-Plane 12/Resources/plugins/DataRefTool or the equivalent X-Plane 11 path.
4. Remove older duplicate copies. Keep only one DataRefTool installation in Resources/plugins.
5. Start X-Plane and check the Plugins menu. Open the DataRefTool search or window item shown by the installed release.

A mistake we see constantly is an extra folder level, such as Resources/plugins/DataRefTool-release/DataRefTool. If the plugin does not appear, compare the structure with our guide to installing X-Plane mods and plugins, then inspect Log.txt in the X-Plane root directory for a loading error.

How do I find and test a dataref?

Load the target aircraft first, then search for a distinctive fragment of the system or control name while watching the live results.

1. Prepare the aircraft. Load the exact aircraft and livery you are investigating, allow its systems and plugins to initialise, and place the relevant system in a known state.
2. Open DataRefTool. Use the entry under X-Plane’s Plugins menu and select the dataref search view.
3. Search with short terms. Try fragments such as the component, system or function name instead of guessing an entire path. Stock X-Plane references often begin with sim/; aircraft-specific references use names chosen by their developer.
4. Watch live values. Move one switch, lever or knob and look for a result that changes at the same time. Repeat the action in both directions to rule out unrelated flight-model values.
5. Use change detection. Start a fresh change-detection pass, operate the control once, and narrow the results. Continuously moving flight and engine values can otherwise swamp the list.
6. Check the type and index. A result may be a number, an array or byte data. For an array, identify the individual index associated with the control rather than changing every element.
7. Test cautiously. Select a writable result, enter a temporary value through DataRefTool’s value editor, and confirm the cockpit responds. Make small changes and be ready to reload the aircraft if its system logic becomes confused.

The first changing result is not necessarily the correct interface. A cockpit switch may have separate references for its commanded position, animated position, electrical output and annunciator state. For automation, choose the command or writable input intended to operate the control—not a read-only animation or status output.

Should I use a dataref or a command?

Use a command for a cockpit action when one exists; use a dataref when you need to read state or the aircraft explicitly provides a writable control reference.

Switch DataRefTool to its command results when a dataref search produces only status values. Trigger the candidate command once and observe the cockpit. Commands usually preserve the aircraft’s own interlocks, sounds and animation logic, while forcing a dataref can bypass them.

Why can’t DataRefTool find or change a dataref?

Missing results usually mean the wrong aircraft state, result category or interface is being examined—not that DataRefTool itself has failed.

• The aircraft or plugin has not created it yet: reload the target aircraft, power the relevant systems and wait for its plugins or scripts to initialise. Custom references may exist only while that aircraft is loaded.
• It is a command rather than a dataref: search the command list using the same name fragments.
• The value is internal: DataRefTool cannot reveal an aircraft variable that was never exposed as an X-Plane dataref or command.
• The edit immediately springs back: the aircraft, flight model or another plugin owns that value and writes it repeatedly. Use the corresponding command or intended writable input instead.
• The dataref is read-only: it can be monitored but not controlled. Writable status should be checked before attempting an edit.
• The wrong array element is selected: inspect each index while moving the control rather than assuming the first element is correct.
• The plugin menu is absent: check for nested folders, an incompatible operating-system binary, a disabled plugin or two installed copies. The specific loader error should appear in Log.txt.
• X-Plane shortcuts stop responding: the DataRefTool search box may still have keyboard focus. Click outside the field or close the window before testing normal controls.

How do I use a DataRefTool result in a script?

Copy the exact dataref or command path only after confirming its behaviour, type, writable status and any required array index.

DataRefTool is an inspector and test utility; changing a value there does not create a permanent configuration. To read or operate the result repeatedly, place it in a compatible script and follow our FlyWithLua installation and troubleshooting steps. Keep DataRefTool open during development so you can verify that the script changes the intended value and does not fight another system every frame.

For a separate program running outside X-Plane, DataRefTool helps identify and validate names but is not the transport layer. Our guide to X-Plane UDP, RREF and DREF output explains the difference between grouped UDP data, reading individual datarefs and writing supported values.