Datarefs Vs. Commands IV: Duplication

In my previous posts I have tried to explain the difference between commands and datarefs, and when you might use each.  To review:

• A dataref represents information. You can always read it, and you might be able to change it.
• A command represents an action.  You can always invoke the action, but you can't tell if it worked without looking at a dataref.

So...why is there so much overlap and duplication?

Dataref Vs. Dataref

There is duplication in the datarefs because we don't delete old datarefs when we add newer, improved ones. The old datarefs stay in place to keep old plugins working. Here are a few reasons why we've added new datarefs:

• The cockpit2/ and flightmodel2/ sections were added as a new, simpler, easier to use interface for authors in version 9.  (Read more here and here and here.)
• In some cases, the old dataref was a bit-field while the new one is a simple integer. While plugins can use bitfields, modelers cannot animate using bit fields.
• In some cases, the old dataref did not represent a clean view of the data. Some old datarefs exposed X-Plane internal structures that are not appropriate for long-term use.

To see this in action, let's look at the autopilot.  How many ways are there to set the autopilot mode?

1. sim/cockpit/autopilot/heading_mode. This is the original heading mode, and it is marked deprecated, because it exposes a bunch of internal X-Plane autopilot values.
   
2. sim/cockpit/autopilot/autopilot_state. This is the ideal autopilot dataref for plugins. It provides all functions, but since it is a bit-field it is not useful for authors.
   
3. sim/cockpit2/autopilot/heading_mode. This is a clone of the original heading_mode into the cockpit2 domain. Honestly I am not sure how it got there - I know it was me who put it there, but it sure is a dumb idea; the original dataref is deprecated, so it was stupid of me to duplicate it!
   
4. sim/cockpit2/autopilot/heading_state. This is coming in 930 and provides a heading-state enum set appropriate for authors...basically an enum that matches the two heading bits of the autopilot_state dataref that programmers were using.
   

How do you sort through this? Three rules of thumb:

• Try to use sim/cockpit2 and sim/flightmodel2 when possible.
• More recent datarefs are usually better.
• Use the most useful dataref you can find.

Commands Vs. Commands

Sometimes there is some duplication of commands, e.g.

sim/engines/carb_heat_on                           Carb heat on.
sim/engines/carb_heat_off                          Carb heat off.
sim/engines/carb_heat_toggle                       Carb heat toggle.

Here it's a lot more obvious why there are multiple commands: they affect the carb heat in multiple ways. Typically this is done because commands are mapped to joysticks and other USB hardware; some hardware generates a button press when a command is toggled, but some hardware generates two commands, one for the off and one for the on position.

The rule of thumb is: use the command that gives you the action you want.

Commands Vs. Datarefs

Very often there will be a command and a writable dataref.  Typically we need them both:

• The command is needed to let users set up their joystick and keyboard.
• The dataref predates version 9 - writing it was the only way to invoke an action.

Newer datarefs are more likely to be read-only, as we put new "changing the sim" functionality into commands.  To go back to our autopilot example, we have on command: sim/autopilot/heading that lets us arm heading mode.  This command is probably preferable to any of the datarefs for changing the autopilot state.

My previous post discusses writing to a dataref. vs. actuating a command in more detail.