Model Matching

“Model Matching” describes how XPMP2 picks one of the installed CSL models to match with what your plugins would like to draw into the simulator’s sky. Users will have installed a varying amount of CSL models from which XPMP2 can choose.

Matching takes place


Matching is based on 3 input parameters:

All parameters are optional. Pass an empty string if you can’t provide details.

Internally, a fourth parameter named related group is added, derived from the ICAO aircraft type designator: There are many similar looking aircraft models in the world…just think of A319, A320, A321. The related.txt files combines all similar looking models into one line, which make up such a group. Each aircraft type is allowed to appear at maximum once in the entire file. The idea is to use a A320 model if a necessary A319 model is not available.

Aircraft / airline / livery combinations available for the user are listed in the xsb_aircraft.txt files in the user’s CSL model folders. XPMP2 reads all of these files into a cache when your plugin calls XPMPLoadCSLPackage, i.e. typically at startup.


Model Matching now compares 10 attributes between the parameters you pass during aircraft creation and the available models. They are rated according to the following priority from broad to fine-grained attributes:

  1. “has rotor” - this avoids picking a winged model for a helicopter
  2. ICAO aircraft class type - landplane, seaplane, helicopter, …
  3. Wake Turbulence Category - a good rough general size indicator
  4. Number of engines
  5. Engine type - jet, turbo, piston
  6. Related group - see above, groups similar-looking models like A319, A320, A321
  7. ICAO airline / operator and related group together match (this means that a “related” model with matching livery is preferred over an exactly matching aircraft with wrong livery)
  8. ICAO aircraft type designator - like A320, A388, B738, B741, C172, MD82, ..
  9. ICAO airline / operator - like AAL, AFR, BAW, DLH, SWA, WJA, …
  10. Special Livery

The better a potential CSL model matches with the passed-in parameters the more of the above attributes match, the higher is the “match quality”. Higher priority attributes count more than lower ones: technically it is a bit mask with the number 1 attribute at the most significant bit.

The model with the best match quality is picked. If there are several models ending up with the same match quality, then XPMP2 takes a random pick. This often happens if there are several models available for the expected ICAO aircraft type designator, but none of them has the correct livery for the requested operator.

There is no “default” livery any longer as there was in libxplanemp. The downside is that it is a bit harder to identify non-matching liveries: Asking twice with the same match parameters can end in different models being picked.


If you are interested in how models are picked then you can activate logging of model matching: In your configuration callback return 1 for key XPMP_CFG_ITM_MODELMATCHING and 0 or 1 for key XPMP_CFG_ITM_LOGLEVEL.

With model matching logging activated, XPMP2 writes info into Log.txt like this:

.../CSLFindMatch: MATCH INPUT: Type=BE36 (WTC=L,Class=L1P,Related=128), Airline=N13, Livery=N136HP
.../CSLFindMatch: MATCH FOUND: Type=BE20 (WTC=L,Class=L2T,Related=128), Airline=SLG, Livery= / Quality = 56 -> model BB_GA/BE20_CGSAE

.../CSLFindMatch: MATCH INPUT: Type=B737 (WTC=M,Class=L2J,Related=56), Airline=SWA, Livery=N462WN
.../CSLFindMatch: MATCH FOUND: Type=B737 (WTC=M,Class=L2J,Related=56), Airline=SWA, Livery= / Quality = 2 -> model BB_Boeing/B737_SWA

.../CSLFindMatch: MATCH INPUT: Type=DHC6 (WTC=L,Class=L2T,Related=108), Airline=CVU, Livery=N190GC
.../CSLFindMatch: MATCH FOUND: Type=BE20 (WTC=L,Class=L2T,Related=128), Airline=JEI, Livery= / Quality = 16 -> model BB_GA/BE20_DIKOB

.../CSLFindMatch: MATCH INPUT: Type=H500 (WTC=L,Class=H1T,Related=177), Airline=N91, Livery=N911WY
.../CSLFindMatch: MATCH FOUND: Type=B06 (WTC=L,Class=H1T,Related=177), Airline=PAT, Livery= / Quality = 8 -> model BB_Heli/B06_US3_31A

Note that “quality” is reported inverse here in Log.txt (as it is used in XPMP2’s code): Lower numbers are better matches.

For example: The first match (Quality = 56) is a comparably bad one… just look at the aircraft class: Wanted is a “L1P” aircraft (one piston engine), the best we found is an L2T (two turbo engines).