- 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.
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:
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.
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.
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.
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!
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.
- Try to use
- 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.
sim/autopilot/headingthat 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.