v1.50
Download
Support Forum

CSL2XSB

Convert other CSL packages

The Python script CSL2XSB can do the following to your CSL models:

  • convert packages to work with LiveTraffic, tested with X-CSL, which is often used with X-IvAp

  • enable features like rotating props and rotors, rolling wheels, opening reversers, tested on the Bluebell package

  • Make CSL packages unique to LiveTraffic, working around the "missing gear" issue when using multiple Multiplayer clients. This is an advanced feature only needed for pilots who use LiveTraffic in parallel to other multiplayer clients like XSquawkBox, X-IvAp, Swift, PE etc in the same X-Plane installation. Please understand the implications beforehand! And: This feature will no longer be needed once LiveTraffic v2.0 is available. You may just want to wait the little bit of time till v2.0 is available, for progress see here.

LiveTraffic now includes this script in the folder LiveTraffic/Resources. But it can also be downloaded separately. If interested in more details of what the script does see further down.

If you know how to work a command line and call a Python script then you'd probably better off with the description here.

The following tries to describe the necessary steps for beginners in a Windows 64 bit environment, i.e. it describes the one way I think is the most simplest:

  1. Install Python, a modern scripting language:

    1. Windows: Use the latest "Windows x86-64 web-based installer" from Python's download page.

      1. Important: Check (select) the option "Add Python 3.7 to PATH" at the bottom of the "Install Python" window.

      2. Click on "Install Now". Python will install.

      3. When done, click "Close" in the "Setup was successfull" screen.

    2. MacOS: Download the latest "macOS 64-bit installer" from Python's download page and install it by double-clicking the downloaded .pkg file and following instructions.

  2. Download the CSL package you want.

    1. X-CSL packages can be downloaded here. If you don't already have the package (e.g. because you use X-IvAp) then download and start the installer. The installer will not identify LiveTraffic as a supported plugin. Instead, from the menu select File > Select Custom Path and specify a path where the CSL packages are to be downloaded to and where they later can be updated.

    2. Download other packages as you like...

  3. Do not let CSL2XSB.py run on this original download. Always make a copy of the entire folder into a folder LiveTraffic can reach later, e.g. to <...>/LiveTraffic/Resources/X-CSL.

  4. Copy the CSL2XSB.py script into the same folder, i.e. into the base path of what you want to convert. With LiveTraffic v1.20 the script is included in the LiveTraffic/Resources folder, under which usually all CSL packages are located. That is a good place.

  5. Start CSL2XSB.py in interactive mode:

    1. Windows: Double-click CSL2XSB.py in the Windows explorer to start the script.

    2. MacOS:

      1. Open a terminal window by starting /Applications/Utilities/Terminal.app

      2. In the terminal, change to the directory where CSL2XSB.py is located, e.g. by entering: cd '/Applications/X-Plane 11/Resources/plugins/LiveTraffic/Resources' if your X-Plane installation is in /Applications/X-Plane 11. (You don't need to type all the folder names, enter 3-4 characters and hit [Tab] to extend to the full folder name.)

      3. Start the script by entering the command python3 CSL2XSB.py

  6. The script

    1. will ask you "Do you want to run CSL2XSB on the current directory "..."?". Enter "Y" and hit Enter.

    2. It then asks "Do you want to make the CSL packages unique to LiveTraffic?" Read below about it. If unsure leave this alone and just hit enter.

    3. You will see messages about the folders being processed. You might see some warnings about not found texture files, which are problems in the underlying CSL package to be solved by their developers.

    4. When done the script waits for you to hit [Enter] so you have a chance to scroll through the messages.

  7. Start X-Plane/LiveTraffic, go to CSL Settings,

    1. enter the just converted path as a new CSL path next to the already existing ones,

    2. click [Load] to check if everything is alright, and,

    3. if you want to load that package automatically next time, don't forget to place a check mark in front.

How the Script Works

The script runs over all subdirectories and changes xsb_aircraft.txt and *.obj files it finds along the way, i.e. it changes your CSL packages. You can run it directly from LiveTraffic/Resources, then it will walk over all your CSL package under that folder.

CSL2XSB tries to keep the original copies of each file with additional extension .orig. When run again and again, it even runs based on these original files, so you can just run the script over and over again, e.g. to make use of new feature added to the script. Still, you want to keep a backup of your original files.

Convert Packages like X-CSL

The main task here is to resolve an additional parameter to the OBJ8 command in xsb_aircraft.txt, introduced in other forks of the multiplayer library. These parameters allow CSL package creators to ship just one .obj file with the plane model (say A320), but several textures for different liveries (say BAW, DLH, AAL...). The additional parameters define the necessary livery texture files. This saves a lot of space as only one .obj file is necessary.

This design approach is disputed and LiveTraffic doesn't support it. Instead, CSL2XSB

  • reads these additional parameters from xsb_aircraft.txt,

  • creates the required additional .obj files pointing to the various texture files, then

  • changes xsb_aircraft.txt to point to the newly created .obj files.

So it would create A320_BAW.obj, A320_DLH.obj, A320_AAL.obj, which are essentially just copies of the original A320.obj, with just two lines changed: those defining the texture. This eats a lot more space (an additional 1.2 GB for the full X-CSL package), but stays consistent with the original format.

Along the way, the script cleans up some common errors in the xsb_aircraft.txt file. For even more details see the README.md on GitHub.

Enable Features like Rotating Props / Rotors, Rolling Wheels...

The Bluebell package contains many models, which have originally been created for WorldTraffic. The models contain already features like rotating rotors, rolling wheels or opening reversers. Before LiveTraffic v1.20 there were simply no dataRefs available to control these animations. So Bluebell just left dataRefs alone, which couldn't be mapped to an original libxplanemp dataRef, so props or wheels didn't turn.

LiveTraffic now offers a few more animation control dataRefs. The script, technically quite simplistic, includes a replacement table to replace a WorldTraffic dataRef with the matching LiveTraffic dataRef, so that LiveTraffic now can control these animations.

Making CSL Packages Unique to LiveTraffic

This feature will neither be needed nor supported with LiveTraffic v2.0. If you are on X-Plane 11 then instead consider upgrading to v2.0.

If you run LiveTraffic in parallel to other multiplayer clients like XSquawBox, X-IvAp, Swift, PE in the same X-Plane installation you will be experiencing the "Missing Gear" issue. LiveTraffic now offers a workaround for advanced users. I encourage you to understand background and workaround first before applying it.

What Do You Need To Do

  1. Make a copy of all CSL package LiveTraffic shall use - for LiveTraffic's sole access. When done, these package will no longer work with other clients:

  2. Run the CSL2XSB script on all of these packages and answer to the question Do you want to make the CSL packages unique to LiveTraffic? with Y. (or, if using the command line, add the parameter --replaceDR LT)

  3. In LiveTraffic's CSL Settings, deactivate the option Register original libxplanemp CSL dataRefs and restart LiveTraffic.

Background: The "Missing Gear" Issue

LiveTraffic, XSquawkBox, X-IvAp, Swift etc. share the same underlying library for placing and rendering planes based on OBJ files: "libxplanemp". OBJ files define what the plane looks like and also, which and how animations (like gear, flaps) and lights are supported. When being drawn, these objects query so-called dataRefs in each drawing cycle to learn about the current position of gear, flaps ets. and which lights are on. In essence, dataRefs are a flexible way for any plugin to offer access to variable values to other plugins or the sim itself. The core simulator X-Plane itself offers hundreds of them, which only allows plugins to integrate with the simulator.

But as all mutiplayer clients use the same library for this purpose these dataRefs have the very same names in all cases, no matter if it is LiveTraffic to put a plane into the sky or X-IvAp. For example, during each drawing cycle a plane reuqests the current value of dataRef libxplanemp/controls/gear_ratio to learn how much the gear is extended.

For each animation, the CSL objects need to refer to this dataRef. Here are a few lines from Bluebell's A320, which even without detailed knowledge of the anatomy of an OBJ file make comprehensible that there is an ANIMation controlled by libxplanemp/controls/gear_ratio, which rotates an object by 90 degrees:

LiveTraffic/Resources/CSL/A320_AAF.obj
ANIM_rotate_begin -0.000340 0.000000 -1.000000 libxplanemp/controls/gear_ratio
ANIM_rotate_key 0.000000 0.000000
ANIM_rotate_key 0.100000 -90.000000
ANIM_rotate_key 0.900000 -90.000000
ANIM_rotate_key 1.000000 0.000000
ANIM_rotate_end

The standard dataRef names have the advantage that CSL models can be shared across these clients: You can use the very same copy of CSL models for LiveTraffic, XSquawkBox, X-IvAp...which saves on disk space.

But the downside is that the multiplayer clients cannot fully operate in parallel: Only one plugin can successfully register this dataRef's name and then answer to requests for the current dataRef‘s content. This often seems to be LiveTraffic, probably due to it being earlier in the alphabet, which determins the startup order of plugins. So LiveTraffic‘s planes correctly move gear and flaps and lights, because when they ask the dataRef for current values the correct plugin answers, which knows the plane. But when XSB‘s or X-IvAp‘s planes are being rendered also their query for dataRef data ends up at LiveTraffic, which has no proper gear/flap/light etc. data for them and returns anything. Which usually means: No gear, no flaps, no lights for them.

The Workaround

The idea is to clearly distinguish packages between clients so each client can animate its own planes independent of others. So it solves the issue by trashing the advantage!

You make a copy only for LiveTraffic. And the CSL2XSB script changes all dataRef names in that copy by simply replacing libxplanemp by LT. Instead of using the name libxplanemp/controls/gear_ratio as all clients do, LiveTraffic can also use its own unique name LT/controls/gear_ratio.

LiveTraffic always registers its own LT/ dataRefs. No action required in LiveTraffic to make them work.

But for backwards compatibility, LiveTraffic still registers the libxplanemp/ dataRefs by default, so normal users don't feel a difference. You need to deactivate the option Register original libxplanemp CSL dataRefs in the CSL settings to free up the original dataRefs starting with libxplanemp/, so that XSquawBox, X-IvAp et al can use them. As long as that option is still active the issue of missing gear will continue to occur.

Also please note that all of the above only removes LiveTraffic from the problem. If you are really using several of the other multiplayer clients (XSquawkBox, X-IvAp, Swift, PE...) in parallel these will still be in conflict to each other and only one of them will win. So in that case there will still be some planes without gear...but at least LiveTraffic plus the winning one out of that group will be able to control their planes fully.

Last updated