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:

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:

• Using Blender to create X-Plane scenery
• The Blender Manual

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.

(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 ¹/₁₀^th and ¹/₁₀₀^th 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:

• The name of the X-Plane light is taken from the value of a property named name if this exists, otherwise from the name of the lamp object.
• Additional parameters are taken from the value of a property named params.
• R,G,B settings are ignored.

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

• In the Material buttons panels F5:
  • On the Links and Pipeline panel press Add New to create a new material, or choose an existing material (if any) from the drop-down list.
    Press the Halo button on this panel.
  • On the Material panel the Halo button and the R,G,B,A sliders control the light's R,G,B and A values.
    Alternatively you can create properties named R, G, B and/or A to set these values.
  • On the Shaders panel the HaloSize slider controls the light's S value.
    Press the HaloTex button in this panel to make Blender render the light correctly.
• In the Texture buttons panels F6:
  • On the Texture panel press Add New to create a new texture for the mesh, or choose an existing texture (if any) from the drop-down list. You should use just one texture.
    Change the Texture Type to Image.
  • On the Image panel load the texture file that contains the light that you want to use.
  • On the Map Image panel press the UseAlpha button.
    Use the MinX, MinX, MaxX, MaxY settings to select a subset of the texture.
• To drive the custom light using a dataref add a String property named name.

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

• In the Lamp buttons panels F5:
  • On the Preview panel press the Spot button.
  • On the Lamp panel the Energy,R,G,B sliders control the light's intensity and R,G,B values, and the Dist slider controls the light cone's length.
  • On the Shadow and Spot panel the SpotSi slider controls the light cone's width.
• Rotate the Lamp object to change the light cone's direction.
• To drive the spill light using a dataref add a String property named dataref.

Meshes

Create meshes consisting of triangular and/or rectangular faces:

• In the Mesh Editing panel F9:
  • Press the New UV Texture button once (X-Plane objects support only one primary texture).
  • Use the UV/Image Editor window to open this texture and control mapping of the texture to the mesh faces.
• In the Texture Face Editing panel F9 available in Edit Mode:
  • Tex button controls whether the face has a texture.
  • Tiles button controls whether the face is rendered with “polygon offsetting” (ATTR_poly_os) in X-Plane. Press this button for faces that lie flat on the ground to prevent Z-buffer thrashing in X-Plane. Don't press this button for other faces.
  • Collision button indicates that the face is not “hard” (ie not “landable on”) in X-Plane. Making faces hard is very expensive, so this button should normally be pressed. Unpress this button only for things like helicopter landing pads.
    You can control whether it is possible to fly under this hard face in X-Plane v9 and later; add a Bool property named deck and give it the value True.
    You can specify the surface type; add a String property named surface and give it the value water, concrete, asphalt, grass, dirt, gravel, lakebed, snow, shoulder or blastpad.
  • Twoside button controls whether one or both sides of the face are displayed. Unless you have a lot of double-sided faces it is cheaper to avoid this button and to use two single-sided faces back-to-back instead.
  • Alpha button is a hint to Blender and to X-Plane that the face is transparent or translucent. Use this for outwards-facing transparent or translucent faces to instruct X-Plane to draw these faces last so that you can see other faces through them. Don't press this button for opaque (normal) faces.
    See drawing order for more fine-grained control over drawing order.
• In the Link and Materials Editing panel F9 available in Edit Mode:
  • Set Smooth and Set Solid control whether to smooth edges of faces in a mesh. The effect is only visible in Blender 3D View windows when the Viewport Shading button is set to Solid or Shaded, but the effect is always visible in X-Plane.
    In Object Mode these buttons affect the entire mesh. In Edit Mode these buttons affect the selected face(s).
    You can add an EdgeSplit modifier in the Modifiers Editing panel F9 to get Blender to automatically sharpen edges on a smoothed mesh based on the angle between faces.
• In the Material buttons panels F5 you can change the way that the mesh reacts to light by specifying a material. Changing between materials in X-Plane is expensive so you should ensure that you use at most a few materials in your model.
  Press Add New to create a new material, or choose an existing material (if any) from the drop-down list.
  Only a few of Blender's many material buttons affect X-Plane:
  • On the Material panel the Col button and the R,G,B sliders control the diffuse colour of the faces. X-Plane combines the colours that are specified by the texture (if any) with this setting.
    The default X-Plane setting is 1, 1, 1 (white). However the default setting of a new material in Blender is 0.8, 0.8, 0.8.
    You should normally set this to 1, 1, 1 and control the diffuse colour of the faces by editing the texture file instead.
  • On the Shaders panel the Spec slider controls the specularity (shininess) of the faces.
    The default X-Plane setting is 0 (matt). However the default setting of a new material in Blender is 0.5.
  • On the Shaders panel the Emit slider controls the emissive brightness of the faces. Emissive faces give off light so the effects of this setting are most obvious at night. It is usually cheaper and easy to use _LIT textures to control night-time brightness instead of using this setting. However using this setting allows you to create faces that also give off light during the daytime, e.g. on overcast days, which _LIT textures do not.
    The default X-Plane and Blender setting is 0 (not emissive).
    On the Material panel Mir button and the R,G,B sliders control the emissive colour of the 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:

• EdgeSplit - automatically sharpen edges between mesh faces (this only has an effect if you've used the Set Smooth button).
• Subsurf - produce a more detailed version of the mesh by subdividing faces.
• Curve - bend the mesh along a curved path.

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”:

• Click on the lamps and/or meshes (the “children”)
• Shift-click on the armature
• Choose Pose Mode from the Mode menu in the 3D View window's toolbar
• Click on the bone (the “parent”)
• Press Ctrl P and select Bone from the popup menu

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

• Choose Object Mode from the Mode menu in the 3D View window's toolbar
• Select the child lamp or mesh
• From the 3D View window's menubar choose Object → Scripts → X-Plane Animation
• In the Parent Bone panel, use the pop-up menu to select the dataref
  (or you can type in just the “leaf” name of the dataref into the text field, or the full name of a custom dataref)
• Some datarefs require you to specify a “Part number”;
  e.g. the dataref sim/flightmodel/engine/ENGN_thro represents the engine throttle settings, so you need to specify which engine you're referring to. Press the Part number button and specify 0 for the first engine, 1 for the second engine etc.
• Press the Apply button

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

• In the Animation Frame field, in the Buttons window's menubar, select frame 1
• Click on the armature
• Choose Pose Mode from the Mode menu in the 3D View window's toolbar
• Click on a bone
• Move and/or rotate the bone
• Press  i  and specify a LocRot key (i.e. location and rotation)
• Repeat for any other bones in the armature
• Select animation frame 2 and repeat

(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:

• Choose Object Mode from the Mode menu in the 3D View window's toolbar
• Select the child lamp or mesh
• From the 3D View window's menubar choose Object → Scripts → X-Plane Animation
• Specify in the Frame #n fields the dataref values that correspend to each frame;
  e.g. the yoke pitch dataref yolk_pitch_ratio takes values between -1 (forward) and +1 (back) in X-Plane. So, to make X-Plane display the position in frame 1 when the yoke is pushed fully forward specify -1 in the Frame #1 field
• Press the Apply button

Using multiple datarefs

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

• In Edit Mode add additional bones to the armature.
• Still in Edit Mode, in the Armature Bones panel, create parent/child relationships between each bone. (Note: This panel also lets you rename bones. Don't do this - use the X-Plane Animation dialog to name the bones after the datarefs that they represent).
• Use the technique described above to make your lamps/meshes the children of the “youngest” bone in the chain.
• Insert LocRot keys for every bone in the chain (each bone can have a different number of keys).

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:

• Use the technique described above to make your lamps/meshes the children of an armature bone
  (If you don't want to animate your lamps/meshes then don't insert any animation keys for this bone, and the bone doesn't have to be a valid dataref)
• Choose Object Mode from the Mode menu in the 3D View window's toolbar
• Select a lamp or mesh that you want to hide
• From the 3D View window's menubar choose Object → Scripts → X-Plane Animation
• In the last panel, press the Add New button
• Specify the dataref and the range of values (it's OK to use datarefs that are not otherwise used in the animation)

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:

• Objects that don't belong to a group are drawn first.
• The groups are sorted by alphabetical order, and then
  • objects that belong to the first group are drawn next.
    …
  • objects that belong to the last group are drawn last.

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:

• Select the meshes that you want to be drawn late.
• Press the Add to Group button on the Object and links panel F7 (or press Ctrl G).
• Choose ADD NEW.
• Give the new group a name.

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:

• Add a Blender object of type “Empty” to your scene.
• Add a property to the Empty object named group_terrain, group_beaches, group_shoulders, group_taxiways, group_runways, group_markings, group_airports, group_roads, group_objects, group_light_objects or group_cars.
• Give the property a value between -1 and -5 to make X-Plane draw your object before this group, 0 to draw your object with this group, or between 1 and 5 to draw your object after this group.

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:

• Add a Blender object of type “Empty” to your scene.
• Add a property to the Empty object named slung_load_weight and specify the weight in pounds.

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:

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:

• Create a new, larger, texture in an image editor application.
• Panel texture: Paste the original texture into the lower left corner of the new texture.
• Non-panel texture: Paste the original texture into one of the corners of the new texture, or aligned on a multiple of the original texture's width and height.
• In Blender, in the UV/Image Editor window, select the original texture from the pop-up menu.
• Choose Image → Replace and fixup UV mapping…
• Select the new image and press Replace image.
• In the Fixup UV mapping dialog, press the button in the cluster of buttons that represents where you placed the original texture in the new texture.

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

• smoke_black and smoke_white X-Plane primitives are ignored.
• ambient, blend and specular attributes are ignored.
• The importer usually can't work out which faces are partially or wholly transparent. You should tell Blender which faces are transparent using the Alpha button in UV Face Select mode after import.

Import plane

• Wings are simplified to reduce polygon count. Any wing curvature (ie the customize chords option in PlaneMaker) is ignored.
• Adjacent wing segments may not be exactly joined-up. If not corrected manually this can create shadow effects in XSquawkBox and X-IvAp.
• Cockpit objects are ignored. You can use File → Import → X-Plane Object to import cockpits.
• Planes (and their weapons, misc objects and cockpit objects) use multiple texture files. These are not automagically merged into one file during the import.
• The importer can't work out which faces are partially or wholly transparent. You should tell Blender which faces are transparent by pressing the Alpha button in UV Face Select mode after import.
• LOD algorithm can be insufficiently aggressive in layer 2.

Problems

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

• First, check that you are using the latest version of the scripts.
• Try to send me the the .obj, .acf or .blend file (where relevant) and the contents of the Console window. (In Mac OS X, this is the "Console" program. In Windows this the window titled "Blender" that looks like a Command Prompt).

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.

Version 3.11 © 2004-2013 Jonathan Harris