How do I access an array dataref in an X-Plane plugin?

In a native X-Plane plugin, resolve the dataref with XPLMFindDataRef, verify that its type mask includes xplmType_IntArray or xplmType_FloatArray, then read it with XPLMGetDatavi or XPLMGetDatavf. Offsets are element indexes, and passing a null output buffer to the getter returns the array length.

Which XPLM function reads an array dataref?

The correct function depends on the array type advertised by the dataref.

Call XPLMGetDataRefTypes and test the result with a bitwise &. Do not compare the result for equality: one dataref can advertise more than one representation. A dataref with xplmType_Data is a byte block read through XPLMGetDatab, not an integer or float array.

Before writing code, check the exact dataref name, type, units and access rules. The displayed value alone does not tell you which SDK accessor it requires.

How do I read the array safely?

Read an array safely by finding its handle, querying its length and then requesting a bounded range into a correctly typed buffer.

1. Find and validate the dataref. Use XPLMDataRef ref = XPLMFindDataRef("sim/example/array"); and stop if ref is NULL.
2. Check the type mask. For a float array, test XPLMGetDataRefTypes(ref) & xplmType_FloatArray. Use the corresponding integer flag for an integer array.
3. Query the length. For a float array, call int total = XPLMGetDatavf(ref, NULL, 0, 0);. Use XPLMGetDatavi in the same way for an integer array.
4. Allocate or reuse a suitable buffer. It must contain at least as many elements as the count passed to the getter.
5. Read the required range. Call int copied = XPLMGetDatavf(ref, buffer, offset, count); and check copied rather than assuming the full request succeeded.

To read one float at index index, use float value; int copied = XPLMGetDatavf(ref, &value, index, 1);. Treat the read as successful only when copied == 1.

How do the offset and count parameters work?

The offset is a zero-based element index, while the count is the maximum number of elements to copy. An offset of 3 and count of 2 request the fourth and fifth elements; neither value is measured in bytes.

Clamp the count to the reported array length and reject negative indexes in your own code. If you do not know which element carries the value you need, our live DataRefTool inspection workflow explains how to watch individual array indexes change inside X-Plane.

How do I write to an array dataref?

Check that the dataref is writable with XPLMCanWriteDataRef, then call the setter matching its advertised array type.

Use XPLMSetDatavf(ref, values, offset, count) for floats or XPLMSetDatavi(ref, values, offset, count) for integers. These functions can replace a subsection of the array, so you do not need to rewrite every element.

The setters do not report how many elements were accepted. If confirmation matters, read the range back, while allowing for datarefs that clamp values or are recalculated by X-Plane on the next frame. A writable flag means the SDK permits a write; it does not guarantee that the value will persist.

Why does an array dataref return no values?

An empty or failed read usually comes from an unresolved handle, the wrong accessor or an out-of-range offset.

• The handle is null: verify the full, case-sensitive dataref path and ensure any plugin publishing that dataref is loaded.
• The wrong getter is being used: match Datavi to integer arrays and Datavf to float arrays.
• The type check uses equality: test the relevant bit with & because the returned value is a mask.
• The offset starts beyond the end: query the length first and check the getter's returned copy count.
• The buffer is undersized: the count passed to the getter must not exceed the number of elements available in your buffer.
• The call runs on a worker thread: keep XPLM dataref API calls on X-Plane's main thread unless the SDK explicitly documents an exception.

Should the dataref handle be cached?

Cache a valid XPLMDataRef handle instead of calling XPLMFindDataRef during every flight-loop callback.

This is the same resolve-once pattern covered in our native plugin dataref and command guidance. Reuse buffers as well, particularly for code that runs every frame. If another plugin owns the dataref and can be unloaded, stop using the old handle when that provider disappears and resolve it again after the provider returns.