The information on this page is for reference only, you do not need to worry about how X-Plane data is organized, all the necessary standard X-Plane commands and datarefs are included in SimVim input/output parameters.
If you have been working with X-Plane data manipulation, Plane Maker or external interfacing, then, for sure, you know about X-Plane data structure. If you were only flying various virtual planes, at least you've heard about "DataRefs" and "Commands" in relation to simulator control (e.g., when assigning the Joystick buttons).
All standard X-Plane commands and datarefs are named strings started with sim/.. prefix. What is the difference between them?
In short, the Commands are used to initiate action (input control functions), DataRefs are mostly used for output information (to read simulator variables and display them).
To put it simply, from a user's point of view, a DataRef can be considered an internal named variable that stores information. This variable can be writable or not. Writable DataRef can be changed either by an internal flightmodel function or by a plugin. But even if the DataRef is writable it doesn't mean that it is suited for input controls, and simply changing its value in the plugin may be not enough to change an aircraft system state.
Generally, "cockpit-related" datarefs are used in X-Plane to display information onto the screen instrument panel and "animate" on-screen switches. Or, the plugin (such as SimVimCockpit) can use them to provide data for a hardware panel. Some of them can be used as input:
You can see the large list of X-Plane datarefs sorted by category on the X-Plane Developer website. Also, you can use such plugins as DataRefTool or DataRefEditor to see the dataref list in X-Plane window.
NOTE: A "hardware" cockpit requires only a small number of datarefs from the huge X-Plane data list, namely only those used for control panels and instruments. Thus, SimVimCockpit functions use only the appropriate standard datarefs from the table below:
|Dataref prefix /../||The DataRef's purpose in X-Plane, relation to aircraft control||Used for cockpit Input/Output?|
|sim/...||This is the base X-Plane prefix for all standard datarefs and commands|
|sim/cockpit2/.../..||This is the only category where ALL datarefs can be used for cockpit input controls and outputs.||USED|
|laminar/.../...||New X-Plane-11 prefix, all datarefs under this category are used in specific Laminar plane models.||USED for specific laminar planes cockpit controls|
|These categories are not needed for cockpit controls, and used by developers to define an aircraft systems properties in Plane Maker. Some datarefs are used in SimVimCockpit custom functions||Some datarefs are used as predefined variables|
|(../weight/, ../position/, ../engine/, .) is NOT USED for any cockpit input controls and outputs, these datarefs are used to define aircraft flight model properties by plane developers for external model, animations, etc.||A few datarefs are used in SimVimCockpit|
|sim/weapons/..||For weapons properties and control - used by SimVim||Used|
|sim/operation/..||Some datarefs from this section can be used by SimVIm for the sim control||Few|
|sim/weather/..||For Weather properties and control - can used with SimVim for weather control Console.||OPT|
|sim/cockpit/.../..||Most datarefs in this category are deprecated and not needed to use! - "cockpit2/.." is used now instead!||NONE or few|
|sim/graphics/..||Everything related to sim graphics and animation, NOT USED for any cockpit input controls and outputs||NONE|
|sim/joystick/...||This category is used only for joystick settings, NOT related to other external cockpit control.||NONE|
|sim/multiplayer/..||For multiplayer mode, current properties of 20 planes, NOT used for interfacing||NONE|
|sim/network/..||For Network UDP properties, NOT used for control||NONE|
|sim/physics/..||World physics, NOT used for interfacing||NONE|
A command can be thought of as a reference to a single program function. When a command is called via X-Plane, it runs a particular function in the program that created this command (that could be X-Plane itself, a plugin, or a custom aircraft's script). This function can do whatever the programmer wants. It also accepts a single argument - the command's state (begins, continues, ends). Some commands can use all of these states, particularly the commands for "Press-and-hold" buttons - that means the function can do different things when the button is pressed, held, or released and change different dtarefs and system parameters.
You can see the list of X-Plane commands in the X-Plane's Plugins folder (the commands.txt file) . Also, you can use DataRefTool to see the command list in X-Plane window. The SimVimCockpit input functions use all standard commands from these categories:
When people start studying X-Plane custom aircrafts, they usually find out about "custom" DataRefs only. These DataRefs are created and registered in X-Plane when you start your custom plane and they have their naming rules (usually they start with a specific prefix - for example, "aerobask/.../.../" instead of the standard "sim/.../.../" ).
Many of such datarefs are used the same way as standard, just having a different name. Some of the custom daraefs are included to bring more realism to the virtual cockpit and plane systems - see some notes about this here.
You may wrongly think that all you need to control your specific custom aircraft is to find its "custom" datarefs and simply change their value when needed. But often it's not.
What is sometimes overlooked is the existence of custom commands, and that utilizing these commands for interaction with the aircraft model is often better then using custom datarefs.
The reason for that is that, commands are often programmed to do more then just change a single dataref value. While a dataref's value is important as it is used by other parts of the program to check what needs to be done, just changing the dataref value may not result in all the necessary actions being done, that are supposed to happen when a switch in the cockpit is flipped, for example.
The main thing you will need for custom aircraft data conversion for SimVim is the list of all custom commands and datarefs needed for cockpit control. Sometimes it's easily accessible (included in the aircraft), sometimes you need to find it or see the list in the DataRefTool plugin.
Search only for those commands (and datarefs) that correspond to the parameter that doesn't work. The list of all custom datarefs for your aircraft can be very large, but you probably would really need only a small part of it for your cockpit controls.
While working with custom data for your aircraft model, you should remember the following rules:
In this case the only option is using these 4 commands for rotary switch positions.
In this case you need to use the 2 commands and the dataref which is needed to monitor its current value to set switch position using the up/dn commands correctly.
(SimVim plugin will process this switch correctly, when you assign both commands and the reference dataref in the data conversion tool).
In this case you can use the dataref with 4 different values instead of commands.
But some of these commands (#1 here) can not only set the dataref value, but also initiate other functions, for example turn some annunciators, launch another system, etc. So, you may not get what you need, some function will work, some will not, so using the commands is preferable here.
Note that this is not always the case, as datarefs can also be programmed to initiate some additional functions when the value is changed, but it's up to the developer to do it.
It's the best option, always use it even if there is a writable dataref.
In this case you need to use both the command and the dataref which is needed to monitor its current value to set switch position using the toggle command correctly.
(SimVim plugin will process this switch correctly, when you assign both the command and the dataref in the data conversion tool).
In this case you can use it as in the previous case, or use the dataref only, but only if the toggle command does not initiate some other function.