-
Notifications
You must be signed in to change notification settings - Fork 7
LegacyCSL
NB: The documentation here is largely taken verbatim from the old CSL Developer's guide and may be incorrect in spots. I've attempted to update it where possible, but there will most likely be errors. My commentary will be annotated in blockquotes. Strikeouts will be used where either information is believed no longer relevant, but hasn't been confirmed, or the information was important in how things happened, but is definitely no longer relevant. - CC.
Original document was Copyright © 2005 Ben Supnik, Chris Serio.
As the primary developer/maintainer for XSB, I'm publishing this document openly as it has greater relevance to the open sourced libxplanemp than it does to XSB. - CC.
| Date | Changes |
|---|---|
| 2017-04-03 | Minor Updates (relating to XSB 1.3.x) |
| 6/8/05 | Initial Draft (Public Beta 9) |
This document explains how to create model sets for XSquawkBox. Read this if you want to customize the set of aircraft that you can see in XSquawkBox. This document applies to both XSB 1.0 for VATSIM and for IVAO. Differences between the clients are noted.
Making a model set can be complex and should not be attempted unless you already understand X-Plane ACF files or objects, the limits of X-Plane, and are comfortable editing text fies.
Creating custom model sets is not supported; if you build a model set and have a problem you may discuss this with other users, but we do not have time to answer specific tech support questions about model sets; build model sets at your own risk!
A plane model is a 3-d representation of an aircraft. A model is usually either an OBJ file (X-Plane 3-d object) and PNG texture image, or an ACF file (X-Plane aircraft) and PNG texture. XSquawkBox can use either format to show other planes flying on the network.
A CSL package is a folder containing one or more models, and an xsb_aircraft.txt
file that servers as a directory, describing these models. A user "installs" a CSL package by
copying it into XSB's CSL folder (in Resources/plugins/xsquawkbox/Resources/CSL).
A user may have many CSL packages installed; XSquawkBox will pick a model from one of the CSL packages by examining them in priority order, as determined by their file names. A user may reprioritize the CSLs by renaming them. (In this way the CSL system is very similar to custom scenery.)
A user can specify a default ICAO code in XSquawkBox; when a model cannot be properly matched up, XSquawkBox looks for a model with this default code. Please note that the default code is not verified; if the user sets a default ICAO code that is not represented in his installed CSL packages, then a fallback must be used.
The number of object models that XSB can load is limited only by available RAM and
VRAM. The number of ACF models that can be loaded is limited to 7 for X-Plane 6 and
9 for X-Plane 7 annd 8. We recommend that ACFs be used sparingly as models, because
the total number of ACFs allowed is very limited.
The limit on object models and ACF models was largely lifted around X-Plane 10 and now is dependent upon performance and resources. It is still not recommended to use ACF models as they're quite heavy and most ACF models are high poly and quite expensive to draw. - CC.
Important: the ACF limit is over-all and decided at startup; the 9 ACFs that are available cannot be changed based on what aircraft are nearby.
XSquawkBox can display a virtually unlimited number of aircraft, but showing more aicraft reduces framerate. The user can customize XSquawkBox to show more or less aircraft by setting runtime preferences.
You can use an ACF aircraft file or an OBJ object file to represent a model in XSquawkBox. Here are some of the trade-offs:
- You can have any number of OBJs, but only
9the system configured limit of ACFs max, among all CSL packages. - You can use multiple paint-schemes per OBJ, but only one per ACF.
- ACFs can have moving parts (real spinning rotor/prop discs, control surfaces, retractable gear).
OBJs do not animate at all. - OBJs can have many levels of detail; ACFs have only two (full detail and only lights).
- OBJs draw faster than ACFs.
Generally I recommend basing a CSL on OBJs and then possibly providing a separate ACF CSL for users who want moving parts; the user will have to pick among ACF CSLs carefully due to the 9 plane limit.
XSquawkBox matches models based on the "SquawkBox 3" system, developed by Joel DeYoung. Basically models are matched based on three parameters:
-
ICAO equipment code. This is a standard 4-digit code that uniquely identifies an aircraft. There are thousands of these codes defined for standard real-world aircraft.
-
Airline code. This is a standard 3-digit c ode that uniquely identifies a given airline. This is optional and may not be provided, for GA planes for example.
-
Livery code. This is a string (standardized by Joel for VATSIM) that defines paint schemes within an airline. This is optional, and is only used if an airline is defined. Livery codes only make sense in the context of an airline. (E.g. "CLASSIC" might look different for DAL and UAL.)
XSquawkBox also defines "related" aircraft...for example, all nine models of Boeing 737 are distinct, but are considered "related".
Each CSL XSB_aircraft.txt tags each model with an ICAO code, then optionally an airline code, then
optionally a livery code. A model can be tagged multiple times with different sets of information.
For example, a single model could be marked as a 737-700, a 737-300 SWA Shamu, and a 737-400 UAL.
Typically you will only tag a model with an airline twice though: once as ICAO/Airline and once as
ICAO/Airline/Livery. (More on this later in the xsb_aircraft.txt file format info.)
XSquawkBox's matching priority is therefore this:
- If possible, match the exact ICAO code, airline and livery.
- Match an ICAO code and airline, but not a livery.
- Match a related ICAO code, airline and livery.
- Match a related ICAO code, airline but no livery.
- Match an exact ICAO code, but no airline or livery.
- Match a related ICAO code, but no airline or livery.
- Use the default livery for the ICAO code, as defined by the user.
- Use the default livery for a plane related to the ICAO code, as defined by the user.
- Use the fallback configured model
I've edited the above list to closer reflect what happens, but it's still a gross simplification of what actually happens now, there's some additional matching passes to handle some edge cases, like GA aircraft with liveries, and a secondary fallback system that tries to match on DOC8643 paramters (hull type, engine count, engine type, etc) before using the manually set fallback type. - CC.
(Please note that these last 3 steps will only work if the user has the number of ACFs set above 1 in X-Plane 8 - under some conditions nothing may be drawn at all!)
For each of these matching steps, the match is tried against all CSL packages in order. For example, an exact match in a low priority CSL trumps an approximate match in a high priority CSL.
At no time is the "wrong" livery or airline automatically used. If a model is defined only to have a specific livery, then it will not match a no-livery query. So as the author of a CSL, you can choose to allow your B737 to be used generically (by exporting it both with and without airline) or only as a specific airline (by exporting it only without an airline.
There is no requirement that any of these values be "real world", although if you are inventing an aircraft, you should use values that do not correspond to real world airplanes.
There is no need for a user to customize any of the normal XSB text files to use non-standard codes - a user can simply type an ICAO code into the blank fields of the login dialog box.
This whole section removed as it's not relevant to libxplanemp - it's purely handled within XSB itself - it can still be found in the CSL devkit on the xsquawkbox website. Not all clients are expected to deal with the old CSL code madness. - CC.
Each CSL package must contain one "XSB_aircraft.txt" file in the root of the CSL package folder. This
file defines what models will be used for various multiplayer aircraft.
All filenames, both in the XSB_aircraft.txt file and in your package, are case sensitive. Do not
use spaces in your filenames. The line endings of the varous text files can be of any format - Mac,
Windows or Unix.
A package has at least one global package name. This identifies the package uniquely; this name must have no spaces but should be unique to your package. (Consider using your company name or own name in the package name to avoid duplicate names.) By identifying packages with global names, packages can use each other's OBJs even if a user renames the package's folder.
Global names should start with two underscores; folders within a CSL should never start with two underscores.
Advanced Authors: Technically a package can have more than one name. In this case, all
names are mapped to the same package. For example, perhaps you have published a jet package and
a turboprop package separately. Other people have used these two package's global names (__JOE_NIFTY__PROPS
and __JOE_NIFTY_JETS) to create additional liveries. For your new package you want to put all
planes in one huge package, but you still want to be compatible with these additional liveries.
Simply declare both __JOE_NIFTY__PROPS and __JOE_NIFTY_JETS as global names for your new package.
Directory paths in the XSB_aircraft.txt file should use the /, \ or : character (/ is recommended)
as a directory separator. You cannot use .. or :: to reference a parent directory. All paths must
start with a package name, but this package name can reference another package. (In this way you can
combine someone else's OBJ with your texture.)
The xsb_aircraft.txt file contains a list of models with attributes that tell XSquawkBox how to use them. The file is structured in the form of a series of one-line "commands" that define the models.
The "AIRCRAFT" and "OBJECT" commands define new models (implemented as either AIRCRAFT or OBJECTS). Attributes following these commands apply to these models until a new AIRCRAFT or OBJECT is listed.
These are the commands allowed in the xsb_aircraft.txt file:
EXPORT_NAME <global package name>
EXPORT_NAME __XPFW_JETS_1_0
The EXPORT_NAME command names your CSL package. You must have at least one of these commands
in your package, but may have more than one. All EXPORT_NAME commands should come first in the file.
Package names should always start with two underscores and be unique to your package.
DEPENDENCY <global package name>
DEPENDENCY __XPFW_PROPS_1_0
The dependency command declares that your package requires another CSL package, identified by the other package's global name. If the other package is not available in the uesr's installation, your package will not be processed. It is important to include dependency commands when you use OBJs from another package because otherwise parsing will fail partway through your package, which can cause strange behavior in XSquawkBox. Put dependency commands after your export_names. You do not need to have this command; you may have more than one if you have multiple dependencies.
AIRCRAFT <minimum version> <maximum version> <acf file>
AIRCRAFT 670 700 __XPFW_PROPS/Turboprops/BE20/Kingair.acf
The aircraft command introduces a new CSL model based on an X-Plane .acf file. A version range must be specified (in the form of 3-digit numbers) to indicate which version of the sim this ACF is for. Because you can have a version range, you may need to include multiple AIRCRAFT commands with a range of non-overlapping versions, so that exactly one AIRCRAFT will be selected.
OBJECT <filename>
OBJECT __XPFW_JETS/Jets/B747/BigBoeing.obj
The object command introduces a new CSL model that is based on an object.
TEXTURE <bitmap file>
TEXTURE __XPFW_JETS/Jets/B737/swa_737.png
The texture command overrides the texture normally used in an OBJ. Without this command, the texture for an OBJ is based on the contents of the OBJ command. If this command follows the object command, you can control the texture, to use one model with many textures.
Because the OBJECT and TEXTURE commands do not have to reference the same package (by global
name), you can use your textures with another package's objects or vice versa. In this way you
can create a package that adds additional liveries to another package.
HASGEAR YES|NO
HASGEAR NO
Normally an object is considered to having moving landing gear. if the landing gear do not retract on the plane, include a HASGEAR NO directive to prevent XSB from moving the gear. This is important for certain fixed gear planes like the C172 - without this directive, ACFs may have graphic artifacts on takeoff.
ICAO <icao code>
ICAO B734
The ICAO command maps this model to the given ICAO code without a livery or airline. The
model will be eligible as a direct model match for aircraft with this ICAO code and no airline,
or as a secondary match for a plane with a livery or airline if the correct match is not available.
AIRLINE <icao code> <airline code>
AIRLINE B734 SWA
The AIRLINE directive maps the ICAO code with airline to a livery. This model will match
the specified ICAO code only for the given airline (with no livery directly or with a livery
as a standby match).
LIVERY <icao code> <airline code> <livery code>
LIVERY B734 SWA SHAMU
The LIVERY command maps a model to an ICAO code with livery and airline; it will only be used
for an exact match.
To use an ACF as a model in XSquawkBox, you need to include the ACF and its related textures in your
CSL package. The file path given to the ACF is relative to the XSB_aircraft.txt file; you can use
subdirectories to organize your CSL.
There aren't many limits on using ACFs...just a few tips:
- Make sure you don't depend on ACFs - only 9 can be loaded, and some of those "slots" could be used by a higher priority CSL.
- If your ACF does not have retractable gear, be sure to use the HASGEAR directive to keep XSB from trying to retract the gear anyway.
- The ACF must be loadable by x-Plane; if you are going to use a new V8 aircraft, be sure to provide some kind of backup.
WARNING: You should be used to working with OBJ files and 3-d modelers before you attempt to create an OBJ model for XSquawkBox. This manual is not a guide to creating OBJs. and assumes you already understand the OBJ file format.
XSquawkBox can also use an object as a model. This technique lets XSquawkBox show a lot more than nine types of planes.
XSquawkBox's use of OBJ files is slightly non-standard; please see this list of warnings and caveats.
- No BMP support! All textures must be PNGs for XSquawkBox OBJs.
- No attribute support (except LOD) - none of the
ATTR_commands except forLODwork. You may not use materials or other suchATTRtricks; these commands are ignored. - polygon-type commands are not allowed and are ignored.
- Flashing or strobing lights are not allowed and are ignored.
- Smoke puff commands, the drive-in-movie, and cockpit panel commands are ignored.
XSquawkBox does honor the ATTR_LOD command for objects; use this command to reduce the complexity
of your model when viewed far away. At a minimum, set your model to be "lights only" at a far distance.
Otherwise a huge number of aircraft will have to be drawn at full resolution while flying en route. XSB
automatically reduces to "lights only" for ACFs; to get comparable performance it is crucial that you do
this with XSB.
Please remember that all commands must be repeated once per LOD section. So the lights must be present in each LOD section, for example.
You can include as many LODs as you want, but realistically probably only 3 are required at most - a high detail, a low detail, and lights only. With more LODs, the RAM usage for multiple LODs starts to outway performance benefits.
Unlike normal OBJs, XSquawkBox attempts to smooth-shade all aircraft by analyzing the aircraft shape. It is not necessary to use strip primitives in XSB to achieve shading; a model will look the same whether built with strips or individual triangles. The smooth and flat shade attributes have no affect on XSB and are ignored.
XSquawkBox supports a few special light colors that create special lights:
| Red | Green | Blue | Light | Notes |
|---|---|---|---|---|
| 11 | 11 | 11 | Red Navigation Light | Always on, red, for left wing tip. |
| 22 | 22 | 22 | Green Navigation Light | Always on, green, for left wing tip. |
| 33 | 33 | 33 | Anticollision Lights | Flashes red, on when engines are running. |
| 44 | 44 | 44 | Strobe Light | Bright white strobes on wingtips, the kind that blind in clouds. |
| 55 | 55 | 55 | Landing/Taxi Light | Bright white always-on lights. |
We strongly recommend using these codes rather than normal light commands for aircraft lights.
The default texture for an aicraft is specified normally in the OBJ. Howver, the XSB_aircraft.txt file can
override this texture with the TEXTURE command. This basically replaces the object texture. The advantage of
this technique is that the OBJ is only loaded into RAM once even if you have 100 different texture liveries.
For this reason it is better not to include multiple copies of the same OBJ in your package if the only thing
you are changing is the texture.
There is no advantage to using stripped primitives in XSB for performance.
All PNGs and OBJs used for OBJs in a CSL are shared - this means if you use one texture for two aircraft
or the same OBJ with different PNGs (via the TEXTURE) command, you save RAM.
It is faster to use one large texture for OBJs than many small ones, but only if a number of the smaller textures would be used. For example, if your aircraft textures are 512x512, you could put four aircraft's textures into one large 1024x1024 texture. When all four aircraft are visible at the same time, this will produce a significant framerate improvement. However, when only one aircraft is visible, this may be slower.
Probably the best use of texture merging is when planes share mostly common texture, for example, the same paint on all but the fuselage and then a custom airline logo on the fuselage.
(This is different from OBJs for scenery; with scenery, since a large number of OBJs are visible at once,
it is almost always a win to share a few big textures. With XSquawkBox it can be impossible to guess which
liveries will appear together.)
Unsure if that's true anymore, and this defeats the benefit of the asynchronous texture loader. Please don't do this anymore. - CC.
You can make an OBJ model for XSB without ever using PlaneMaker; simply use a 3-d modeler to create a model, export it or convert it to an OBJ, and you are done. But if you want to use PlaneMaker, here are a few warnings:
-
Use the special PlaneMaker build provided on the XSquawkBox website. This build has a modified OBJ export function that exports more of the plane than PlaneMaker's normal export. It also exports lights using XSquawkBox's codes and builds an extra lights-only LOD for you.
-
XSquawkBox and OBJs can only use one texture; if you use the aircraft 2 paint scheme you will have to merge or remap these textures.
-
Even the modified PlaneMaker does not export weapons.
-
Even the modified PlaneMaker does not export prop discs.
-
If you use a cockpit OBJ, you will have to merge it by hand with a 3-d editor and remap the texture.
You may need to debug your CSL package. There are a few techniques to do this.
If there is a problem loading your CSL package, XSquawkBox will print a warning to the screen once X-Plane has loaded:
There was a problem initializing XSquawkBox. Please examine X-Plane's Log.txt file for details.
Log.txt will then show the line number, package, bad line, and error for every problem with the CSL package.
XSB: Loading package: Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt
XSB WARNING: Parse Error in file Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt line 3.
OBJECT.
XSB WARNING: OBJECT command takes 1 argument.
XSB WARNING: Parse Error in file Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt line 4.
HASGEAR FOO.
XSB WARNING: HASGEAR takes one argument that must be YES or NO.
XSB WARNING: Parse Error in file Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt line 5.
OBJECT This/Is/NotRight.
XSB WARNING: package not found.
XSB WARNING: Parse Error in file Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt line 5.
OBJECT This/Is/NotRight.
XSB WARNING: the model This:Is:NotRight failed to load.
XSB: Loading package: Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Props:xsb_aircraft.txt
There are two problems that XSquawkBox cannot detect:
-
If an ACF failed to load, X-Plane replaces it with a default. To see this, dump a CSL cycle (see below); this problem is not logged to
Log.txt. -
Depending on user settings and the number of ACF, XSquawkBox may run out of ACF slots for your ACF. This is not so much an error in your CSL as a design limitation. Again, dumping a cycle, explained below, can help root this out.
This section also removed as it's XSB Specific. - CC.
You can use the .debug csl command to dump one "cycle" of the CSL system. You will get output in error.out like this:
XSB CSL:
XSB CSL: Package 2 path = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:xsb_aircraft.txt
XSB CSL: Plane 0 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A320:A320.obj
XSB CSL: Plane 1 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A320_a:A320_a_Aer_Lingus.obj
XSB CSL: Plane 2 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A320_a:A320_a_Austrian_Airlines.obj
XSB CSL: Plane 3 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A320_b:A320_b_JetBlue.obj
XSB CSL: Plane 4 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A320_b:A320_b_TED.obj
XSB CSL: Plane 5 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A333:A333.obj
XSB CSL: Plane 6 = Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Jets:A343:A343.obj
XSB CSL: Table 0
XSB CSL: A320 UAL UATED -> 4
XSB CSL: Table 1
XSB CSL: A320 AUA -> 2
XSB CSL: A320 EIN -> 1
XSB CSL: A320 JBU -> 3
XSB CSL: Table 2
XSB CSL: A318 A319 A320 A321 UAL UATED -> 4
XSB CSL: Table 3
XSB CSL: A318 A319 A320 A321 AUA -> 2
XSB CSL: A318 A319 A320 A321 EIN -> 1
XSB CSL: B731 B732 B733 B734 B735 B736 B737 B738 B739 ASA -> 11
XSB CSL: B731 B732 B733 B734 B735 B736 B737 B738 B739 LDA -> 9
XSB CSL: B731 B732 B733 B734 B735 B736 B737 B738 B739 SAS -> 13
XSB CSL: Table 4
XSB CSL: A320 -> 0
XSB CSL: A333 -> 5
XSB CSL: Table 5
XSB CSL: A318 A319 A320 A321 -> 0
XSB CSL: A332 A333 -> 5
XSB CSL: A342 A343 A345 A346 -> 6
Dumping one cycle map of planes.
[1] - B200.acf - Macintosh HD:code:design++:Resources:plugins:XSquawkBox Resources:CSL:Props:B200:B200.acf
End of cycle dump.
This is actually internal to libxplanemp - your trigger may vary in other usages, but
.debug csldoes still work in XSB - CC.
This is a highly abridged dump. Here's what this tells us:
-
We can see three planes in this CSL (plane 0 - 2) and their full paths.
-
We then have six tables that match various airplane "signature" to planes by index number. For example, in table 1, an airplane whose signature is A320 AUA will match plane 2, the A320 Austrian Airlines.
-
After each package, we have a dump of X-Plane's ACFs used by XSB - in this case just one, the B200.
The six matching tables in turn are:
- Table 0: exact matches to ICAO, airline and livery. In our case a United A320 with the TED livery maps to plane 4.
- Table 1: exact matches to ICAO and airline. In our case, an A320 Shamrock (EIN) matches to plane 1.
- Table 2: related matches to ICAO, airline and livery. In our case, any of the A318, A319, A320, and A321 in United TED colors will match to plane 4 as well.
- Table 3: related matches to ICAO and airline. In our case, Any B737 (100-900), SAS will match to plane 9.
- Table 4: exact ICAO only matches. Any A320 will match to plane 0.
- Table 5: related ICAO only matches. Any A332 or A333 will match to plane 5.
There's actually 8 'tables' used now - as the tables aren't stored whole, but in pieces that are "glued" together, there's no real reason to report them in this dump. - the missing passes are exact ICAO+Livery (before table 4), and related + livery (before table 5). You can easily work out how they're assembled by looking at tables 0 and 2 however. - CC.
You can examine this output to see which ICAO codes your plane is registered for; these must match the incoming ICAO codes
shown above with .debug models=1
Finally the most detail you can get is to use .debug matching=1. This will turn on match logging. When a new aircraft is found on the network, XSquawkBox will dump this to Log.txt:
XSB MATCH - ICAO=A321 AIRLINE=UAL LIVERY= GROUP=A318 A319 A320 A321
XSB MATCH - Skipping 0 Due Absent Livery
XSB MATCH - Group 1 key A321 UAL
XSB MATCH - Skipping 2 Due Absent Livery
XSB MATCH - Group 3 key A318 A319 A320 A321 UAL
XSB MATCH - Found: A319/UAL/ : D:\X-Plane 11\Resources\plugins\XSquawkBox\64\..\Resources\CSL/A319/A319_IAE.obj - D:\X-Plane 11\Resources\plugins\XSquawkBox\64\..\Resources\CSL/A319/UAL.png
XSquawkBox is trying to match a UAL A321, no livery. The group is A318 A319 A320 A321. (Group names are built by concatinating all related ICAO codes.)
To match this, XSquawkBox then makes eight attempts with various keys. We can see it here first skipping over a livery specific match (as there wasn't one set), then trying to find a UAL A321, then skipping the related w/ livery match, then trying to match a UAL of a related type, at which point it succeeds and stops trying to match.
There are 8 matching groups it'll attempt before it falls back to ICAO Configuration data.
libxplanemp used to do a fixed number of rounds, but there was no benefit at all to completing additional rounds when you'd already succeeded. Also, it used to make attempts to match for absent keys. Those attempts were also removed. - CC.