XPMP2
X-Plane multiplayer library 2 - using instancing
Classes | Namespaces | Macros | Typedefs | Functions | Variables
AIMultiplayer.cpp File Reference

Implementation of serving TCAS target dataRef updates. More...

#include "XPMP2.h"

Classes

struct  XPMP2::multiDataRefsTy
 Keeps the dataRef handles for one of the up to 19 legacy AI/Multiplayer slots ("sim/multiplayer/position") More...
 
struct  XPMP2::infoDataRefsTy
 Keeps the dataRef handles for one of the up to 63 shared data slots ("sim/multiplayer/position/plane#...") More...
 
union  XPMP2::TcasLightsTy
 A structure simplifying communicaton with sim/cockpit2/tcas/targets/position/lights. More...
 
struct  XPMP2::TcasLightsTy::BitsTy
 

Namespaces

 XPMP2
 

Macros

#define INFO_AI_CONTROL   "Have control now over AI/Multiplayer planes"
 
#define INFO_AI_CONTROL_ENDS   "Released control of AI/Multiplayer planes"
 
#define INFO_REMOTE_CLIENT_AI   "XPMP2 Remote Client controls TCAS. We don't need control as our planes will show up there."
 
#define WARN_NO_AI_CONTROL   "%s controls TCAS / AI. %s could NOT acquire control, our planes might NOT appear on TCAS or 3rd party apps."
 
#define DEBUG_AI_SLOT_ASSIGN   "Aircraft %llu: ASSIGNING AI Slot %d (%s, %s, %s)"
 
#define DEBUG_AI_SLOT_RELEASE   "Aircraft %llu: RELEASING AI Slot %d (%s, %s, %s)"
 
#define MSG_ADD_DATAREF   0x01000000
 Message to DRE/DRT to inform about dataRefs. More...
 
#define SET_DR(ty, dr)   XPLMSetData##ty(drTcas##dr, v##dr.data(), 1, (int)v##dr.size())
 
#define FIND_PLANE_DR(membVar, dataRefTxt, PlaneNr)
 
#define SHARE_PLANE_DR(membVar, dataRefTxt, PlaneNr)
 
#define UNSHARE_PLANE_DR(membVar, dataRefTxt, PlaneNr)
 

Typedefs

typedef std::map< float, XPMPPlaneIDXPMP2::mapAcByDistTy
 Map of Aircrafts, sorted by (priority-biased) distance. More...
 

Functions

void XPMP2::AIMultiClearAIDataRefs (multiDataRefsTy &drM, bool bDeactivateToZero)
 Resets all actual values of the AI/multiplayer dataRefs of one plane to something initial. More...
 
void XPMP2::AIMultiClearInfoDataRefs (infoDataRefsTy &drI)
 Clears the shared info dataRefs. More...
 
bool XPMP2::GoTCASOverride ()
 Are we going to new (TCAS override) or the old way? More...
 
size_t XPMP2::AIUpdateMultiplayerDataRefs ()
 The old way: Update Multiplayer dataRefs directly. More...
 
size_t XPMP2::AIUpdateTCASTargets ()
 The modern way: Use TCAS override and update TCAS targets. More...
 
void XPMP2::AIAssignSlots (size_t fromSlot, size_t toSlot)
 Assigns slots, ie. planes to places in gSlots. More...
 
void XPMP2::AIMultiUpdate ()
 Updates all TCAS target dataRefs, both standard X-Plane, as well as additional shared dataRefs for text publishing. More...
 
int XPMP2::AIMultiControlPlaneCount (XPLMDrawingPhase, int inIsBefore, void *)
 Callback to toggle aircraft count ("TCAS hack") More...
 
void XPMP2::AIMultiClearTcasDataRefs ()
 Clears the key (mode_s) of the TCAS target dataRefs. More...
 
void XPMP2::AIMultiInitAllDataRefs (bool bDeactivateToZero)
 Reset all (controlled) multiplayer dataRef values of all planes. More...
 
void XPMP2::AIMultiInformDREs ()
 Inform DRE and DRT of our shared dataRefs. More...
 
void XPMP2::AIMultiInit ()
 Initialize the module. More...
 
void XPMP2::AIMultiCleanup ()
 Grace cleanup. More...
 
const char * XPMPMultiplayerEnable (void(*_callback)(void *), void *_refCon)
 Tries to grab control of TCAS targets (formerly known as AI/multiplayer) from X-Plane. More...
 
void XPMPMultiplayerDisable ()
 Release TCAS targets control. More...
 
bool XPMPHasControlOfAIAircraft ()
 Has XPMP2 control of TCAS targets? More...
 

Variables

constexpr float XPMP2::FAR_AWAY_VAL_GL = 9999999.9f
 Don't dare using NAN...but with this coordinate for x/y/z a plane should be far out and virtually invisible. More...
 
constexpr float XPMP2::AISLOT_CHANGE_PERIOD = 15.0f
 How often do we reassign AI slots? [seconds]. More...
 
constexpr int XPMP2::AI_PRIO_MULTIPLIER = 10 * M_per_NM
 How much distance does each AIPrio add? More...
 
float XPMP2::F_NULL [10] = { 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f}
 A constant array of zero values supporting quick array initialization. More...
 
constexpr int XPMP2::XPLM_PHASE_AIRPLANES = 25
 The drawing phase "xplm_Phase_Airplanes" is deprecated in XP11.50 upwards, but we need it in earlier versions to fake TCAS. More...
 
const char * XPMP2::DATA_REF_EDITORS []
 
std::vector< std::string > XPMP2::vecDREdataRefStr
 list of dataRef strings to be send to the editors More...
 
constexpr size_t XPMP2::SDR_CSLMODEL_TXT_SIZE = 40
 Number of characters to be allowed for CSL model text. More...
 

Detailed Description

Implementation of serving TCAS target dataRef updates.

Updates the up to 63 slots of X-Plane's defined TCAS targets, which are in turn synced with the 19 "legacy" multiplayer slots, which in turn many other plugins (like TCAS implementations or map tools) read to learn about any multiplayer aircraft.
Also serves shared dataRefs for publishing text information, which is not X-Plane standard but originally suggested by FSTramp. However, the post and file, in which he suggested this addition, is no longer available on forums.x-plane.org. Still, XPMP2 fullfills the earlier definition.

See also
X-Plane 11.50 Beta 8 introduced a new way of informing X-Plane of TCAS targets, see here a blog entry for details: https://developer.x-plane.com/article/overriding-tcas-and-providing-traffic-information/
Author
Birger Hoppe

Class Documentation

◆ XPMP2::TcasLightsTy

union XPMP2::TcasLightsTy

A structure simplifying communicaton with sim/cockpit2/tcas/targets/position/lights.

Class Members
struct BitsTy b
int i the full integer value

◆ XPMP2::TcasLightsTy::BitsTy

struct XPMP2::TcasLightsTy::BitsTy
Class Members
bool beacon: 1 Beacon lights.
bool land: 1 Landing lights.
bool nav: 1 Navigation lights.
bool strobe: 1 Strobe lights.
bool taxi: 1 Taxi lights.

Macro Definition Documentation

◆ DEBUG_AI_SLOT_ASSIGN

#define DEBUG_AI_SLOT_ASSIGN   "Aircraft %llu: ASSIGNING AI Slot %d (%s, %s, %s)"

◆ DEBUG_AI_SLOT_RELEASE

#define DEBUG_AI_SLOT_RELEASE   "Aircraft %llu: RELEASING AI Slot %d (%s, %s, %s)"

◆ FIND_PLANE_DR

#define FIND_PLANE_DR (   membVar,
  dataRefTxt,
  PlaneNr 
)
Value:
snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr); \
drM.membVar = XPLMFindDataRef(buf);

◆ INFO_AI_CONTROL

#define INFO_AI_CONTROL   "Have control now over AI/Multiplayer planes"

◆ INFO_AI_CONTROL_ENDS

#define INFO_AI_CONTROL_ENDS   "Released control of AI/Multiplayer planes"

◆ INFO_REMOTE_CLIENT_AI

#define INFO_REMOTE_CLIENT_AI   "XPMP2 Remote Client controls TCAS. We don't need control as our planes will show up there."

◆ MSG_ADD_DATAREF

#define MSG_ADD_DATAREF   0x01000000

Message to DRE/DRT to inform about dataRefs.

◆ SET_DR

#define SET_DR (   ty,
  dr 
)    XPLMSetData##ty(drTcas##dr, v##dr.data(), 1, (int)v##dr.size())

◆ SHARE_PLANE_DR

#define SHARE_PLANE_DR (   membVar,
  dataRefTxt,
  PlaneNr 
)
Value:
snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr); \
if (XPLMShareData(buf, xplmType_Data, NULL, NULL)) { \
drI.membVar = XPLMFindDataRef(buf); \
vecDREdataRefStr.push_back(buf); \
} \
else drI.membVar = NULL;

◆ UNSHARE_PLANE_DR

#define UNSHARE_PLANE_DR (   membVar,
  dataRefTxt,
  PlaneNr 
)
Value:
snprintf(buf,sizeof(buf),"sim/multiplayer/position/plane%u_" dataRefTxt,PlaneNr); \
XPLMUnshareData(buf, xplmType_Data, NULL, NULL); \
drI.membVar = NULL;

◆ WARN_NO_AI_CONTROL

#define WARN_NO_AI_CONTROL   "%s controls TCAS / AI. %s could NOT acquire control, our planes might NOT appear on TCAS or 3rd party apps."

Function Documentation

◆ XPMPHasControlOfAIAircraft()

bool XPMPHasControlOfAIAircraft ( )

Has XPMP2 control of TCAS targets?

See also
XPMPMultiplayerEnable()

◆ XPMPMultiplayerDisable()

void XPMPMultiplayerDisable ( )

Release TCAS targets control.

Afterwards, XPMP2's aircraft will no longer appear on TCAS or on 3rd-party plugins relying on TCAS targets dataRefs.
Is called during XPMPMultiplayerCleanup() automatically.

◆ XPMPMultiplayerEnable()

const char* XPMPMultiplayerEnable ( void(*)(void *)  _callback = nullptr,
void *  _refCon = nullptr 
)

Tries to grab control of TCAS targets (formerly known as AI/multiplayer) from X-Plane.

Only one plugin can have TCAS targets control at any one time. So be prepared to properly handle an non-empty response that indicates that you did not get control now. The returned message includes the name of the plugin currently having control.
If successful, XPMP2's aircraft will appear on TCAS and are available to 3rd-party plugins relying on TCAS tagrtes or multiplayer dataRefs.
Typically, a plugin calls this function just before the first aircraft are created. But it could also be bound to a menu item, for example.

Parameters
_callback(optional) You can provide a callback function, which is called directly by X-Plane when control of TCAS targets is not successful now but becomes available later.
_refCon(optional) A value just passed through to the callback.
See also
X-Plane SDK documentation on XPLMAcquirePlanes for more details about the callback.
Returns
Empty string on success, human-readable error message otherwise, includes name of plugin currently having TCAS tagrets control