How do X-Plane datarefs and commands work in plugins?

In X-Plane plugin development, datarefs expose simulator state as typed values that code can read—and sometimes write—while commands represent actions such as toggling a switch or holding a starter. Plugins obtain SDK handles, use them on X-Plane’s main thread, and can publish their own datarefs and commands for other add-ons.

What is the difference between a dataref and a command?

A dataref is a named variable or array, whereas a command is a named action with press, hold and release phases.

Datarefs have types such as integer, float, double, integer array, float array or byte data. Some are read-only, some are writable, and a few advertise more than one compatible type. Our guide to finding documented X-Plane datarefs explains where the public lists come from and why unsupported private datarefs are risky.

Commands do not contain a value that a plugin reads. They tell X-Plane or an aircraft plugin that an operation began, remains active or ended. This distinction matters because directly changing a cockpit dataref can bypass system logic that the corresponding command would have run.

How should an X-Plane plugin read and write datarefs?

An X-Plane plugin should find each dataref, verify its capabilities and then use the SDK accessor matching its declared type.

1. Find and cache the handle. Pass the dataref path to XPLMFindDataRef and retain the returned XPLMDataRef. It is an opaque handle, not a pointer to the underlying variable. Check for a null result rather than assuming every aircraft or simulator version supplies the path.
2. Check its type and access. Use XPLMGetDataRefTypes to inspect the supported type flags. Before writing, check XPLMCanWriteDataRef; this prevents an invalid setter call but does not guarantee that a written value will persist.
3. Use the matching accessor. Scalar accessors include XPLMGetDatai, XPLMGetDataf and XPLMGetDatad, with corresponding setters. Arrays use the integer or float array accessors, while byte data uses XPLMGetDatab and its setter. Query an array’s length before allocating storage, respect offsets and counts, and do not assume byte data is null-terminated text.
4. Access it on X-Plane’s main thread. The general XPLM API is not a worker-thread interface. A worker may perform independent calculations, but dataref reads and writes should be marshalled back to a flight-loop callback or another permitted main-thread callback.
5. Respect ownership and lifetime. Built-in references normally remain available for the simulator session. A dataref supplied by an aircraft or another plugin may disappear when that provider unloads, so re-resolve external references after an aircraft or provider change.

Choosing a dataref write or command

Use a command when the documented interface describes an operation; write a dataref when it explicitly represents an input, target or continuously controlled value.

A writable flag only says that the SDK accepts a write. X-Plane or the aircraft may calculate the same value again on the next flight loop, making it snap back. Repeatedly forcing the value can also fight the autopilot, electrical system or aircraft plugin. Where a matching public command exists, operating that command usually preserves the intended logic, sounds and cockpit animation.

How do X-Plane command phases and handlers work?

X-Plane commands have begin, continue and end phases so they can represent both a quick button press and an action held over time.

Find an existing command with XPLMFindCommand. Use XPLMCommandOnce for a complete momentary press. For a held control, call XPLMCommandBegin when the input is pressed and XPLMCommandEnd when it is released. Every begin must eventually have an end, including when an input is cancelled or the plugin is being disabled.

A plugin can also register a command handler before or after X-Plane’s normal processing. The handler receives these phases:

• Begin: perform work that should happen once when the control is pressed.
• Continue: update an operation that remains active while the control is held. Do not treat its callback frequency as an elapsed-time clock.
• End: stop the held operation and clear any temporary state.

A handler returns 1 to allow command processing to continue and 0 to consume it. Return zero only when intentionally replacing the normal action; an observational handler should normally let other handlers and X-Plane receive the command. Never invoke the same command from inside its own handler, as that can create recursion.

How does a plugin publish custom datarefs and commands?

A plugin publishes custom datarefs with a registered data accessor and creates custom commands with a unique command name and handler.

XPLMRegisterDataAccessor defines the custom dataref’s type, writability and read or write callbacks. XPLMCreateCommand creates a command, after which the plugin registers its handler. Use a distinctive slash-separated namespace containing the developer or plugin identity because these names are global and collisions are difficult to diagnose.

Expose state through a custom dataref and actions through custom commands. Keep accessor callbacks quick and predictable: another plugin, cockpit object or script may read them frequently. Avoid setters with surprising side effects, and guard against loops in which a setter runs a command that writes the same dataref again.

This interface is also how aircraft systems connect with visual objects. Our explanation of dataref-driven XPlane2Blender animations and cockpit manipulators shows how model controls connect to plugin-owned state and commands. For the surrounding SDK, modelling and aircraft-authoring software, see our overview of the X-Plane add-on development toolchain.

Register handlers and accessors at a deliberate point in the plugin lifecycle, then unregister what the plugin owns when it stops or no longer provides the interface. References merely found through XPLMFindDataRef or XPLMFindCommand do not need to be released by the consumer.

Compatibility and common failure modes

Publicly documented interfaces are the safest choice, but a plugin should still detect each required dataref or command rather than assuming it exists in every X-Plane version and aircraft.

• The handle is null: check spelling and case, then confirm that the aircraft or provider plugin has loaded. Retry when the dependency changes, not in every frame.
• A read returns nonsense or causes instability: verify the handle and use an accessor supported by its type flags. Do not retain a reference owned by an add-on that has been unloaded.
• A written value immediately resets: another system owns the value. Find the documented input or target dataref, or use the command that represents the desired operation.
• A command remains stuck: the plugin issued begin without end. Pair the calls on release and cover disconnection, cancellation and shutdown paths.
• An action happens twice: a handler performs the action and then returns 1, allowing the normal handler to repeat it. Consume the command only when replacement is intentional.
• It works in a stock aircraft but not an add-on: the aircraft may use custom systems, commands and datarefs. Detect its published interface instead of assuming every cockpit manipulator controls a stock path.
• Frame rate falls: cache resolved handles, throttle work that does not need per-frame updates, and keep custom accessor and command callbacks short.

Avoid building released plugins around sim/private paths. They are internal implementation details rather than a compatibility contract and may change without the guarantees associated with X-Plane’s public plugin interfaces.