Scenery & Cockpit import/export scripts for Blender 2.49

Overview

Blender is an open source 3D object editor for Windows, Mac and UNIX.

These Blender scripts export models created in Blender 2.49 to X-Plane v8, v9, v10 or CSL .obj format.

The scripts also import existing X-Plane v6, v7, v8, v9, v10 and CSL .obj files and X-Plane v7, v8, v9 and v10 .acf airplanes.

Requirements

Runs on Windows 2000 or later, Mac OS 10.4 or later, and Linux.

Requires Blender 2.49:

Windows: Download and run this Blender installer. When presented with options, use the default choices.
Some scripts also require you to install Python 2.6.

Mac OS
10.5 - 10.8:
Download and open this Blender archive.
Copy the Blender application out of the archive e.g. to your /Applications folder.

Mac OS
10.4 (Intel):
Download and open this Blender archive.
Copy the Blender application out of the archive e.g. to your /Applications folder.

Linux: If Blender 2.49 is offered in your distro's package manager then download and install it from there.
Otherwise download for x86 or x86_64 and unpack it to e.g. your desktop.
You will also need to obtain a copy of Python 2.6 for your distro.

Tutorials

This document is a reference and assumes basic familiarity with Blender. You may find it easier to get started using the following tutorials, and come back to this document later:

Installation

Run Blender to check that it is installed correctly. If the Blender window appears “blurry” turn off anti-aliasing in your video card's OpenGL settings and re-start Blender.

Now close Blender.

Windows:
Extract the contents of this zip file to a new (temporary) folder.
Double-click on the file install.cmd to install the scripts.
(Unless when installing Blender you chose to place your data files in a system-owned location, in which case right-click on install.cmd and choose Run as administrator instead).

Mac OS: Double-click on the file install.command to install the scripts in all compatibile copies of the Blender application that the Finder knows about.
You may be prompted for your password if you installed Blender into a system-owned location such as /Applications.

Linux: If you obtained your copy of Blender from your distro's package manager, then extract the contents of this zip file to ~/.blender/scripts .
If you downloaded Blender from the links above, then extract the contents of this zip file to the (hidden) folder .blender/scripts within the folder where you unpacked the archive.

(Re)start Blender. Check that this file can be viewed by choosing Help → X-Plane in Blender.

Importing

First, move the 3D Cursor to where you want the imported object to be placed. Usually you'll want the object to be placed at the origin so just press Shift C to centre the 3D Cursor at the origin.

Importing X-Plane objects

Choose File → Import → X-Plane Object, select a .obj file and press Import OBJ.

You can import multiple .obj files and re-export them as a single file. But note that the X-Plane .obj file format only supports the use of one texture file, so you'll have to create a single larger file containing all required textures - see below. Or you can have Blender create this single file automatically by selecting all the objects and, in a UV/Image Editor window, choosing Image → Consolidate into one image.

Importing FS9 & FSX models

Choose File → Import → FS9/FSX Model, select a .mdl file and press Import MDL.

MSFS models usually use multiple textures, but the X-Plane .obj file format only supports the use of one texture file, so you'll have to create a single larger file containing all required textures - see below. Or you can have Blender create this single file automatically by selecting all the objects and, in a UV/Image Editor window, choosing Image → Consolidate into one image.

Importing X-Plane planes

Choose File → Import → X-Plane Plane or Weapon and choose whether to import the plane or weapon so that the “reference point” is located at the 3D Cursor (for making cockpit & misc objects) or so that the “centre of gravity” is located at the 3D Cursor (for making CSLs and static scenery).

Then select a .acf or .wpn file and press Import ACF or WPN.

The script creates up to three versions of the plane or weapon in Blender, one in each of layers 1, 2 and 3. The versions in layers 2 and 3 use approximately 1/10th and 1/100th of the number of faces compared to the version in layer 1. See Level of Detail below for an explanation of why it does this.

Imported planes need some tweaking before you can export them as scenery or as a CSL object; see Tweaking Planes.

Exporting

First, choose File → Save As… and save the .blend file in the aircraft or scenery folder where you want the exported object(s) to end up.

Exporting objects

Choose File → Export → X-Plane Object

The object is exported in the same folder and with the same name as the current Blender file, but with a .obj extension. Blender may display some informational messages - click on one of these messages to see which object(s) the message refers to.

If there is an error then the scripts will attempt to identify and highlight the offending Blender object(s).

Exporting facades

TBD

Exporting autogen blocks

TBD

Creating X-Plane objects

X-Plane objects are made using the techniques described below whether the object is intended as a scenery object, an aircraft “Misc” object, an aircraft cockpit object, or a “CSL” object for use with multi-user plugins such as XSquawkBox or X-IvAp. Only Lamps and Meshes are exported to X-Plane. You can use other Blender object types, e.g. Curves and Surfaces, to construct your scenery as long as you convert them to meshes before exporting to X-Plane.

Cockpit objects support additional functionality described here, and CSL objects have some limitations described here.

Textures

X-Plane objects support only one primary texture; in an image editor application create one texture file that is like a “collage” of all of the textures that you need in your model. The height and width of the texture file must be powers of two e.g. 128, 256, 512, 1024, 2048 (X-Plane v9 only) or 4096 (X-Plane v10 only) but it doesn't have to be square. If you later find that you run out of space in your texture file you can use this technique to increase the size.

Export the texture file to 32bit or 24bit PNG format (i.e. with or without an “Alpha” channel) or DXT1, DXT3 or DXT5 DDS format in the aircraft or scenery folder where you want the X-Plane .obj file to end up.

X-Plane objects support a number of secondary textures. These use the same UV mappings as the primary texture:

An emissive map texture to control night-time brightness.
Save your emissive texture in the same folder as your primary texture file, and with the same name but with _LIT appended; e.g. primarytexture_LIT.png or primarytexture_LIT.dds.
A normal map texture to control “bumpiness” and shinyness.
Save your normal map texture in the format described here and here in the same folder as your primary texture file, and with the same name but with _NML appended; e.g. primarytexture_NML.png.
The cockpit panel texture (aircraft cockpit objects only).
Described here.

Lamps

Only Lamp objects of type “Lamp” and “Spot” are exported to X-Plane. Lamp objects of types “Area”, “Semi” and “Hemi” are ignored (and so can be used to illuminate your model in Blender). Lamp objects with certain words in their names have special behaviours when exported to an X-Plane object:

Lamp - Normal (legacy) light. The colour is determined by the R,G,B sliders on the Lamp panel F5.
Flash - Flashing (legacy) light. The colour is determined by the R,G,B sliders on the Lamp panel F5.
Traffic - Traffic (legacy) light; cycles red, orange, green. (R,G,B settings are ignored).
smoke_black or smoke_white - Not really a light; emits smoke. The size of the smoke puffs is determined by the Energy slider on the Lamp panel F5 (R,G,B settings are ignored).
other - X-Plane pre-defined “named” or “parameterized” light:

Custom lights are created using the vertices from a rectangular “Plane” Mesh object:

Spill lights (X-Plane v10 only) are created using Lamp objects of type “Spot”:

Meshes

Create meshes consisting of triangular and/or rectangular faces:

Use this script if you need to reset all faces in the scene to standard settings (i.e. no polygon offsetting, not hard, single sided, not transparent).

You can add “modifiers” in the Modifiers Editing panel F9 to change the way that the Mesh appers. Some useful modifiers when modelling for X-Plane are:

Animation

You can make lamps, meshes and lines animate in X-Plane according to the value of any of the simulator datarefs listed here that have type “int”, “float” or “double”.

Basic animation

Create an “Armature” object. Make the lamps and/or meshes that you want to animate the children of the armature's “bone”:

Once you have assigned a parent bone to your lamps/meshes, you can specify the simulator dataref that will drive the animation:

Use frames to represent the desired position of the lamps/meshes at various dataref values - X-Plane will interpolate linearly between the positions:

(Note: X-Plane's animation syntax is quite simple; so don't use IPOcurves, Vertex Groups, Deformations, Shape Keys or any other advanced Blender animation techniques since these will be ignored by the exporter - only the positions specified by keys in the first n frames are significant to X-Plane.)

X-Plane v8 only supports two frames, so if you want your .obj file to work in X-Plane v8 then you should insert “LocRot” keys only in frames 1 and 2.

X-Plane v9 and later supports multiple key frames. Also, X-Plane will extrapolate your animation when the dataref has a value outside of the range that you specified in the Frame #n fields. You can stop the extrapolation and “clamp” your animation's position by repeating the poses and Frame #n values in the first two and/or the last two frames. Or you can cause your animation to loop back to frame 1 when the dataref value exceeds a certain number by specifying this number in the Loop field.

The X-Plane Animation dialog renames the parent bone to the “leaf” name of the dataref. So pressing the Draw Names button in the Armature panel can be helpful to see what's going on when you have lots of animations.

Use the Action Editor window to get an overview of which bones in the selected armature have keys inserted into which frames.

Controlling animation response to dataref values

By default, X-Plane will display the meshes in the frame 1 position when the dataref has a value of 0, and in the last frame position when the dataref has a value of 1. You can change these values:

Using multiple datarefs

You can animate your lamps/meshes using multiple bones, each bone representing a different dataref:

The X-Plane Animation dialog displays the settings for the lamp/mesh's parent bone, gandparent bone etc. (Note: Don't change the parent/child relationships between your lamps/meshes and their parent bones while the X-Plane Animation dialog is being displayed).

Hiding lamps and meshes

You can make all of the lamps and meshes in an animation disappear when a dataref is within a certain range:

You can make hidden lamps/meshes re-appear when a dataref value is within a certain range by adding another entry, and changing the type from Hide to Show. The dataref that you use to “show” the animation can be the same or different than the datarefs that you used to “hide” the animation. (The animation is always shown by default, so you only need to use a Show entry if you have used one or more Hide entries and you want to override them).

The order of Hide and Show entries is significant; the animation will be hidden if any of the Hide dataref values are in range, unless a subsequent Show dataref value is also in range. You can use the Up and Down arrow buttons to change the order of the entries.

Note that the Hide and Show entries apply to all children of all bones in the armature. You can make an armature the child of a bone in a different armature; in which case all children are affected by any Hide and Show entries in parent armatures.

Drawing order

The order in which X-Plane draws the animations, lights, lines and triangles in your scenery or cockpit object usually has no effect on the appearance. So the exporter optimises the order of animations, lights, lines and triangles in your object to minimise the number of OpenGL state changes and therefore maximise X-Plane's framerate.

However drawing order does become important if you use transparent and/or translucent textures on some of your faces - transparent and translucent faces must be drawn last, otherwise other faces and lights will not be visible through them. You should therefore tell Blender which faces are transparent/translucent using the Alpha button in the Texture Face Editing panel F9 in UV Face Select mode. The exporter will ensure that X-Plane draws these faces last.

But sometimes you need even more control over the drawing order - e.g. modelling a cockpit with a transparent HUD and (obviously) a transparent canopy; the HUD must be drawn after the canopy.

You can specify the relative order in which lamps, meshes etc should be drawn by assigning them to “Groups” on the Object and links panel F7:

e.g. in the case of the cockpit with transparent canopy and HUD, we could put the canopy and HUD into separate groups named GroupA and GroupB respectively. Since A is before B in the alphabet, the canopy would be drawn before the HUD (and both would be drawn after the rest of the cockpit).

To add objects to a new group:

Objects that belong to a group are highlighted in green instead of pink so that you can easily distinguish them.

Drawing group

You can specify when X-Plane should draw your scenery object relative to other scenery elements:

e.g. to make X-Plane draw your object at the same time that it draws runway markings add a property named group_markings to an Empty object and give it the value 0.

Slung load weight

You can specify the weight of an object for use in X-Plane's physics engine if the object is being carried by a plane or helicopter:

Level Of Detail

X-Plane has borrowed the concept of Level Of Detail from 3D games. This works on the principle that when you're viewing an object from a large distance it can be displayed with reduced detail without you noticing the difference. By displaying distant objects with reduced detail we can simulate a more complex scene than would be possible if all objects were drawn at maximum detail.

Use Layers to create objects (but not aircraft cockpit objects or, prior to X-Plane 10, Misc objects) with multiple Levels Of Detail. Objects in layers 1-3 are visible in X-Plane at the following distances:

Layer Distance
1 < 1000m
2 1000-4000m
3 4000m-10000m

Changing the texture size

If you run out of space in your texture file then you can increase the size. You should use the following procedure to ensure that your UV mappings and/or PlaneMaker instrument layouts are preserved:

You can also use this technique if you want to combine 3D models that use different texture files; paste all of the textures used by the 3D models into a single new texture file, then use Image → Replace and fixup UV mapping… on each of the original textures.

Blender tips

Auto-saving

Blender can automatically archive old copies of your .blend files when you save. This is useful if you later want to revert to an older version. In the User Preferences window, on the Auto Save tab, choose the number of Save Versions. The older versions of your file will be called .blend1, .blend2 etc.

Blender can also periodically save a copy of your work in case Blender or your computer crashes, or in case you quit Blender without saving. On the Auto Save tab press Auto Save Temp Files. Also, on the File Paths tab, ensure that Temp is set to a folder that exists on your machine. This is where the auto-saved files will be created. (The default value of /tmp is fine for Mac and Linux, but /tmp doesn't exist on most Windows machines so you should change this setting).

Properties

“Properties” are used to specify animation parameters, “named” lights and the drawing group. You can see an object's properties by selecting it and pressing F4 to display the Logic panel. Press the Add Property to create a new property.

Each property has three fields; Type, Name and Value. If you want to supply a non-numeric value, e.g. the name of a “named” light, you'll first need to change the Type from Float to String.

Limitations

Import object

Import plane

Problems

Please email any questions, problems etc to the author. If reporting a problem, please:

Acknowledgements

“X-Plane” is a registered trademark of Laminar Research.

Includes code © Ben Supnik 2012-2013, © Ben Russell 2010 and © Mike G 2010.

License

These tools are licensed under the GNU GPL v2.0 license.

Use of these tools does not impose any requirement on you to license your work under the GPL. For the avoidance of doubt, this means that you can license any scenery that you make using these tools under commercial terms (subject to any licensing restrictions on any imported or library objects that you use).

The author would appreciate a courtesy copy of any commercial work that you make using these tools, but you are under no obligation.