Introduction
Model Set plug-ins are collections of plane models that are used for displaying planes in your vicinity. They replace the Common Shape Library (CSL) that was part of previous versions of SquawkBox.
The CSL was created because it added a large set of simplified plane models that could be used by SquawkBox for displaying nearby planes. Because the models were greatly simplified, many planes could be shown without slowing the frame rate a great deal. The main problem with the CSL was that it was not extensible. For CSL additions and enhancements to work, they had to be used by every SquawkBox user.
The plug-in approach to model sets solves this key problem. An individual SquawkBox user can now have as many or as few model set plug-ins installed as they wish, and still be compatible with other SquawkBox users. A model set plug-in can be a large, general set containing many planes, it may be a small set only containing special liveries for a single airline, or anything in between.
SquawkBox cannot run without at least one model set plug-in. SquawkBox ships with two such plug-ins: one based on the CSL models that were a part of SquawkBox 2, and one based on the VIP set of aircraft models.
About This Document
This document contains a description of what you need to do to create a SquawkBox model set plug-in. Your plug-in must conform with this document before it can be certified as SquawkBox compatible. At the end of the document are instructions about how to submit your plug-in for certification. Once certified, your model set plug-in will be listed on the squawkbox.ca web site.
How to Make a Model Set Plug-in
There are two parts to a SquawkBox Model Set plug-in:
The Flight Simulator models are comprised of the models and textures themselves, the aircraft.cfg file(s) and all other files that must reside under the aircraft subdirectory of Microsoft Flight Simulator in order for the models to be loaded by Flight Simulator. This document assumes you have adequate working knowledge of the formats and requirements of these files. Further documentation can be found in the Microsoft Flight Simulator SDK.
The SquawkBox Model Set file
The SquawkBox Model Set file is a text file with an extension of .sms which is loaded by SquawkBox when it starts. This file provides the link between SquawkBox and the planes you have created.
Conceptually, the model set file maps between aircraft names and a set of standard codes which describe the characteristics of the aircraft. There are three such standard codes: the aircraft equipment type, the airline and the livery (paint job).
The first four lines of the .sms file contain some special information about the model set.
Line 1: A 3 character identifier that uniquely identifies your model set.
Line 2: The name of your model set.
Line 3: A description of your model set.
Line 4: A URL for a web site that the user can visit to get more information about your model set.
The information in lines 2 through 4 will be displayed to the user in the SquawkBox user interface.
Each remaining line in the file specifies a single plane in your model set. Each line contains up to
four whitespace delimited tokens as follows:
Model-Title Equipment-Code [Airline-Code] [Livery-Code]
This information describes which equipment type, airline and livery are represented by each model in your model set. There should be one such entry for every unique model.
The Model-Title is the name of the aircraft specified in the Title field in the aircraft.cfg file. Microsoft Flight Simulator allows these titles to contain spaces, but you must ensure that none of the aircraft in your model set contain spaces. Furthermore, all of the titles in your model set must begin with the three characters specified on the first line of your .sms file. This ensures that you will not have any titles that conflict with other model sets.
The Equipment-Code is the standard ICAO equipment type code that this aircraft represents.
The Airline-Code is the standard airline code that this aircraft represents. For real-world airlines that are currently in operation, this is the standard ICAO 3 digit airline code. For defunct and fictional airlines, this is the standard code as defined on the squawkbox.ca web site. Note that if the airline code is omitted, this model represents a generic version of the indicated aircraft. In this case, the livery code should also be omitted.
The Livery-Code is a 5 character code specifying the special livery on this aircraft. This code must be taken from the standard list of livery codes on the squawkbox.ca web site. If this code is omitted, this model is a generic livery of the indicated airline.
Blank lines in the .sms file are acceptable and are ignored by SquawkBox. In addition, you can add comments to your .sms file with the semicolon character. All contents followed by a semicolon on a given line are ignored by SquawkBox.
Standard Codes
The codes used in the .sms file are standard codes from two sources:
The International Civil Aviation Organization (ICAO) defines standard codes for aircraft equipment types, as well as standard codes for most airlines in existence in the world. For the purposes of SquawkBox, we further define standard codes for fictional and defunct airlines, as well as standard codes for an airline's particular liveries.
Lists of standard ICAO codes for equipment types and airlines are available from a variety of sources.
You may find the following sites helpful:
International Civil Aviation Organization
airlinecodes.co.uk
Federal Aviation Administration
To obtain standard codes for defunct and fictional airlines as well as for liveries, visit the squawkbox.ca web site and click on "Standards".
Adding to the Standard Code List
If you are developing a model set and need to add a fictional or defunct airline or a livery which is not yet included in the standard lists, you may propose new codes for addition to the standard. For fictional or defunct airlines, the code must be three digits: the underscore character, followed by two alphanumeric digits. For liveries, the code must be five alphanumeric digits long. When submitting your model set for certification, you must list the codes that you are proposing for addition.
Removing Planes from the Flight Simulator User Interface
Typically, the models included in a SquawkBox model set are not intended for flying since they are only used for the purpose of displaying other aircraft in the player's vicinity. As such, you should ensure that your model set's planes do not show up in the Flight Simulator user interface. To achieve this, you have to specify a .air file for your models that indicates a non-flyable type of aircraft.
Although not documented in the Flight Simulator SDK, this is typically possible by modifying a single byte in most .air files. I will add information about the details of this technique as time allows. But for now, simply send me an e-mail and I will help you out.
Installer and Uninstaller
Your model set plug-in must include an installer and uninstaller. The installer should autmatically detect the location of both Microsoft Flight Simulator and SquawkBox on the user's computer. If the computer has multiple versions of Microsoft Flight Simulator installed, you do not have to give the user the option of installing your models to any of them. Rather, you should install your models into the Flight Simulator directory that is associated with the currently installed version of SquawkBox.
To find out where SquawkBox is installed, look in the Windows registry under:
\HKEY_CURRENT_USER\Software\Level 27 Technologies\SquawkBox\3\
When SquawkBox is installed, this registry folder should contain a key named SBDir. This key
contains a string value that contains the fully qualified paths to the main SquawkBox directory.
Your installer must copy all your models to a subdirectory of the aircraft directory located under the Flight Simulator main directory. As well, it must copy your .sms file into the aircraft directory located under the SquawkBox main directory. Your installer must also register an appropriate uninstaller with Windows to allow the user to remove the aircraft and .sms file.
Bear in mind that the user may have Flight Simulator installed on one computer and SquawkBox on another. So your installer and uninstaller must allow the user to choose whether to install/uninstall the .sms file, the models themselves, or both.
Testing your Model Set
Once you have added your model set to SquawkBox you will need to test that it works. In order to display information about what models SquawkBox has chosen for display you can use the .cheat dot comamnd. Here is a summary of how to use this command:
.cheat model <callsign>
Shows the equipment, airline and livery code for the inidicated callsign along with the local model name
that was chosen to display that model.
.cheat model
Display the same information for all planes in the current multiplayer session.
.cheat debugmp
Display the same information as planes are added to the multiplayer session.
The Model Matching Algorithm
SquawkBox searches through all the installed model set plug-ins for the best match from each model set. It assigns a score to each model based on how well that model represents the other plane. The model with the highest score is used as the matched model. The following table describes the score that is assigned.
| Equipment | Airline | Livery | Score |
| M | M | M | 10 |
| R | M | M | 9 |
| M | M | E | 8 |
| R | M | E | 7 |
| M | M | 6 | |
| R | M | 5 | |
| M | E | 4 | |
| R | E | 3 | |
| R | 2 | ||
| 0 |
If all model sets return zero for all models, SquawkBox displays the question mark aircraft.
How to Submit Your Plug-in
To submit your plug-in for testing, send an e-mail to plugins@squawkbox.ca. Arrangements will then be made to tranfer the model set plug-in and to have it tested. Every effort will be made to test your model set expeditiously.
Need Help?
Are there parts of this document that are unclear? Do you have questions? Are you having trouble getting your model set plug-in to work properly? For help use the SquawkBox Forum. The forum entitled "SquawkBox Plug-ins" is the best place for these types of questions.