This technote explains the details of acquiring multiplayer planes.
Why Acquiring is Necessary
Before you can call most routines in the XPLMPlanes.h API, you must "acquire aircraft" - this grants your plugin exclusive rights to manipulate them, and also informs X-Plane that it cannot. If multiple plugins were allowed to manipulate the multiplayer planes at once, there would be a risk of thrash and interop problems; the acquire API provides a simple solution.
The acquire API essentially acts as a mutex; only one plugin can acquire planes at a time. If your plugin cannot acquire planes, the routine will fail.
You can register a callback routine if you are interested in determining when planes are free at a later date. Three things to note:
- Providing a callback doesn't guarantee that it will be called.
- You must attempt to re-acquire from the callback - the callback does not pre-acquire planes for you. (This is different from the semantics of a blocking mutex in OS programming.)
- The re-acquire attempt may fail!
When Planes are Loaded and When Plugins Are Loaded
- Plugins loaded almost first at startup - before planes.
- Planes loaded later but before sim starts.
- Therefore you can acquire planes before they have been loaded.
- XPLMCountAircraft can return 0 during load because your plugin is first.
- Planes may be loaded while the sim is running if the user adjusts the rendering settings dialog box.
Request Lists and Acquiring
- When you acquire planes, your plugin can provide a model request list.
- For each non-empty slot, the sim remembers this request.
- If it needs to load a previously unloaded plane (during startup or increase of plane count) and your plugin still has planes, it loads the item from the request list.
- This allows you to avoid changing the default AI planes (which would slow startup).
- If planes are already loaded when you acquire them, the request list does nothing!!!
- Once you acquire planes, you can disable X-Plane's AI and also artifically decrease the number of planes.
- Plane count manipulations affects drawing and AI.
- Anyone can write to plane location datarefs - these are not controlled by acquire yet (an implementation defect).
- Without AI disabled (requires acquiring) writing to datarefs doesn't help - they'll be overwritten.
Disabling and Enabling and Planes
- If your plugin is disabled, planes are released.
- Therefore you may have to reacquire when enabled.
An algorithm for safe plane management
- Acquire any time enabled with a request list.
- From enable, install an immediate processing callback.
- From callback, compare loaded planes to desired planes and "set aircraft" to fix anything missing. This will lazily load aircraft only when the acquire request list fails. Callback can then cancel itself.