Copying .obj Files for Replacing Animation dataRefs and Textures

CSL packages come in different flavours. Popular ones for general use are the Bluebell and the X-CSL packages. Both come with different history. For XPMP2 to use all their features it needs to change their .obj files. Performing these changes is built into XPMP2.

Previously, the CSL2XSB.py script performed the necessary changes. But executing it was an additional step too complex for some users, and required the user to have Python 3 installed.

Now, XPMP2 includes the required operation as well, which will be applied to .obj files shortly before they are loaded as an instances, ie. only for models which are actually used.

Two kinds of operations happen and a plugin using XPMP2 can control via configuration if they shall be applied. See the XPMPIntPrefsFuncTy type definition in XPMPMultiplayer.h or the XPMP2-Sample.cpp code for CBIntPrefsFunc(). The following configuration values play a role:

section key                 type default description
models  replace_datarefs    int     0    Replace dataRefs in OBJ8 files upon load, creating new OBJ8 files for XPMP2 (defaults to OFF!)
models  replace_texture     int     1    Replace textures in OBJ8 files upon load if needed (specified on the OBJ8 line in xsb_aircraft.txt), creating new OBJ8 files

General Notes on Copied Files

If copying takes place, then a new .obj file is written into the same folder next to the original one. The file name of the copy is as follows:

For example, X-CSL defines the Lufthansa A320 as follows in A320/xsb_aircraft.txt:

OBJ8 GLASS YES A320:A320fCFMfan.obj
OBJ8 SOLID YES A320:A320fCFM.obj DLH.png A320fCFM_LIT.png

The copying operation will create the following two new files:

Each copied file includes a comment in line 4 stating its origin:

# Created by <PluginLogAcronym>/XPMP2 based on Resources/plugins/LiveTraffic/Resources/X-CSL/A320/A320fCFMfan.obj

Replacing dataRefs

This is off by default, because well curated packages won’t need it. To enable it return 1 when called for configuration item XPMP_CFG_ITM_REPLDATAREFS.

When enabled, a copy for each .obj file will be created just before it is to be loaded. In each copy, dataRefs are replaced based on the definition in <resourceDir>/Obj8DataRefs.txt. That file just lists dataRef names to be replaced with the replacement dataRef like this:

cjs/world_traffic/engine_rotation_angle1        libxplanemp/engines/engine_rotation_angle_deg1
cjs/world_traffic/main_gear_deflection          libxplanemp/gear/tire_vertical_deflection_mtr

The Obj8DataRefs.txt file available with XPMP2 defines a number of replacements to unlock more features in the Bluebell CSL models. The simple text format allows you to add/change replacement definitions easily and ship your version with your plugin.

Replacing Texture

This is on by default. You could switch it off by returning 0 when asked for configuration item XPMP_CFG_ITM_REPLTEXTURE.

A copy will only be initiated if additional textures are defined as 4th (and optionally 5th) parameter with the OBJ8 command in xsb_aircraft.txt.

The copy will then state those defined textures in the TEXTURE resp. TEXTURE_LIT commands of the .obj file.

For the Lufthansa A320 example above the TEXTURE lines will look like this: