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/andflightmodel2/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
sim/cockpit2andsim/flightmodel2when 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.
Hi Ben,
Regarding your post: “To go back to our autopilot example, we have on command: sim/autopilot/heading that lets us arm heading mode.”
Did you mean “sim/cockpit/autopilot/heading” instead?
Following this line, my version of dataref.txt recommends using:
“sim/cockpit/autopilot/heading_mag” as this is the preferred setting.
Thanks
Bob (7g_pull on X-Plane forum)
Hi Bob, Yeah – I think you are right – that should be sim/cockpit/autopilot – I will edit the post.
Oops — Bob, the original article text is correct. The COMMAND for the autopilot is:
sim/autopilot/heading
see commands.txt in beta 7. Basically commands are not divided into cockpit and flightmodel. All commands are actuated from the cockpit…that is, commands represent what the pilot wants, which is only sometimes what really happens!
I have a question about commands and their callbacks. Does the callback get bound to one command (with XPLMRegisterCommandHandler), or can a set of commands all use the same callback (albeit with different inRefcon pointers)?