Skip to main content

G3X Touch Plugins

Introduction​

The G3X Touch package uses the Plugin API to allow developers to inject their own custom Typescript code into the avionics system in order to implement aircraft-specific features.

Loading Plugin Scripts​

Global plugin scripts are loaded via XML files in the html_ui/Plugins directory. The declared target of the plugin must be equal to G3XTouch in order to be loaded by the G3X Touch.

Airplane plugin scripts are loaded on a per-instrument basis via panel.xml:

<PlaneHTMLConfig>

  <Instrument>
    <Name>G3XTouch_1</Name>

    <Plugin>coui://SimObjects/Airplanes/MyAirplane/panel/Instruments/G3XTouch/Plugins/Plugin.js</Plugin>
  </Instrument>

  <Instrument>
    <Name>G3XTouch_2</Name>

    <Plugin>coui://SimObjects/Airplanes/MyAirplane/panel/Instruments/G3XTouch/Plugins/Plugin.js</Plugin>
  </Instrument>

</PlaneHTMLConfig>
tip

It is best practice to store aircraft-specific G3X Touch plugin script files (.js) in the aircraft's panel/Instruments/G3XTouch/Plugins/ subdirectory. This greatly reduces the risk of file conflicts within the sim's virtual file system, because the plugin files are contained in an aircraft-specific subdirectory.

For more detailed information on how plugins are defined and loaded, please refer to the Plugin API documentation.

Plugin Interface​

G3X Touch plugins conform to the G3XTouchPlugin interface. In addition to all functionality supported by standard plugins, G3X Touch plugins support the onInit() lifecycle callback method. This callback is called after onInstalled() has been called for all plugins on the same instrument. It is also guaranteed to be called at the beginning of the instrument's initialization process. It is recommended that any plugin initialization tasks that require interaction with core parts of the G3X Touch avionics and/or other plugins be performed in onInit().

G3X Touch plugins are passed the following references via binder:

  • The local event bus.
  • The instrument backplane.
  • The avionics configuration object (contains global options parsed from panel.xml).
  • The instrument configuration object (contains instrument-specific options parsed from panel.xml)
  • An instance of FacilityLoader.
  • The flight plan lateral path calculator.
  • The local flight management system (FMS) instance.
  • The UI service.
  • A collection of all G3X Touch navigation indicators.
  • The CAS system.
  • A provider of flight plan source data.
  • The local GDU user setting manager.
  • The local display user setting manager.
  • The local PFD user setting manager.

Plugin Functionality​

Each G3X Touch plugin can implement one or more of the following optional methods:

registerUiViews()​

This method is used to register additional views with the UI service. This method is guaranteed to be called after the base G3X Touch has registered all of its views. Therefore, you may replace views registered by the base G3X Touch by registering your own view under the same key.

caution

When replacing a base G3X Touch view, ensure that the replacement conforms to the same interface as the view being replaced. Otherwise, you may encounter runtime errors.

In addition to the UI service, a context object is also passed to this method. The context object contains references to all items not already referenced by the plugin binder that are required to create the base G3X Touch views. These references are provided primarily to make it easy to replace any of these views. However, you are also free to use them when creating brand new views.

registerMfdMainPages()​

This method is used to register additional MFD main pages. This method is guaranteed to be called after the base G3X Touch has registered all of its pages. Therefore, you may replace pages registered by the base G3X Touch by registering your own page under the same key.

In addition to the page registrar, a context object is also passed to this method. The context object contains references to all items not already referenced by the plugin binder that are required to create the base G3X Touch MFD main pages. These references are provided primarily to make it easy to replace any of these pages. However, you are also free to use them when creating brand new pages.

registerPfdPages()​

This method is used to register additional PFD pages. This method is guaranteed to be called after the base G3X Touch has registered all of its pages. Therefore, you may replace pages registered by the base G3X Touch by registering your own page under the same key.

In addition to the page registrar, a context object is also passed to this method. The context object contains references to all items not already referenced by the plugin binder that are required to create the base G3X Touch PFD pages. These references are provided primarily to make it easy to replace any of these pages. However, you are also free to use them when creating brand new pages.

registerPfdInsets()​

This method is used to register additional PFD insets. This method is guaranteed to be called after the base G3X Touch has registered all of its insets. Therefore, you may replace insets registered by the base G3X Touch by registering your own inset under the same key.

In addition to the inset registrar, a context object is also passed to this method. The context object contains references to all items not already referenced by the plugin binder that are required to create the base G3X Touch PFD insets. These references are provided primarily to make it easy to replace any of these insets. However, you are also free to use them when creating brand new insets.

renderEis()​

This method is used to render custom EIS content. An EIS rendered in this way will replace all EIS components configured in panel.xml.

note

Support for displaying an EIS must still be declared in panel.xml via the <Eis> tag before EIS content can be rendered by plugin. If the <Eis> tag is not properly defined in panel.xml, then no EIS will be displayed in the G3X Touch, even if one or more plugins return a non-null value from renderEis().

If multiple plugins render their own custom EIS contents with this method, then only the one from the plugin that was loaded last is used.

renderToPfdInstruments()​

This method is used to render additional components onto the PFD display. Components rendered in this way will be rendered into the DOM after all base G3X Touch components. Therefore, these additional components will by default appear on top of any overlapping base G3X Touch components.

caution

When positioning components within the PFD display, remember that the display changes size when switching between Fullscreen and Splitscreen modes, and when the EIS is toggled on/off (if the installation supports displaying an EIS). Additionally, certain base G3X Touch components in the display may change their size, visibility, and/or positioning when the above changes occur.

getPersistentGlobalSettings()/getPersistentLocalSettings()​

These methods are used to define user settings whose values should be saved across flights. Settings marked as persistent in this manner will be saved via the MSFS DataStore API to the user's cloud save file. Saved settings are loaded during instrument initialization when loading a new flight. Persistent settings are saved on a per-aircraft basis (determined by the airplane's ATC_MODEL).

Global settings are those whose un-aliased names are unique across all G3X Touch instruments. These are typically settings that are synced across different JS/HTML instruments. Local settings are those whose un-aliased names are unique within each G3X Touch instrument, but may not be unique when compared across different instruments. These are typically settings that are not synced across instruments (e.g. those managed by a DefaultUserSettingManager instantiated with the keepLocal option).

tip

A new cloud save data key is generated and written for each persistent user setting per aircraft as soon as the instrument initializes after loading a flight. Currently there is no mechanism by which you can remove data keys from cloud save files. This means that once a key is added to a cloud save, it can never be removed.

As such, it is highly recommended that you finalize the names of all would-be persistent user settings before allowing them to be saved. This will help to minimize the number of "junk" keys written to the cloud saves of anybody running your plugin code.