EXPERIMENTAL USE ONLY!!! -- [What?] -- Login to add public annotations [How? >>YouTube].

DataRefEditor

DataRefEditor is a free plugin that lets you view and change the 2000+ DataRef values inside X-Plane. DataRefEditor can be an SDK developer’s best friend. With the inclusion of generic instruments in V9, DataRefEditor took on new significance. In November 20022, DataRefEditor was revised to support Macs with Apple silicon (M1 and M2) CPUs.

Downloading and Installing DataRefEditor

DataRefEditor for X-Plane 11 & 12 can be downloaded here.

DRE is a fat plugin and it is therefore installed by dragging the DataRefEditor folder into the X-Plane / Resources / Plugins folder.  It is accessed from X-Plane’s pull down Plugins menu: Plugins > Data Ref Editor > Show Data Refs.  This will bring up a window showing each of the DataRefs and their values.

The download comes with a README file with complete instructions.

Viewing DataRefs

The DRE window can be resized by dragging any of its margins.  The window can also be dragged to any position on the screen.

To selectively filter or search for a small group or a singular DataRef enter a fragment of the DataRef string name into the bottom left corner of the DRE window.  Note: DRE is case sensitive.  For example entering “tire” will bring up 25 or more datarefs containing “tire” in the DataRef name.  Notice that many of the values fluctuate.

You can also view multiple windows in DRE.  For example: resize your “tire” window and use X-Plane’s > Plugins menu to open a second DRE window.  Entering “defl” will display the deflection of each of the tires on the aircraft.

Art Controls and Sim Stats

Besides the regular “show datarefs” display (which shows all of the datarefs in DataRefs.txt plus any datarefs intentionally published by other plugins), there are two other sets of datarefs that DataRef editor can show:

  • Art Controls
  • Stats

Both are shown using the menu picks “Show Art Controls” and “Show Stats”.

The art controls are mapped into the domain sim/private/controls/…. by X-Plane.  The stats are mapped into the domain sim/private/stats/….

Like all sim-private datarefs (sim/private) these datarefs are undocumented and unsupported and may not be there in future builds.

Your plugin, panel, or object should not depend on any sim/private datarefs!  They should only be used for diagnostics/debugging.

The art control datarefs are datarefs that will change the operation of the sim when changed.  For example, you can change the global size of billboarded lights using an art control.

The sim stats provide a huge amount of diagnostic information about the sim’s performance.  For an example, see [[Calculating Rendering Load]], which in detail explains how to measure X-Plane’s geometric throughput via the stats.

There is no one comprehensive list of stats and art controls; they are generated as part of our internal development process and left in the sim to aid in debugging during beta.

Changing DataRefs

You can change the value of most DataRefs by right or left clicking on the DataRef value and entering a new value.  This will allow you to observe the effect of changing a DataRef while in flight or on the ramp.  For example, if you change the value of sim/operation/failures/rel_tire1 from 0 to 1 you will observe that a small aircraft will tilt to the side as the tire deflates and the  “tire blown!” warning will appear.

Bring keyboard focus back to X-Plane by pressing return.

Many DataRefs items are stored as arrays.  Use the slider on the bottom right of the DRE window to advance the array index by 1 up to a value of 99.  For example, you can observe the tire deflection in the x, y, and z directions of each of the 10 tires on a “heavy” by incrementing the array index.  The slider on the left advances the array index by 100.

Adding Your Own DataRefs

There are two ways to add datarefs to DataRefEditor:

  • You can edit DataRefs.txt in Resources/plugins.  This is the easiest way to add datarefs, but when you update X-Plane, the installer will want to overwrite your changes.  Also, for this to work, your plugin must be loaded before DataRefEditor.
  • You can programmatically publish your datarefs.

Publish Your Own DataRefs

When the plugin starts up it will read all the datarefs that are in the Datarefs.txt file.

Once Xplane is up and running you can then tell the DataRefEditor plugin about your custom datarefs. The code to do this should only be called once. One way of doing this is to use a flight loop callback that returns 0. That way the flight loop callback will only be called once.

#define MSG_ADD_DATAREF 0x01000000

float CustomDatarefExampleLoopCB(float elapsedMe, float elapsedSim, int counter, void * refcon);

PLUGIN_API int XPluginStart( char *outName, char *outSig, char *outDesc)
{
	strcpy(outName, "CustomDatarefExample1");
	strcpy(outSig, "xplanesdk.examples.CustomDatarefExample1");
	strcpy(outDesc, "CustomDatarefExample1");

	// Defer registering for later.
	XPLMRegisterFlightLoopCallback(CustomDatarefExampleLoopCB, 1, NULL);

	return 1;
}

PLUGIN_API void XPluginStop(void)
{
	XPLMUnregisterFlightLoopCallback(CustomDatarefExampleLoopCB, NULL);
}

float CustomDatarefExampleLoopCB(float elapsedMe, float elapsedSim, int counter, void * refcon)
{
	void *Param = NULL;
	XPLMPluginID PluginID = XPLMFindPluginBySignature("xplanesdk.examples.DataRefEditor");
	if (PluginID != XPLM_NO_PLUGIN_ID){
		XPLMSendMessageToPlugin(PluginID, MSG_ADD_DATAREF, (void*)"xpsdk/example/engine/custom_whatever1");
		XPLMSendMessageToPlugin(PluginID, MSG_ADD_DATAREF, (void*)"xpsdk/example/engine/custom_whatever2");
	}
	// etc
	// etc
	return 0;
}

How This Works

  • We have to be sure the DataRefEditor plugin is fully loaded before we can tell it about our datarefs. So we register a flight loop callback. This callback will be run once x-plane is fully loaded, after all plugins are loaded and enabled. Our callback returns 0, which will cause it to not run again. (This callback is effectively a one-shot deferred callback.)
  • We find the dataref editor by signature. Note that we will get XPLM_NO_PLUGIN_ID if the dataref editor is not installed.
  • We then send it a custom message, MSG_ADD_DATAREF. The message’s parameter is a pointer to a null-terminated C string name of a dataref for it to start editing.
  • Note the high number for the dataref. “commands” and “messages” are partitioned into different numeric spaces to aid plugin interoperability. See XPLMPlugin for more info.

Older Versions