Repository navigation
X‐Plane Aircraft Integration
X-Plane aircraft builders can integrate AviTab into their 3d cockpit where it will behave like a 'touchscreen' digital instrument.
X-Plane allows custom digital instrument regions of the 3d cockpit to be mapped to rectangular regions in a 2d panel texture. When the 3d cockpit is rendered, the regions that are mapped to the 2d panel are drawn using the texture bitmap in the corresponding region of the 2d panel. The custom digital instrument model simply needs to update its region of the 2d texture, typically whenever X-Plane requests this through a draw callback.
AviTab can be used as a custom digital instrument in the aircraft's 3d panel by assigning a region in the 2d panel texture (ie within the dimensions of the panel.png) and providing a configuration file AviTab.json alongside the aircraft's ACF file. (Note that the panel.png file does not need to have any particular image in it, and is usually simply set to a uniform black. The file is only used to provide an initial texture of the required size which will then be updated in memory by the digital instruments.)
To indicate that an aircraft has support for AviTab as a cockpit digital instrument, the aircraft builder needs to include a file AviTab.json in the same directory as the aircraft's ACF file. AviTab will look for this file whenever an aircraft is loaded, and if it is well-formed will register additional callbacks with X-Plane in order to draw on the 2d panel texture at the appropriate time.
The simplest well-formed AviTab.json will look something like:
{
"panel": {
"left": 0,
"bottom": 0,
"width": 800,
"height": 480,
"enabled": true
}
}
This instructs AviTab to draw its window into the 2d panel texture with the left-bottom (x,y) corner at (0,0) and right-top corner at (799,479). Assuming that this region has been defined as the 2d target region for a 3d cockpit instrument, and assuming that the region does not overlap with another digital instrument, then the AviTab window should appear in the 3d cockpit.
AviTab has a fixed window ratio of 5:3 (and size of 800x480 pixels), so it is advised to use the same 5:3 aspect ratio for the 2d panel region. If the 2d region has a different aspect ratio then AviTab will draw its window as large as possible and centred within the specified region while maintaining the 5:3 ratio.
Support and basic configuration of AviTab as a cockpit digital instrument is controlled by the existence of the AviTab.json file, but most aspects will be controlled at runtime using X-Plane datarefs and commands which AviTab creates at startup.
By default the AviTab panel is disabled at startup. This can be overridden by setting "enabled" to true in AviTab.json (as shown in the example above). The panel can also be enabled and disabled at runtime by writing to the dataref avitab/panel_enabled.
When the panel is disabled, AviTab will not draw on the 2d texture region. This mode allows an aircraft builder to support different sources for the same cockpit instrument (assuming that the other sources can also be disabled) so that only one model draws in any one frame.
To prevent AviTab from drawing to the panel when the 3d instrument is not powered, write to the dataref avitab/panel_powered. If the AviTab panel is enabled but not powered then AviTab will draw a uniform black texture. If the AviTab panel is enabled and powered, then AviTab will draw its normal display.
The AviTab panel brightness can be controlled by writing to the dataref avitab/brightness. This value should be a floating point number between 0.0 (dark) and 1.0 (bright).
Typically the position of the AviTab window in the 2d panel texture is specified in AviTab.json and does not change. However, if the position needs to be changed at runtime then the datarefs avitab/panel_left, avitab/panel_top, avitab/panel_width, and avitab/panel_height can be modified.
The following X-Plane commands can be used to switch directly between AviTab's apps without UI interaction:
- AviTab/app_charts
- AviTab/app_airports
- AviTab/app_routes
- AviTab/app_maps
- AviTab/app_navigraph
- AviTab/app_plane_manual
- AviTab/app_notes
- AviTab/app_about
The AviTab panel supports three methods for mouse button and wheel interaction - Aircraft Managed, Capture Window and Hybrid Commands. The Aircraft Managed mode was added in AviTab v1.1.0 and is the preferred mode for new and updated integrations. The older modes may still function and be appropriate in some situations.
The Aircraft Managed mode is enabled by adding "aircraft_managed": true to the AviTab.json panel configuration file.
In this mode, the aircraft integration is responsible for providing the current location of the mouse/pointer and sending button and wheel events.
The mouse location should be set by writing to 2 AviTab datarefs, avitab/panel_x_click and avitab/panel_y_click. The values written are the same as the values that sim/graphics/view/click_3d_x_pixels and sim/graphics/view/click_3d_y_pixels provide (or used to provide), i.e. the location of the mouse pointer within the 2d panel texture after mapping from the 3d cockpit region.
Mouse (primary) button clicks are signalled using the command AviTab/click_left. The three command phases xplm_CommandBegin, xplm_CommandContinue, and xplm_CommandEnd represent the button-down, mouse-drag, and button-up events respectively. A single xplm_CommandBegin should be followed by zero or more xplm_CommandContinue and completed with a single xplm_CommandEnd, typically sent successively in each X-Plane frame update. The mouse location datarefs should be kept up-to-date for the duration of the command.
Mouse wheel/scroll events are signalled using the commands AviTab/wheel_up and AviTab/wheel_down. The action is triggered by the xplm_CommandBegin phase. The latest mouse location should be written to the datarefs before the command is sent.
Aircraft Managed mode was added in AviTab v1.1.0. The aircraft integration can test for the existence of the above datarefs to confirm support, and possibly provide a warning or log entry if the installed version of AviTab does not support Aircraft Managed mode.
Capture Window mode was the original integration mode, and is the default mode if no other mode is explicitly selected.
In this mode, when the AviTab integrated panel is enabled, AviTab will create a (large) transparent window which it uses to capture mouse and mouse-wheel interactions that take place over the 3d cockpit region where the AviTab window is drawn. Any mouse or mouse-wheel events that are not directed at the AviTab display are ignored and X-Plane will forward these to the next window in the stack.
AviTab detects the location of the mouse when button and wheel events occur by reading the value from 2 X-Plane datarefs sim/graphics/view/click_3d_x_pixels and sim/graphics/view/click_3d_y_pixels. These datarefs provide the location of the mouse within the 2d panel texture, and read as (-1, -1) when the mouse is not over a 2d-mapped area of the 3d cockpit.
In many cases AviTab's Capture Window mode will work and is the simplest integration method. However, there are some scenarios where the Capture Window does not work, or will not be appropriate:
-
If AviTab's Capture Window interferes with existing windows of your aircraft (e.g. SASL2) then the Aircraft Managed mode should be used.
-
Since X-Plane 12, some of the newer cockpit digital instruments do not provide the X-Plane dataref 2d mouse coordinates, making the AviTab capture window non-functional. In this case, use the Aircraft Managed mode.
-
Using the mouse is not possible in VR with Capture Window mode. See the VR section below for further information. The Aircraft Managed mode is preferred as it supports monitor-based and VR/HMD users in a consistent manner.
This mode exists mainly for backward-compatibility. For new and updated integrations the Aircraft Managed mode is preferred since it provides a consistent interface and a clear chain of command.
Hybrid Commands mode is supported where the aircraft is responsible for issuing mouse button and wheel commands (as for Aircraft Managed mode), but AviTab is responsible for determining the mouse position when these events occur. This mode can be enabled by "disable_capture_window": true to the AviTab.json panel configuration file. (Note that aircraft_managed set to true will override disable_capture_window.)
In this mode AviTab does not create a Capture Window, and ignores its own mouse position datarefs, but instead uses the X-Plane datarefs sim/graphics/view/click_3d_x_pixels and sim/graphics/view/click_3d_y_pixels. As noted earler, in some cases these X-Plane datarefs do not provide the required information.
This mode exists mainly for backward-compatibility. For new and updated integrations the Aircraft Managed mode is preferred since it leaves no doubt about where AviTab is getting its control data.
AviTab's Capture Window is implemented by creating a large transparent window that covers all monitors and intercepts all mouse clicks (forwarding the ones that are not targetted at the AviTab panel). This is not supported in VR, so integrations using the Capture Window mode will not respond to mouse interactions when flying in VR.
As a workaround, AviTab detects trigger presses on the VR controllers and treats these as mouse button clicks when the VR laser is pointed at the AviTab panel. Although this works, many users find fine control of the VR controller laser much less easy than a mouse.
Additionally, since many home cockpit VR-pilots do not use VR controllers, the Capture Window mode is not the best choice for integrations intended to work in VR.
For new and updated integrations the Aircraft Managed mode is preferred. The aircraft integration should support both mouse and VR controller interactions with the 3d cockpit digital instrument, and map both of these to the AviTab position datarefs and commands described earlier.
Thanks to nhadrian for this sample integration (pre-dates support for "aircraft_managed" mode).
This X-Plane forum thread by RandomUser gives a detailed step-by-step guide to integration. A reference project can also be downloaded.
Thanks to danklaue for allowing these notes to be shared.
-
AviTab config (AviTab.json)
In the panel block, set:
left, bottom, width, height to the actual 2D panel rectangle where AviTab is rendered. enabled: true aircraft_managed: true -
Coordinate contract
Before every AviTab mouse command phase, write:
avitab/panel_x_click avitab/panel_y_clickValues must be absolute 2D panel pixels (not normalized).
Coordinate system is panel-global, origin at left/bottom, Y increasing upward.
Click command lifecycle
On mouse-down:
write x/y AviTab/click_left with xplm_CommandBeginWhile button held (drag):
each frame: update x/y, then AviTab/click_left with xplm_CommandContinueOn mouse-up:
update x/y AviTab/click_left with xplm_CommandEndWheel lifecycle
For each wheel event:
write current x/y first send AviTab/wheel_up or AviTab/wheel_down (xplm_CommandBegin)Coarse filtering in aircraft code
Only forward events intended for AviTab’s on-screen region.
Avoid sending unrelated clicks/wheel traffic outside your intended input zone.
Powered/enabled preconditions
Ensure AviTab is both powered and enabled when forwarding input.
If either is false, expect commands to be ignored.
Diagnostics verification
If no apparent response from AviTab check AviTab log lines to confirm mapping:
Creating panel @ 2048,482 size 1194x728 mode=managedIf mode is not "managed" check AviTab.json.
cmd:click_left/down(...)off-target cmd:wheel/up(...)off-target cmd:wheel/down(...)off-targetIf off-target appears on click_left/wheel entries, your aircraft is sending coordinates outside AviTab’s mapped panel window.
Common failure patterns
aircraft_managed missing: click and wheel appears non-functional.
Normalized 0..1 coords used instead of panel pixels: no interaction or off-target.
Wrong Y convention (top-origin assumptions): interactions land in wrong place.
Coordinates written after command call instead of before: intermittent misses.