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?
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?
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.
How do you sort through this? Three rules of thumb:
- Try to use
- More recent datarefs are usually better.
- Use the most useful dataref you can find.
sim/engines/carb_heat_on Carb heat on.
sim/engines/carb_heat_off Carb heat off.
sim/engines/carb_heat_toggle Carb heat toggle.
- 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.