Scenery & Cockpit import/export scripts for Blender

Overview

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

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

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

Requirements

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

Requires Blender 2.45 or later:

Windows: Download and run the "Installer" build of Blender.

Mac OS
10.5:
Download the "Python 2.5" build of Blender for Intel or PPC.
To install, copy the Blender application out of the disk image eg to your /Applications folder.

Mac OS
10.3 & 10.4:
Download the default "Python 2.3" build of Blender for Intel or PPC, unless you have installed Python 2.5.
To install, copy the Blender application out of the disk image eg to your /Applications folder.

Linux: Most distros come with Blender, so you can install it via your package manager (eg Synaptic, YaST, YUM).
Or download the build that corresponds to the version of Python that is installed on your system.

Tutorials

This document is a reference and assumes 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
Vista:
Extract the contents of the zip file to a new (temporary) folder.
Right-click on the file install.cmd and choose Run as administrator.
(This installs the scripts in the folder %HOME%\blender\scripts if it exists, otherwise in the copy of Blender that is associated with .blend files).

Windows
2000/XP:
Extract the contents of the zip file to a new (temporary) folder.
Double-click on the file install.cmd.
(This installs the scripts in the folder %HOME%\blender\scripts if it exists, otherwise in the copy of Blender that is associated with .blend files).

Mac OS: Double-click on the file install.command.
(This installs the scripts in the folder ~/.blender/scripts if it exists, otherwise in all copies of Blender that the Finder knows about).

Linux: Start a shell window, and type:
mkdir -p ~/.blender/scripts
Extract the contents of the zip file to this folder.

(Re)start Blender. This file can now be viewed by choosing Help → X-Plane in Blender.

You can now delete the temporary folder.

Importing objects

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.

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

The scenery is imported at the 3D Cursor position.

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 planes

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

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 below.

Exporting objects

First, choose File → Save As… and save the .blend file in the aircraft or scenery folder where you want the .obj file to end up. Then choose:

File → Export → X-Plane CSL Object or
File → Export → X-Plane v7 Object or
File → Export → X-Plane v8/v9 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).

csl: These objects are intended for use with multi-user plugins such as XSquawkBox or X-IvAp.
v8: These objects are supported by X-Plane versions 8.20 and later.
v9: These objects are supported by X-Plane versions 9.00 and later.

Creating X-Plane scenery

Tweaking planes

Imported planes need to be positioned correctly on the ground for use as static scenery (don't do this if you're making a CSL or cockpit object):

The primary file for textures is named airplane_paint. Most planes also use textures from a secondary file named airplane_paint2. Objects that use textures from the secondary file are imported with "*" after their name to make them easier to identify in Blender's Outliner window.

The X-Plane .obj scenery file formats only support the use of a single file for textures, up to 1024x1024 pixels in size. If your plane only has a few simple objects that use textures from airplane_paint2 then you should re-texture these objects to use airplane_paint, following the same procedure described below for weapons and misc objects. If that is not feasible you can use this procedure to make the plane use textures from a single file:

If your imported plane uses weapons or misc objects then each of these will use an additional bitmap file. Weapons are imported with their names starting with "Wnn" and objects with their names starting with "Onn". Also note that reduced-LOD versions of weapons and misc objects may be present in layers 2 and 3.

Open an Outliner window and choose View → Show Outliner. For each mesh that has a name starting with "Wnn" or "Onn" or ending with "*", either:

Consider performance issues when the plane is rendered in X-Plane. Ask yourself the following questions:

Creating 3D cockpits

X-Plane 3D cockpits are just normal v7, v8 or v9 scenery objects except that cockpits can't contain multiple Levels of Detail, so only objects in Blender layer 1 are exported. If you want to keep objects in your Blender scene for reference but which you don't want to export - eg the plane fuselage - then put them in layer 4 or greater before exporting.

Choose File → Save As and save the blender file in the same folder as your plane's .acf file with the name airplane_cockpit.blend, airplane_cockpit_INN.blend or airplane_cockpit_OUT.blend (where airplane is the name of your plane's .acf file):

You will usually want to import your plane into Blender to act as a reference and/or starting point for your cockpit. Delete any plane parts that you don't need in creating your cockpit - you only need to keep the fuselage itself plus any relevant Misc Bodies. After import, your cockpit uses the same texture file as your plane, ie airplane_paint. Choose Image → Replace in a UV/Image Editor window to use a different texture file, which can be named anything you like (but no spaces) and which should live in the same folder as your plane's .acf file.

To make your 3D cockpit appear in X-Plane, on the Standard → Viewpoint → View screen in PlaneMaker, check the show cockpit object in: INSIDE views, exact forwards option. To hide the 2D cockpit altogether, also check the show cockpit object in: PANEL views, exact forwards option; hiding the 2D cockpit means that you no longer have to leave a large part of the Panel Texture transparent to represent the windscreen, which gives you more room on the Panel Texture for instruments.

Cockpit instruments

To construct moving cockpit instruments paint the …/cockpit/-PANELS-/Panel.png texture in an image editor application and place instuments in PlaneMaker as as you would for a 2D panel (but bear in mind that only the top 768 lines of the Panel Texture can be used in the 3D cockpit in X-Plane versions prior to 8.20). The Panel Texture can by 1024×any size in X-Plane v8, and any size up to 2048×2048 in X-Plane v9. Normally you can only use a single file to texture your X-Plane objects. But when constructing a 3D cockpit you can additionally use this …/cockpit/-PANELS-/Panel.png file - the instruments that X-Plane draws on the 2D panel will also appear in your 3D model.

The …/cockpit/-PANELS-/Panel.png texture doesn't contain any instruments when you load it into Blender (unless you've painted them on yourself). This makes it hard to tell in Blender where X-Plane will draw the instruments. So it's easier if you use a screenshot of the panel with the instruments drawn on it, instead of the real Panel Texture. If your display is larger than your Panel Texture, then this is simple:

If your Panel Texture is larger than your display then you cannot take a screenshot of the whole panel. In this case you'll need to take multiple screenshots of the panel in PlaneMaker and stich them together in an image editing application.

If you later want to resize your Panel Texture then use the procedure described below.

Note that X-Plane versions prior to 8.20 only display the 3D cockpit when running at the default 1024x768 resolution. You may want to mention this in the Readme with your plane if your plane is intended to work in X-Plane versions prior to 8.20.

v9: Cockpit Panel Regions

The cockpit Panel Texture uses a lot of video memory, much of which is wasted when the 3D cockpit is being displayed:

A "Panel Region" is a new texture which is cut out from your Panel Texture:

When you use Panel Regions instead of the Panel Texture to texture your 3D cockpit, X-Plane discards the Panel Texture's alpha channel and also discards all areas of the Panel Texture other than the pieces that you cut out to make the Panel Regions. This reduces video memory requirements and improves performance.

Creating a Panel Region

Any faces that you've textured using the Panel Texture which are contained inside the new Panel Region are transferred over to use the new Panel Region.

Any areas that are fully transparent in the Panel Texture are coloured sky blue in the new Panel Region. You'll get undefined (ie weird) results in X-Plane if you use these sky blue areas to texture your faces.

(Note: When you create a Panel Region, Blender also creates a hidden object named "PanellRegionHandler" to store accounting information. Don't mess with this object).

Deleting a Panel Region

Any faces that you've textured using this Panel Region are transferred back to using the Panel Texture.

The deleted Panel Region will remain in the UV/Image Editor window's pop-up menu for a while until Blender figures out that it can remove it. But the deleted Panel Region won't count towards your maximum of four Panel Regions.

Re-loading the Panel Regions

The Panel Regions aren't automatically updated when you edit your Panel Texture in an image editor application and then reload it in Blender, or when you reload your .blend file.


Using Blender to create X-Plane objects

Only Lamps and Meshes are exported to X-Plane. You can use other Blender object types, eg Curves and Surfaces, to construct your scenery as long as you convert them to meshes before exporting to X-Plane.

Lamps

Meshes

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

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

Lines

Blender doesn't support Lines directly. Use a mesh with one 4-edged face instead. The pair of vertices at each end of the "line" must be within 0.1 units of each other. The face must be the only face in its mesh and must not have a texture assigned to it.

Assign a material to the face and use the Col button and the R,G,B sliders on the Material panel to control the colour of the line. Faces not linked to a material will be exported coloured grey.

v8/v9: 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.)

v8: 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. If you insert keys in frame 3 and above then your animation will not work at all in X-Plane v8. Use the Delete button in the X-Plane Animation dialog to delete any keys from additional frames.

v9: You can add "LocRot" keys in as many frames as you like. If you skip a frame then Blender and X-Plane will use the pose from the previous frame.

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:

v9: 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.

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 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.

v8/v9: 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 - eg 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):

eg 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.

v8/v9: Drawing group

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

eg 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.

v8/v9: 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:

Optimising for X-Plane

v7: Strips

As well as basic 3- and 4-edged faces ("tri"s and "quad"s), X-Plane v7 objects support two compound types - "tri_fan" and "quad_strip". These are strips of two or more tris and quads that share common edges. Because the faces in these strips share common edges, X-Plane and the underlying OpenGL renderer have a third or a half as much work to do to render them compared to individual tris and quads. This gives higher frame rates.

In order for a pair of faces to be considered for inclusion in one of these strips, the following conditions need to be true:

  1. The faces must be facing the same way.
  2. Each pair of faces must share a common edge (apart from the first and last face).
  3. Each shared edge must have the same texture co-ordinates in both faces.

In practice this means that the texture must be reversed in alternate faces in the strip. In the case of tris this can also be achieved by mapping a single area of the texture across all the tris, with the tip of the tris at the centre of the texture area. Use UVs → Copy & Paste from the UV/Image Editor window to automate the creation of strips.

These compound types aren't supported directly by Blender. However, the export script automatically tries to spot when it can use them.

v8, v9 & csl: The performance gains from using strips are more modest in X-Plane v8 and v9, and for CSL objects. These compound types aren't supported in v8/v9 objects (X-Plane v8 and v9 use more advanced techniques) and the only saving from using strips over some other UV mapping methods is in reduced "vertex count". It probably isn't worth going out of your way to look for opportunities of making strips.

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 draw scenery and CSLs (but not aircraft Cockpits or 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. The panel texture can by 1024×any size in X-Plane v8, and any size up to 2048×2048 in X-Plane v9. The height and width of a non-panel texture file must be a power of two eg 128, 256, 512, 1024 or 2048 (X-Plane v9 only), but it doesn't have to be square.

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

Blender has a quirky user interface:

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, eg the name of a "named" light, you'll first need to change the Type from Float to String.

Limitations

Import object

Import plane

Export object

Problems

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

License

These tools are licensed under the Creative Commons Attribution-Noncommercial-ShareAlike license.

Use of these tools does not impose any requirement on you to license your work under a Creative Commons license. 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 scenery that you make using these tools, but you are under no obligation.