XPlane2Blender v3.6.0-alpha.1

XPlane2Blender 3.6.0-alpha.1, aka, The 2.49 Converter

This is 3.5.1-beta.1 + the long in development 2.49 converter. These release notes tell you not only what is new, but how to run it as well!

An Important Note!

1. BACKUP YOUR PROJECTS! There is no going back after saving a 2.49 .blend with 2.79.
2. EXTREMELY IMPORTANT: If you already have XPlane2Blender for 2.49 installed, backup your DataRefs.txt file!

2.49 Converter Features

What does "Converter" Mean Anyway?

"The converter" refers to a certain feature of XPlane2Blender v3.6.0-alpha.1 and runs on every scene after the .blend file is opened. There are other scripts and tools to prep 2.49 files for it too.

I feel it is important to set up expectations properly for what this process will and will not do.

The converter's goal is to use old XPlane2Blender and Blender 2.49 data and copy, transform, add, and replace it. The new project should feel familiar and export functionally equivalent OBJs. It should not need much fixing in Blender 2.79. The converter assumes every OBJ in the .blend exports correctly, and ignores invalid and incorrect data. The converter logs, per scene, when it has difficulties or is about to make a change to your original data.

What this means in detail:

• "old XPlane2Blender and Blender 2.49 data" - The converter only cares about data related to Exporting v9 and up OBJs - no Autogen or Roads or other old features
• copy, transform, add, and replace - Most of the converter's work is copying data to the right place. As you can see, the converter never truly deletes data.
• "the new project feels familiar" - The converted project should be intuitive and true to the artist's previous workflow
• "a functionally equivalent OBJ" - The product of convertered files should look and act the same, but will not have the same character for character content
• "without much fixes" - Even if the converter runs correctly, the exporter might say some 2.49 decisions are invalid. Hopefully, not often
• "assumes every OBJ...exports correctly" - The converter was designed to ignore bad data and no provides no auto corrections
• "it logs, per scene" - Per scene, and not per OBJ, there is a log of what was ignored and other important events

At the end of the process you will have a modern project, based off data from the old world of 2.49

Major Missing Features

• Use of Unicode characters anywhere we care about (like object names and file paths) except the Text Editor, may crash Blender 2.79 entirely
• A nice UI for running this instead of the command line (don't be scared, I'll show you how!)
• Currently, for Bulk Script users, some non-exporting objects will not be converted
• Only empties starting with "OBJ" which have no parents are converted to Root Objects. "GRP", "VRT", and "END" are unused
• Use of Groups to control draw order
• surface, deck, group_{terrain, beaches, shoulders, etc} Game Properties
• COCKPIT_REGION
• Despite exporting without errors, the draw state order may be different

Getting Ready

Now that you know what to expect and the limitations of the converter, it is time to prepare.

Download and Install Software

Use of Blender 2.49 is optional, but recommended. If you cannot easily install Blender 2.49, try to convert your project, and if you don't get the results desired, you will have to find a way to fix the file in 2.49 or proceed by hand.
If you are unsure what is causing poor results, e-mail me (ted at x-plane dot com).

1. As mentioned before, BACKUP YOUR PROJECTS! There is no going back after saving a 2.49 file with 2.79.
2. EXTREMELY IMPORTANT: If you already have XPlane2Blender for 2.49 installed, backup the 2.49's copy of the DataRefs.txt file!
3. Download Blender 2.49b2 and see if it still works for you. If it doesn't and the conversion goes poorly, consider finding an old computer for this process.
4. Install the Laminar Research version of XPlane2Blender for 2.49, which the converter is based on. Unzip the contents into the .blend/scripts folder. The .blend folder is probably located in your user directory.
5. Download Blender 2.79b if you haven't, install this v3.6.0-alpha.1 addon. Help installing here
6. Download start_converter.py. Put wherever it is convenient for you.

2.49 Prep Work (If Possible)

7. If your .blend has animations, run Scripts > Misc > X-Plane Prepare Dropped Actions Text File once and save the project. This makes an internal text file (FixDroppedActions.py) which the converter will use later. It will not change the contents of your .blend file. It does not need to be edited or reviewed. It will not make a text file is there are no actions.
8. If Blender 2.49 works for you, try exporting every OBJ and loading it in X-Plane. Fix any errors you find, save, and repeat. The cleaner the input, the better the conversion. The better the conversion, the less you'll have to do by hand.

IMPORTANT: The converter requires that XPlane2Blender v3.6.0-alpha.1's DataRefs.txt be equivalent to what your project used in 2.49. Otherwise it is likely the converter will be unable to copy some X-Plane Dataref information and you'll have to redo this work by hand in 2.79.

v3.6.0-alpha.1 stores this file with the addon in addons/io_xplane2blender/resources/DataRefs.txt (the "resources" folder), XPlane2Blender for 2.49's copy is found with the other scripts in the "scripts" folder. The DataRefs.txt file in v3.6.0-alpha.1 and Laminar Research 2.49 scripts zip are the same.

The DataRefs.txt file in the "resources" folder is what the converter uses. The DataRefs.txt file in the "scripts" folder is for the 2.49 exporter.

If you're having trouble finding these folders, read this guide.

• If you can run Blender 2.49, great! Next, follow step 8.
• If you can't run Blender 2.49 or are having a difficult time exporting or converting, see Troubleshooting: "What happened with DataRefs.txt?" down below

Even if you have trouble with this step, the Blender Loc, Rot Keyframes and Actions will usually be preserved (see "Troubleshooting: Blender animations are missing!"). It is only the X-Plane Dataref information that is affected by the DataRefs.txt, and 2.79 has new better tools to input those.

Let's Run The Converter!

Currently the converter must be started from the command line. If you have never used this before, it is easy. Open up Terminal (on Mac) or cmd.exe (on Windows) and type in the following:

{full path to Blender 2.79} {full path to old .blend to be converted} -P {path to start_converter.py} -- --project-type {AIRCRAFT or SCENERY} --workflow-type {BULK or REGULAR}

Here is an example from my computer

"C:\Program Files\Blender Foundation\Blender\blender.exe" C:\blend_projects\249_example\old_file.blend -P C:\blender_projects\start_converter.py -- --project-type AIRCRAFT --workflow-type BULK

To break down what this means: Launch blender.exe and open "old_file.blend". Next, run the -Python script start_converter.py before Blender is finished loading the GUI. After the -- are instructions to the converter that this file represents an AIRCRAFT project and that I previously used BULK export instead of REGULAR (aka "Export > X-Plane v8/v9 Object (.obj)"). Since the name "Program Files" has a space in it, quotes must surround around that file path.

You should see Blender start to open and a lot of text in the terminal should scroll by. This text will be visible in internal text files called "Conversion Log, " + the scene name. This will probably take 2 to 10 minutes, but not longer. If it does, please e-mail me.

Interpret The Results

After the converter is finished, you will see Blender 2.79's GUI fully appear. At this point, save a copy with a different name. Do not accidentally overwrite your 2.49 file!
Now, read through the conversion logs and try exporting! You are likely to run into some errors as modern XPlane2Blender applies more validations than 2.49 did and the converter does not autocorrect your work. Keep notes and remember that fixing the root of the problem in 2.49 and reconverting will fix it everywhere at once. The conversion process will likely involve multiple passes.

If you haven't used modern XPlane2Blender before, watch this tutorial for an example of its use.

Key Differences in XPlane2Blender v3.6.0-alpha.1

• Game Properties are not used, everything done with Game Properties is now in a Properties Tab.
• Every mesh must have a Material, only the first material slot is used. Per face properties are not used. Some meshes may be split to accommodate this (see "Troubleshooting: Why was a mesh split into multiple pieces")
• With modern XPlane2Blender, you do not say what OBJ directive you want written to the file, you say what you want to happen and it figures it out for you.
• XPlane2Blender v3.6.0-alpha.1 has more validations and is much closer to the OBJ specification. This may be a big source of post conversion errors.

Where is...?

What It Was	Where It Was	Where It Is Now
Buttons	Buttons Editor	Properties Editor
Running The Exporter	Scripts > Export > X-Plane...	Export OBJs Button in Scene Properties or File > Export > X-Plane Object (.obj)
Root Of OBJ	Empty starting with "OBJ" or scene's content (REG)	Same Place! REGULAR projects automatically put their contents under a new root object whose name starts with "249_ROOT_"
OBJ Name and Export Path	'rname', 'path', Scene Name, "OBJName"	Object Properties > X-Plane > Root Object Box > Name (which supports relative paths)
Blender Keyframes	Action Editor	Dope Sheet Editor
X-Plane Dataref Information	Bone Name, Game Properties On Armature	Armature's Object's Bone Properties > X-Plane > Datarefs
Manipulator Information	Game Properties	Object Properties > X-Plane of object that had manipulator_type Game Property
LOD information	"LOD_" Game Properties, Use layers 1-4 to set bins	LOD set in Root Object Box, layers 1-4 still used
Light Name, Parameters	Game Properties	Light Properties > X-Plane
Draw State Changes	TexFace properties, "ATTR_"/"GLOBAL_" Game Properties	Object's 1st Material Slot's Material Properties > X-Plane
GLOBAL_ properties	Game Properties	GLOBALS automatically chosen by exporter when some material properties match across all Materials used in an OBJ and other requirements are met
TEXTURE directives	UV/Image Editor	Root Object Box > Manual Texture Paths
Enable Debug Info	Change source code	Scene Properties > X-Plane > Advanced Settings, enabled by default
Game Properties	Buttons > Logic	Logic Editor

Troubleshooting - General Bugs

Haunted objects

I have noticed that some objects are "haunted", that clicking, hovering over them, or having them selected crashes 2.49 or 2.79. Sometimes the problems would correct itself simply by restarting several times and getting lucky. If you see a pattern, please tell me! Otherwise, you may try renaming, cutting and pasting a new copy, or just avoiding them as a work around.

Unicode Problems

I have also noticed a VERY repeatable bug where non-English Unicode characters anywhere except in Text Editor blocks crash Blender when accessed or changed with Python. For example, I named a bone BÒNÈ then tried to convert. It crashed and I couldn't print the name, because the bone's name is the problem itself. If you see "Exception: UnicodeDecodeError", e-mail me before trying to spend too much time on this

"How can I help the alpha?"

Please e-mail me (ted at x-plane dot com) or file a bug on Github your experiences of what happened, especially of crashes and any data that wasn't converted correctly. I am also very interested in changes in draw order. If you got stuck somewhere or didn't know how to get the most out of the process, please also let me know! This type of project is reliant on real world examples, so please let me know what you think!

"Why doesn't XPlane2Blender for 2.79 export every valid 2.49 and why doesn't it produce the same content?"

XPlane2Blender for 2.49 was very sloppy and was not faithful to the OBJ8 spec. By having stronger validations, modern XPlane2Blender makes your files better and in some cases faster. You may be able to reduce the 2.79 export errors by fixing the file in 2.49 faster. Based 2.49 and 2.79 different implementations of the OBJ8 spec, the contents will be different, but will look and act the same (or, at least, that is the goal that we're already pretty good at.)

What to focus on in step 8:

XPlan2Blender for 2.49's system for allowing a parent's game properties to affect their children has wide reaching implications for conversion. If you must prioritize time spent on step 8, GLOBAL_ properties, and draw state directives are among the most time consuming to redo.

Troubleshooting - Animation Conversion

"Blender animations are missing!"

Did you run the X-Plane Prepare Dropped Actions Text File script before conversion? The text file it makes contains a list of Actions and Objects to re-pair together since a bug in Blender 2.79 drops the link.

If you were unable to, here's what that script counters: Suppose you have a .blend file with 3 Armatures [Arm1, Armr2, and Arm3] which all share the same Action Action.007. During load, Blender 2.79 will unlink Action.003 from Arm2 and Arm3. X-Plane Prepare Dropped Actions Text File finds these cases in 2.49 and the converter re-links them together and makes up for Blender 2.79's problem.

A prominent example of this is pairs of objects like yokes and wings. If the problem persists, e-mail me

What happened with DataRefs.txt?

The 2.49 exporter believes in saving only the bare minimum needed for export. That means that a lot of shortcuts were taken that makes 2.49 .blend files less future proof.

In 2.49, the exporter uses the bone name to look up what full dataref to use. As new DataRefs in the DataRefs.txt file were added (or rarely, removed), bone names which used to be known and unambiguous became problematic. Once yoke_roll_ratio only referred to sim/joystick/yoke_roll_ratio. Later when sim/cockpit2/controls/yoke_roll_ratio was added the 2.49 exporter (and by extension the new converter) doesn't know which one to choose. And so, artists are expected to manually fix this. Otherwise the exporter will throw an error on export and the converter will ignore the bone and its keyframe values on conversion.

This "Data Rot" or erosion can be dramatic on using an old project for the first time in a while and using a more recent DataRefs.txt file with.

To help mitigate this you have some options

• If you have 2.49, solve the ambiguity with a game property.

  1. Find your problem bone, for example yoke_roll_ratio. This is the "tail name"
  2. Look up the rest of the dataref in the DataRefs.txt file - the "head" - that you used. We know it was sim/joystick and not sim/cockpit2/controls/yoke_roll_ratio
  3. Select the Armature object of the bone, add a String game property to it: (yoke_roll_ratio:sim/joystick). The "tail" is the key name, the "head" is the value
  4. The last [number] in a bone name is not part of the tail, do not include it. Bone "N1_percent[0]" is disambiguated by (N1_percent:sim/cockpit2/engine/indicators)
  5. Shortened names like sf2e_prpndscrttnngldg[0] should not need disambiguating
  6. Remember, even if it can export and convert, your animation will not work in X-Plane if the dataref was removed or the plugin that defines it is broken/missing

  The rules for making disambiguating properties have a lot of stupid edge cases. If you can't figure it out by hand, try using the Object > X-Plane Animation script on a test armature to see what it produces and copy that.

Other options include:

• Make a copy of the DataRefs.txt file and delete every dataref that is causing ambiguities that you know is not being used by another bone. Use this in the "resources" (and "scripts" if you're able to follow step 8) folder.
• If you have the DataRefs.txt file from when the project was active, copy it into the "resources" (and "scripts" if possible) folder. The exporter and converter will hopefully no longer have ambiguities.
• Redo your work in 2.79, which has a nicer interface and is more reliable. As mentioned, the Blender Animations will be preserved.

If you added plugin datarefs to your DataRefs.txt, don't lose track of them as you copy and experiment with making your custom DataRefs.txt.

Make sure to replace your custom copy of DataRefs.txt in "resources" after you're done converting and are ready to begin working again.

Troubleshooting - Material Conversion

Why was a mesh split into multiple pieces?

In 2.49, one mesh could have multiple different TexFace buttons used - multiple drawing states in the same mesh. Modern XPlane2Blender requires each mesh to represent one drawing state with one material. The converter will split a mesh into small enough chunks so that each each chunk represents a uniform set of drawing states.

Technical Explanation For Those Who Are Very Very Curious, But It Will Probably Be More Confusing Than It Is Worth To Read

For example [SHADOW + TILES, TEX] gets split into [SHADOW + TILES], [TEX]. If ATTR_draped was used, it will not affect the TEX object becaues ATTR_draped + TEX is meaningless. The first object's material will have Draped = True and Cast Shadows (Local) = False. The second object will have the default material because TEX by itself doesn't export an ATTR_ directive in 2.49. Thus, the object should export as it did in 2.49, and modern XPlane2Blender is satisfied. Also, we didn't delete the original mesh without replacements, so the project is "unchanged".

If something has been split when it shouldn't, check that the source didn't accidentally have one face that was different than the others (in a way that mattered) or e-mail me.

What Do The Material Names Mean?

The material names beginning with "249" are converted or created during the conversion process. Each describes the what the converter chose to change in the Material Properties. Only the minimal amount of materials needed are created during conversion.

Legend

Found Game Prop/TexFace Button	Abbreviation Chosen
"BLEND_GLASS"	"bg"
"GLOBAL_cockpit_lit"	"ck"
"NORMAL_METALNESS"	"nm"
"GLOBAL_no_blend"	"nb"
"GLOBAL_shadow_blend"	"sb"
"GLOBAL_specular"	"sp"
"GLOBAL_tint"	"tn"
Colllision	"COLL"
"ATTR_solid_camera"	"SOLID_CAM"
Invisible	"INVIS"
ATTR_draw_disable	"DRAW_DISABLE"
Light	"LIGHT"
"LIT_LEVEL" or "ATTR_light_level"	"LIT_LEVEL"
Shadow	"SHADOW"
Tex + Alpha + "ATTR/GLOBAL_shadow_blend"	"TEX_ALPHA"
Tex + Clip + "ATTR/GLOBAL_no_blend"	"TEX_CLIP"
Tiles + "ATTR_draped"	"TILES"
Found UV Texture with "panel." in name	"pn"