Home

libxplanemp has a long history and many many thanks go to people like Ben Supnik, Chris Serio, Roland Winklmeier, Matthew Sutcliffe, and its current maintainer Chris Collins.

These pages list and partly document changes I have done in this TwinFan fork. While I try to maintain backward compatibility with applications basing on the kuroneko fork I would, if need be, probably decide a bit more progressively as I am in the end not officially maintaining a public API but LiveTraffic, for which I add features as are beneficial to this specific plugin.

Changes to Multiplayer/AI/TCAS handling

The code regarding multiplayer handling has been refactored. Nearly all is now included in the XPMPMultiplayerHandling.

• AI Priorities replace previous hard-coded limits (horizontal and vertical distance) of what to show as multiplayer planes. There are at maximum 19 multiplayer slots. If there are more planes available the lib has to make a selection, previously based on distance only. (LiveTraffic issue #129)

  • Priorities are assigned per plane by the calling application via XPMPPlanePosition_t::aiPrio. 0 is the default. Lower number means more likely to be considered for multiplayer slots.
  • aiPrio is simply multiplied with kAIPrioMultiplierMeters(which is set to 10nm) and added to the actual distance. The resulting value is used for prioritising multiplayer slots.
  • For example, LiveTraffic uses this to give planes in front higher prio than to the side than in the back; and ground traffic even less priority if the user's plane is airborne.

• Slotting:

  • If a plane is shown as AI plane, then the lib tries to keep the plane in the same multiplayer slot as long as shown. I.e. if a plane has been shown as sim/multiplayer/position/plane5... once then it will be kept in slot 5. Previously, slots had been assigned based on distance to camera and kept changing as planes move. With fixed slots it is easier for other plugins to following one specific plane. E.g., the standard X-Plane map now shows the flown path. Also see LiveTraffic issue #117,
  • As some plugins take the number of AI planes as configured in X-Plane's settings into account (which strictly speaking is unnecessary...all multiplayer dataRefs are filled regardless of number of configured AI planes) libxplanemp gives the lower multiplayer slots priority:
    • The "lower" slots are as many as there are configured AI planes, say n. The first n planes according to prio x distance will be assigned the first n multiplayer positions so that the most relevant planes will appear in plugins considering n.
    • This does mean that there are occasions when planes still switch slots: When they enter or leave the group of the closest n planes.
    • Users can avoid the effect by either configuring no AI planes at all (recommended if all used plugins don't care!) or the maximum of 19.
  • The downside is, that a slot can be "empty" if the plane in it has disappeared and no replacement is yet available. The lib sets local coordinates x=y=z=9999999.9 in this case, not 0! 0 is a totally valid location. 9999999.9 is in outer space. So if you need to check for an empty slot check for x/y/z >= 9000000.
  • The lib sets the number of used AI aircraft to the highest slot index used. As an extreme case, it could report 19 while only one active plane sits in slot 19.

• Coordinates reported on the multiplayer dataRefs are now one drawing frame ahead of what is used to position rendered planes. This is effectively achieved by delaying the position used for rendering (see XPMPGetPlaneData) While this might sound weird, it supports camera plugins, which base on the multiplayer coordinates to position a camera relative to a multiplayer plane.

  • For rendering, the camera position must be known first, so camera plugins are asks early in the drawing cycle where the camera sits.
  • They use what they have at this point in time to position the camera, which are multiplayer locations calculated in the previous cycle.
  • During the cycle, the lib asks the application for new coordinates. Usually, the application provides updated coordinates for moving planes. This new coordinates don't exactly match the camera location.
  • This would not be a big issue if every drawing frame would be of exactly equal length...but they aren't. And as each frame has a tiny bit different length the camera is off by varying distances. And these variations are visible as jittering planes when viewed closely with such camera plugins.
  • Now in this version, the next position is reported in the multiplayer dataRefs, the camera plugins picks up the next location, calculates its camera position based on it, and the multiplayer planes are positioned right there. No jitter.

• All sim/multiplayer/position/plane... dataRefs are now filled, including the v_x/y/z dataRefs for cartesian velocity, which some plugins use to determine speed.

• During the callback for data type xpmpDataType_Position / XPCAircraft::GetPlanePosition the library provides the called plugin with the 1-based slot number in the new field XPMPPlanePosition_t::multiIdx, i.e. this field is an output field from libxplanemp's perspective (while all others are input field).

• Textual aircraft and flight information is provided via shared dataRefs of type xplmType_Data as suggested by FSTramp (LiveTraffic issue #144):

  • sim/multiplayer/position/plane#_tailnum - Tail number, registration
  • sim/multiplayer/position/plane#_ICAO - ICAO Aircraft type
  • sim/multiplayer/position/plane#_manufacturer - Aircraft manufacturer, human readable
  • sim/multiplayer/position/plane#_model - Aircraft model, human readable
  • sim/multiplayer/position/plane#_ICAOairline - ICAO airline/operator code
  • sim/multiplayer/position/plane#_airline - Airline/operator
  • sim/multiplayer/position/plane#_flightnum - Flight number
  • sim/multiplayer/position/plane#_apt_from - Origin airport
  • sim/multiplayer/position/plane#_apt_to - Destination airport

  The plugin using libxplanemp will be queried for these texts via a call to the XPMPPlaneData_f callback with new data type xpmpDataType_InfoTexts. ioData points to the new XPMPInfoTexts_t structure. Texts shall be zero-terminated. For performance reasons, the application shall only return xpmpData_NewData if there really is new data to be published.

  A plugin wanting to use this data must also call XPLMShareData, can optionally thereby register a notification callback, then calls XPLMFindDataRef and XPLMGetDatab as usual. Provide at least a 40 character buffer to be on the safe side.

• XPMPMultiplayerDisable possible now in mid-flight to release control of AI planes. It is important now (but was not enforced earlier) to match each call to

  • XPMPMultiplayerInitwith a call to XPMPMultiplayerCleanup, and
  • XPMPMultiplayerEnable with a call to XPMPMultiplayerDisable.

CSL dataRef Features

• A few more CSL dataRefs are now available to OBJ8 CSL models, especially for engine/prop rotation, reversers, and the touch down event. As far as possible I tried to align with the PilotEdge definitions. More details on a separate page.
• CSL dataRef root string: As a workaround for parallel usage of several libxplanemp-based plugins - until a smarter way is available or the concept becomes obsolete with instancing - the following is changed:
  • The lib now registers all CSL dataRefs with XPMP_CLIENT_NAME as the leading root string instead of libxplanemp. E.g., in LiveTraffic the gear ratio CSL dataRef is registered as LT/controls/gear_ratio.
  • Optionally and enabled by default, the lib additionally registers the original libxplanemp dataRefs as before. So if you don't do anything to your app nothing should change.
    • The application decides for registering the original libxplanemp dataRefs by returning 1 to the config option "planes"/"dr_libxplanemp" in its IntPrefsFunc callback.
  • The reason is to provide a workaround for parallel usage of several plugins based on libxplanemp. If all plugins try to register the CSL dataRefs as libxplanemp/... then only the first plugin can actually control its planes. All others cannot register the dataRefs. See LiveTraffic issue #143. With the above change it is now possible to run a plugin only with the app-specific dataRef names and hence get not into conflict with other plugins.
  • This certainly means, that also the CSL objects, specifcially the .obj files need to be changed to reference the app-specific dataRef. See the CSL2XSB script as an example how this can be achieved.

Additional Features

• Functions XPMPGetPlaneModelName, XPMPHasControlOfAIAircraft
• Docker-based build environment for Linux build (thanks to sparker!)

Fixes

• Matching by Doc8643 aircraft type in CSL_MatchPlane (part of LiveTraffic issue #44)
• SSAA scaling hack only if HDR is on (XPMPDefaultPlaneRenderer)
• Fixed a race condition causing a CTD when creating several planes using the same OBJ7 model in the same drawing cycle (LiveTraffic issue 145)
• xsb_aircraft.txt parameter interpretations and warnings (Parse... functions) corrected including valid/got LIGHTS (LiveTraffic issue #131). Repeated warnings suppressed (LiveTraffic issue #118)