The "Airplane Modeling" Datarefs

I have blogged about this before, but I will try to create one simple explanation of what's going on with sim/cockpit2 and sim/flightmodel2 datarefs.

Sandy and I (with the help of others who helped compile the list) created "new" datarefs (first released with X-Plane 9) , aimed at airplane modelers. These new sections are:

1. sim/cockpit2/ which provides a new set of datarefs for cockpit modeling via OBJ animation and generic instruments.
2. sim/flightmodel2/ which provides a new set of datarefs for airplane exterior modeling via OBJ animation.

These datarefs sometimes include new data that was not available in version 8, and sometimes they simply provide a second dataref with the same information. Why duplicate datarefs? The new datarefs have some special properties, so I wanted to have a complete set of datarefs for modelers with these new properties.

Skip to the end for the rules of thumb on how to use them.

Clean Naming

The new datarefs are designed to have longer, less confusing names; the old datarefs contained a lot of abbreviations - potentially acceptable for programmers (who are used to seeing things like fstat and chgrp on a regular basis) but not good for modelers who do not speek English as a first language. The new datarefs have long names and are more consistent in their conventions. They also contain complete documentation.

Array Sizes

You will see the array dimension of some of the new datarefs as symbolic constants, e.g. [engine] instead of [8]. This is because the dataref generation system we use knows that these new datarefs sometimes track the maximum number of parts in the aircraft structure. This tagging means that it is much simpler for Sandy and I to adjust the datarefs when Austin increases part maximums.

With the old datarefs, if Austin allows for 10 engines, Sandy and I must search for every [8] dataref and decide if it must be [10] - some will be per-engine and need to change, some will be per-battery and will not! With the new system, we simply redefine the "engine" constant to 10 and the datarefs adjust.

(Note that if your plugin really needs to run dynamically with any number of engines, the best thing to do is to read the array size using XPLMGetDatavX.)

Failure Support

There are two ways to view a dataref: before system failures (such that the dataref reflects simulated physical reality) and after system failures (such that the dataref reflects pilot indications). For example, when the pitot tube ices up, the pre-failure airspeed reflects how fast you are flying; the post-failure airspeed reflects how much crud is in your pitot tube.

Pre-failure datarefs are appropriate for animating the exterior of the airplane. For example, if the gear indicator light fails but the gear is working, you want to animate your landing gear based on the real (pre-failure) gear position, so that the gear really does look like it's down from an outside view.

Post-failure datarefs are appropriate for animating the cockpit. For example, you want to use that post-failure indicated airspeed for your air speed indicator, so that pitot ice will affect your generic instruments and animations, as well as the built-in instruments.

The new datarefs are designed to clearly provide two different views:

• sim/cockpit2/ are all post-failure whenever possible, and are thus appropriate for cockpit modeling.
• sim/flightmodel2/ are all pre-failure, and thus are appropriate for external airplane modeling.

Be careful not to swap them! You should always be using sim/flightmodel2/ for your aircraft and sim/cockpit2/ for your cockpit. If the dataref you need is in one and not the other, email me and I will add it to the right place.

Correct Multiplayer Behavior

The older datarefs all return data about the user's airplane. However if you build an object, attached to an ACF, and that ACF is loaded for a multiplayer plane, you will get incorrect results -- the user will see his own plane's actions visualized on the multiplayer plane.

The new sim/cockpit2/ and sim/flightmodel2/ datarefs handle this case correctly: they return data about whichever airplane is being drawn. Thus if your object is attached to airplane number 5 in a multiplayer session, that's the airplane that will animate your control surfaces.

(Plugin developers - outside airplane drawing, these datarefs return information about the user's flight.)

For this reason, you should always use sim/cockpit2/ and sim/flightmodel2/ - not the older sim/cockpit and sim/flightmodel/ datarefs. If the dataref you want is only in the old sections but not the new ones, email me!

What Dataref Do I Use?

Here's the rule of thumb:

• If you are targeting X-Plane 6/7/8, you must use sim/cockpit and sim/flightmodel, otherwise
• If you are targeting X-Plane 9, use sim/cockpit2 for your generic instruments and 3-d cockpit. Use sim/flightmodel2 for your attached objects.

That's all there is to it!