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:
- sim/cockpit2/ which provides a new set of datarefs for cockpit modeling via OBJ animation and generic instruments.
- 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!
There’s a bug in X-Plane 900 RC2 that will be fixed in RC3. Basically when you’re flying in the Cirrus with a friend (also using the Cirrus via multiplayer) you’ll see your own control deflections on his or her plane.
Understanding this bug gets into the way datarefs and object animation work. In simple terms, a dataref is an access point to data provided by some other part of the sim…the flight model, or another plugin. An object references a dataref as its source for animation values. So if you want to animate the wings, you use sim/flightmodel/controls/lail1def or sim/flightmodel2/wing/aileron1_deg.
Now the question is: when you access this dataref in a multiplayer context, which aircraft’s ailerons are you talking about? It turns out the answer depends.
- For all datarefs except sim/flightmodel2/ and sim/cockpit2/, if the dataref needs to access a plane, the access is to the user’s plane (flight 0), always.
- For sim/flightmodel2/ and sim/cockpit2/, the access is usually to flight 0. But if we are drawing an aircraft, these datarefs refer to the aircraft being drawn!
(Note: this second feature only works correctly in RC3.)
So when you want to animate the wings of your plane in X-Plane 9, by using the sim/flightmodel2/ datarefs in your object, you’ll get the behavior you want: animation with the first plane’s flightmodel when your plane is loaded as plane one, animation with the second plane’s flightmodel when your plane is loaded as plane two, etc.
Of course the rule of thumb is simple: if working on v9, always prefer sim/flightmodel2/ and sim/cockpit2/ when possible for animation work.
Could we have simply made the sim/flightmodel/ and sim/cockpit/ datarefs have this “pick the right airplane” behavior? Possibly, but I took the more conservative opt-in approach. Basically any time we want to change the behavior of the sim we can do one of three things:
- Change it globally – all third party content is affected; don’t like it, too bad. This is how pixel shaders work; if shaders are on you can’t disable the different fogging they provide for your airplane or object.
- Opt-in – you have to change your content to get the new behavior; old content defaults to unchanged. This is how the new datarefs work. You have to edit your content to use the new datarefs to get the new behavior.
- Opt-out – you have to change your content to avoid the new behavior. For a while cockpit lighting was like this, but I received so many reports of version 8 airplanes looking totally strange that I changed the cockpit lighting choices to opt-in.
Generally opt-in is the safest thing we can do to leave previous content working; if we make a change globally then we break any content that doesn’t work well with our changes. Datarefs are used so heavily that a fundamental change in how they work would probably not be safe.
Given a choice between opt-in and opt-out I’ve come to prefer opt-in; both require the same amount of work for LR (we have to write code to support the old and new behavior) so why not do the thing that provides better compatibility?
Finally a general historical note: sim/cockpit2/ and sim/flightmodel2 are not just there to provide new behavior with objects; they are designed to give us a clean start in providing only authoring-related datarefs in an easier-to-understand format. The original datarefs were meant only for programmers, so we didn’t worry too much about usability. Since then, datarefs have become the communications medium for panels and a lot of 3-d animation.
So not only do sim/cockpit2 and sim/flightmodel2/ provide correct animation behavior, but they’re also easier to read.
An important distinction between sim/cockpit2 and sim/flightmodel2 is that they partition the datarefs based on perception vs. reality:
- Generally sim/cockpit2 shows datarefs as the pilot sees them in the cockpit, and actions as the pilot commands them.
- Generally sim/flightmodel2 shows the plane’s behavior as it’s really simulated, and actions as they actually happen.
In other words, when the pitot tube ices up, sim/flightmodel2 shows the real airspeed and sim/cockpit2 shows the incorrect airspeed. When the hydraulic system fails, sim/cockpit2 shows that the pilot wants to bank, and sim/flightmodel2 shows that the ailerons aren’t really moving much.
What this means is that you should use sim/cockpit2 for cockpit objects and generic instruments and sim/flightmodel2 for objects attached to the airplane exterior. This will assure that failure simulation works correctly (e.g. failures are perceived correctly by the pilot) and the external control surfaces match the plane’s physical behavior.
If you’ve studied sim/cockpit2 a lot, you know it’s pretty incomplete. We’ll be adding the rest of the cockpit systems in 910. I would have liked to get the entire set of airplane changes into 9.0 but there’s a lot more to do – not just more datarefs, but also manipulators for 3-d objects and a new lighting model for aircraft interiors. I think 910 will finish what 900 has started in terms of new airplane features.
Final random note: RC3 will allow you to pick any dataref for a generic instrument, not just sim/cockpit2 and sim/flightmodel2. This is mainly so people writing plugins can easily hook their datarefs up to the panel by editing datarefs.txt instead of typing them by hand.
I’ve blogged about this before, but…let me be totally clear:
Don’t use ATTR_cockpit in objects that are not one of the two cockpit objects for your airplane.
Don’t use ATTR_cockpit in the attached misc. objects for your plane – move the parts of the mesh that require ATTR_cockpit into the cockpit object.
Don’t use ATTR_cockpit in scenery objects.
The
OBJ spec basically says as much when it says “don’t use cockpit features” outside of cockpits.
Now what goes wrong if you violate this varies with the betas vs. X-Plane 8, but I can tell you this: no version of X-Plane has ever shipped that will correctly handle ATTR_cockpit in attached objects for all cases. There’s always been bugs in this not-such-a-good-idea code path; it’s just the severity has varied over time.
Here’s a summary of the new airplane features in 9.0 (and some coming). Hopefully this will give you an idea of what new capabilities are available for modeling planes in X-Plane 9. This list will sound like a broken record – virtually all of these features are optional; you don’t have to recut your finished airplanes to use them in version 9.
2-d vs. 3-d Panel
You may have noticed the new “3-d panel” option in PlaneMaker 9. This allows you to build a separate panel for the purpose of providing the texture to ATTR_cockpit (or ATTR_cockpit_region). You can then:
- Provide alternate instrument artwork in a cockpit_3d folder. (This lets you have perspective artwork for the 2-d cockpit and orthogonal artwork for the 3-d cockpit.)
- Pack your instruments together tightly to save space. (There is a real cost to large panels, so using a 1024×1024 panel for the cockpit object is a lot better.)
The 3-d panel is strictly optional, fully replaces the 2-d panel only for cockpit objects, and is activated by providing a custom panel background in a cockpit_3d folder. (See the “Example Plane-Widescreen+objects” plane in beta 19.)
ATTR_cockpit_region
Cockpit regions are an alternative to using the entire 2-d panel to texture your objects. They provide a few advantages:
- Performance. By requiring a power of 2 and allowing you to use a sub-area of the panel, cockpit regions avoid a lot of wasted computing that ATTR_cockpit can cause.
- Next-gen lighting. Unlike ATTR_cockpit, real 3-d lighting is applied to the panel when you use this attribute. This means that you will get a gradual decrease in light on your geometry (correct based on the angle of the sun) that matches the rest of the object.
Please note that you can mix and match which way you get your cockpit texture and whether you use the 2-d or 3-d panel feature (above) independently. However, you can only use ATTR_cockit or ATTR_cockpit_region in your airplane, not boht. ATTR_cockpit is still supported.
Generic Instruments
Generic instruments let you build instruments that follow some basic shapes (needles, tapes, etc.) that can be tied to any dataref. This both lets you customize particular instruments very precisely or create an instrument driven by a plugin dataref. These instruments are optional in version 9 – the old “premade” instruments are still supported.
New Datarefs
X-Plane 9 provides new datarefs targeted at airplane authors. The datarefs are better organized and have clearer names. But the old datarefs still exist, so legacy planes do not have to be updated.
Generally the entire cockpit should use only sim/cockpit2/ datarefs, and the plane exterior should use only sim/flightmodel2/ datarefs.
One special feature of these two sections: if your plane is used as an AI plane, these datarefs will animate the plane with the AI plane’s control deflections, not the user’s control deflections. So using these datarefs fixes the “AI animation” problem.
Plugins in Aircraft Folder
Version 9 airplanes may have a plugins folder (inside the ACF package) with fat plugins inside them. If you develop a plugin for your airplane, consider packaging it this way — this will allow your users to install the airplane with a single unzip for all platforms and no extra “drag-this-file-here”.
Plugins in the airplane folder is optional – you don’t have to provide a plugin, and plugins that are installed in the main Resources/plugins folder will still work. Still, I encourage you to use this feature because it makes the install process a lot simpler. The X-Plane SDK website will have documentation on fat plugins.
Liveries Folder
X-Plane 9 features a new “liveries” folder. Liveries (replacement exterior paint for airplanes and their attached objects) can be placed in packages in the liveries folder to greatly simplify the process of repainting an aircraft. See the “Example Plane-Widescreen+Objects” for an example.
While the liveries feature is optional, I strongly encourage anyone doing repaints to adopt it. Liveries can be switched by the user in the sim without any file manipulation; there is thus no risk of accidentally deleting or breaking an aircraft.
Large 2-d Panels
In X-Plane 9, a panel can be up to 2048×2048 in size. You pick the dimensions. The panel will scroll horizontally if necessary.
Note that if you use the new 3-d panel feature, the 2-d and 3-d panel do not have to be the same size. I would recommend a large 2-d panel (to fill large monitors) and a smaller 1024×1024 3-d panel (for performance).
Hiding Parts
X-Plane 9 will allow you to hide aircraft parts. Many v8 planes use OBJs to model the plane geometry, and use a transparent ACF texture to hide the ACF. Setting the parts to “not drawn” saves the CPU time that X-Plane would spend drawing the airplane, and is thus more efficient.
Keyframes
X-Plane 9 supports key-framed animation; this is useful for the scenery system, but for airplanes it allows for much more complex and realistic animation. OBJs that don’t have key frames still work.
Manipulators
This is a feature coming in the future: the ability to control how the user clicks and interacts with the cockpit object in detail. In X-Plane 9.0 we only support clicking on cockpit-textured geometry; manipulators will make features like draggable handles a lot more workable.
Global Illumination
X-Plane 9 does not yet offer a lot of control of the in-cockpit lighting environment; we’ll be working on this in future versions. These features will be opt-in…that is, you’ll have to change your model to get the new features, and old planes will work the way they always used to. It is likely that you’ll have to use “modern” airplane-building techniques to use these new features (meaning OBJs, named or custom lights, lego brick instruments ,etc.).
