PluginsForAircraft

From X-Plane SDK
Jump to: navigation, search
This page was imported from the previous wiki engine. It needs a review and cleanup of formatting. Please see this page for more information.
There are two ways to make a plug-in that is targeted at a particular aircraft:
  1. Create a plugin that needs to be installed in Resources/plugins, but identifies when the aircraft is loaded.
  2. Create a plugin that lives in the aircraft folder and is automatically loaded when the aircraft is loaded.

There are advantages and disadvantages for both options.

!!! Aircraft plugins in Resources/plugins

This technique has the advantage that it works for all versions of X-Plane and the SDK, because it only requires 1.0 SDK features.

Plugins in the Resources/plugins folder are commonly platform specific, but they can also be fat. For a description of [Fat Plugins|http://www.xsquawkbox.net/xpsdk/phpwiki/index.php?NewVersionAnnouncement] look here.

Plugins in the Resources/plugins folder are loaded following the sim, but before your aircraft is loaded. This leads to the disadvantage that it requires a more complex plugin to detect and enable itself only for your aircraft - your plugin must deal with the special state of being loaded and enabled but not being used.

(You can't disable yourself when your airplane is unloaded because, once disabled, you won't receive any messages and won't be able to re-enable yourself!)

In this design, your plugin is installed in Resources/plugins folder and uses the message XPLM_MSG_PLANE_LOADED to identify when the user loads your aircraft, and it responds appropriately. Some key points:

  • Your plugin will be loaded all the time, even when the user is not using your aircraft. So it is critical that your plugin have a low resource footprint when not in use.
  • Make sure to suspend (set a callback time of 0) for any processing callbacks and unregister any drawing callbacks and/or hide any widgets/windows.
  • If your plugin allocates memory or OpenGL resources, consider deallocating them when an airplane other than your own is loaded.

X-Plane 9 on a large machine with a number of add-ons comes close to virtual address space limits; please be aware that if your plugin has a memory footprint even when it is not running, users will not be able to have a wide variety of plugins installed at once.

! Identifying Your Aircraft

Your plugin will receive a notification when any aircraft is loaded; see IdentifyingYourAircraft to determine whether the aircraft being loaded is yours or not.

If your plugin includes flight loop callbacks and/or menu items specific to your aircraft you will want to disable your flight loop call backs and your menu items upon the load of an aircraft other than yours. A routine for accomplishing this will also be found at IdentifyingYourAircraft.


! Dealing With Overrides

Overrides are datarefs set by a plugin that disable simulator behavior, typically so that plugins can replace the behavior. For example, a plugin can override artificial stability input generation and provide its own artificial stability input. See the sim/operation/override/ datarefs for more information.

One problem with plugins per aircraft is that the plugin associated with the aircraft being loaded may receive the XPLM_MSG_PLANE_LOADED message before the plugin associated with the aircraft being unloaded. The result is that the overrides set by the plugin "coming in" are reset by the plugin "going out".

The general solution to this is, when you receive XPLM_MSG_PLANE_LOADED, use a processing callback to get a callback one frame later. By the time you get this callback, all other plugins will have gotten XPLM_MSG_PLANE_LOADED and unloaded themselves, and it will be safe to set overrides. This is similar to the techniques in DeferredInitialization for plugin startup.

(The 2.0 SDK provides XPLM_MSG_PLANE_UNLOADED, which is sent before XPLM_MSG_PLANE_LOADED, but you cannot count on other plugins disabling overrides early in response to the unloaded message, because the other plugins running might be written for the 1.0 SDK.)

!!! Aircraft plugins in the aircraft folder

This technique has the advantage of being simpler to code; when your plugin is in the aircraft's "plugins" folder, the plugin system will load your plugin whenever the aircraft is loaded and unload the plugin whenever the aircraft is unloaded.

The minor disadvantage of this technique is that it requires the 2.0 SDK. Of greater concern 2.0 SDK works only with X-Plane V9.

Plugins carried in the aircraft's "plugins" folder must be fat. Platform specific plugins in this location are ignored. For a description of [Fat Plugins|http://www.xsquawkbox.net/xpsdk/phpwiki/index.php?NewVersionAnnouncement] look here.

If you are installing or converting an aircraft specific plugin that was located in the Resources/plugins folder to a plugin now carried in the aircraft's "plugins" folder you will find that it does not work. This is because the XPLM_MSG_PLANE_LOADED used to identify the current aircraft, is sent BEFORE the fat plugin is loaded... so a fat plugin doesn't get a loaded message for its own plane.

Simply stated, the fact that it is your aircraft's plugin means that you can be sure that it is your aircraft that is being loaded. XPluginStart IS your plane load, so you just register a deferred initialization from XPluginStart. This eliminates the need to identify when your aircraft has been loaded and unloaded and it is therefore simpler for users to cope with - we recommend this technique for any aircraft/plugin combination that is targeted at X-Plane 9.0.

For unloading, the unload message is sent before your plugin is unloaded, but again - if you are a fat plugin, your plugin's operational lifetime is the same as the plane load, so you can just unregister onXPluginStop and not worry about airplane changes. You simply set up your plugin in XPluginStart when loaded and fully deallocate all resources in XPluginStop when unloaded (something your plugin should do anyway).

(Bugs in the cleanup code of your plugin will be much more visible with this technique because your plugin may be loaded and unloaded several times during a user's session as he or she changes aircraft.)

! Dealing with overrides (revisited)

Even with this technique, you must still deal with the risk that your plugin will be loaded before the XPLM_MSG_PLANE_LOADED message is sent to other (global) plugins to disable their overrides. In this case, DeferredInitialization provides the solution to two problems:

  • Deferred initialization assures that by the time you run your initialization code, all other plugins are loaded and the sim is fully loaded and
  • Deferred initialization assures that by the time you run your initialization code, all other airplane-related plugins have released their overrides.