Marginal → X-Plane Scenery → Tools → XPlane2Blender |
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.
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. |
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:
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 |
(Re)start Blender. This file can now be viewed by choosing Help → X-Plane in Blender.
You can now delete the temporary folder.
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.
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.
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:
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.
Custom Scenery
folder
inside of your X-Plane
installation.X-Plane/Custom Scenery/EGLL/house.blend
.obj
file will be exported to the same place, ie:
X-Plane/Custom Scenery/EGLL/house.obj
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:
airplane_paint
and airplane_paint2
to 512x512. (You don't need to
save these resized versions).airplane_paint
into the left half of this bitmap.airplane_paint2
into the right half of this bitmap..blend
file. If you're making a CSL object then you must save in PNG format._LIT
bitmap files.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:
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):
airplane_cockpit.obj
in both internal and external views.airplane_cockpit_INN.obj
only in internal views.airplane_cockpit_OUT.obj
only in external views.airplane_cockpit_INN.obj
and/or airplane_cockpit_OUT.obj
then you should not create airplane_cockpit.obj
.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.
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:
ScreenshotPanel.png
(or any
filename ending in *panel.*
) in the same folder as your
plane's .acf
file.ScreenshotPanel.png
texture on those faces
that you want to display moving cockpit instruments in X-Plane.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.
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.
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).
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.
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.
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.
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
, smoke_black
, smoke_white
-
As for X-Plane v7 objects; see below. (R,G,B settings are ignored).name
if this exists, otherwise from the name of the lamp object.Flash
- Flashing light. The colour is determined by the R,G,B sliders on the Lamp panel (F5).airplane_beacon
- Red pulsing anti-collision light. (R,G,B settings are ignored).airplane_strobe
- White strobe light. (R,G,B settings are ignored).Traffic
- 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).airplane_landing
- White landing light. (R,G,B settings are ignored).airplane_taxi
- White taxi light. (R,G,B settings are ignored).airplane_nav_left
- Red navigation/position light. (R,G,B settings are ignored).airplane_nav_right
- Green navigation/position light. (R,G,B settings are ignored).airplane_beacon
- Red pulsing anti-collision light, on when engines are running. (R,G,B settings are ignored).airplane_strobe
- White strobe light. (R,G,B settings are ignored).R
, G
, B
and/or A
to
set these values.Image
.
You should use just one texture.
name
.
tri
"s
and "quad
"s in X-Plane).…/Custom Scenery/KSBD Demo Area/KSBD_example.png
for an example)..obj
file to end up.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.
For best results with X-Plane versions prior to 8.50 you should ensure that
objects that use polygon offsetting are listed first in your .env
or .dsf
scenery file.deck
and give it the
value True
.
You can't fly under hard faces in X-Plane v8.surface
and give it the value water
, concrete
, asphalt
, grass
, dirt
, gravel
, lakebed
, snow
, shoulder
or blastpad
.
The surface type is ignored by X-Plane versions prior to 8.50.quads
") are exported as "hard"..obj
files that contain hard faces must be placed in WorldMaker with an
"object heading" of 0. Otherwise the "hard" part of the surface ends
up in the wrong place.1
, 1
, 1
(white). However the default setting of a new material in Blender is
0.8
, 0.8
, 0.8
.1
, 1
, 1
- control the diffuse colour of the faces by editing the texture file instead._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, eg on overcast days,
which _LIT
textures do not.
The default X-Plane and Blender setting is 0 (not emissive).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:
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.
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".
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:
sim/flightmodel/engine/ENGN_thro
represents the engine throttle settings, so you need to specify which engine
you're referring to. Specify a "Part number" of 0
for the first
engine, 1
for the second engine etcUse 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.
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:
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 fieldv9: 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.
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).
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.
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.
You can specify when X-Plane should draw your scenery object relative to other scenery elements:
group_terrain
, group_beaches
, group_shoulders
, group_taxiways
, group_runways
, group_markings
, group_airports
, group_roads
, group_objects
, group_light_objects
or group_cars
.-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.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
.
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:
slung_load_weight
and specify the weight in pounds.
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:
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.
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 |
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 has a quirky user interface:
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" 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.
smoke_black
and smoke_white
X-Plane primitives are ignored.ambient
, blend
and
specular
attributes are ignored..obj
file formats).
You can use
Image → Consolidate into one image
to merge multiple texture files into one file.Please email any questions, problems etc to the author. If reporting a problem, please:
.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).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.
Version 3.09 © 2004-2008
Jonathan Harris
![]() |