Blender2FSX Toolset manual
Blender2FSX Toolset is an addon for the 3D-modelling application Blender. This Wiki page is intended to introduce the reader to the use of Blender2FSX to export models created in Blender for use in Microsoft Flight Simulator X (FSX) and shows some things to consider when modelling for FSX in Blender. It is NOT a generic tutorial on how to build models in Blender. Blender2FSX is currently in BETA-phase, later support for P3Dv2 is planned. The current support thread is located here.
- 1 Requirements
- 2 Installing Blender2FSX
- 3 The Tools
- 4 FSX Materials
- 5 Exporting to FSX
- Windows XP, Vista or 7, (Windows 8 untested)
- Microsoft Flight Simulator X SDK with SP2 or Acceleration
- and obviously, Blender (current version at time of writing is 2.69).
- Download the latest Blender2FSX in the first post of the development/support thread.
- Under Windows Vista, 7: Place the .zip file here: "C:\Users\%username%\AppData\Roaming\Blender Foundation\Blender\2.69\scripts\addons".
- Under Windows XP: Place the .zip file here: "C:\Documents and Settings\%username%\Application Data\Blender Foundation\Blender\2.69\scripts\addons".
Alternatively, you can unzip the file and place its extracted contents in the aforementioned locations. Note that the Appdata folder in Win7 is hidden. To activate the Toolset in Blender,
- Start Blender
- Go to File>User Preferences. Click the "Addons" button. Click the "Testing" button under "Supported level" on the left side of the window (Note: this will change once beta testing is finished).
- If Blender2FSX was correctly installed as described above, you should now see the three addons
- 3DView: FSX Materials,
- 3DView: FSX Toolset and
- Import-Export: DirectX X format for FSX.
- Tick the checkboxes to the right of all three of them.
- Click "Save User Settings" at the bottom left of the window.
Blender2FSX is now activated. You can deactivate Blender2FSX at any time by unticking the checkboxes to the right side of the addons or by deleting the files from Blender's addon folder. You can also refer to the Blender Wiki about addons.
You can now check that Blender2FSX was correctly activated. In Blender's "Default" workspace, in the 3DView, in the Toolshelf on the left side of the viewport (press T), you should see three additional Tools right below Rigid Body Tools (assuming default install of Blender):
- FSX Animation Tool
- FSX Attachpoint Tool
- FSX File Properties
Likewise, under "Properties" (right hand side of the default workspace), Object context, should appear a rollout "FSX Properties" underneath "Custom Properties" and in the Material context, a "FSX Material Params" rollout should be shown (scroll down). Under File>Export, there should now be an option "DirectX for FSX(.x)".
This section describes the functionality of the tools included with Blender2FSX.
Note: It is recommended that you read the FSX SDK documentation, section "Modeling SDK", as Blender2FSX closely emulates the functionality of the ACES Toolsets for gmax/3DSMax provided with and described in the SDK. There is a lot to be found there that is beyond the scope of this Wiki page.
Getting started: FSX File Properties
FSX File Properties is a tool located in Blender's Toolshelf in the 3DView, which can be accessed by pressing T on the keyboard. You might want to scroll down a bit to see it. It serves two purposes:
- First thing to do when starting a new Blender session is to click the "Initialize Toolset" Button. This tells Blender where the FSX SDK is installed and populates the other tools with fresh data from the modeldef.xml file. Whenever changing an entry in the modeldef.xml, make sure to reinitialize the toolset to reflect the changes in Blender.
- Each model for FSX needs a GUID (Globally Unique IDentifier) and a friendly name. So, before exporting your model, you should give it a "friendly name" which should only contain ASCII characters. This name is entered in the field "Friendly Name". You should also assign a GUID either by entering it directly in the GUID field (i.e. if generated externally) or by clicking Generate GUID. Saving your file once done will write the GUID and friendly to the .blend file.
You can now start building your model.
Important remark: When building your models, always make sure they have a scale of (1,1,1), otherwise they will not be displayed correctly in the simulator. If you scale objects in Object Mode, you can always reset the scale to (1,1,1) by hitting Ctrl+A > Scale.
Blender2FSX is not foolproof, so here are some general guidelines of what to do and what to avoid in order to yield the expected results with this tool set. However, when you know what each of these guidelines mean, transgressing them gives you more creative freedom.
- Always apply a material to your objects. An object with no material is invisible in the sim and in combination with attachpoints may produce failure of the compiler (XToMdl.exe).
- Always have a generic object (non animated and with no attachpoints) in each LOD. Some functions require this object to be there in order to process other objects.
Organizing your model/scene becomes necessary as it grows larger and includes different LODs (levels of detail). I will suggest one way of doing it. First:
How to export an LOD?
To export an LOD (let's take LOD_400 as an example), create/add an Empty at the origin (0,0,0) of your scene, rename that empty "friendly_name_LOD_400", replacing friendly_name with your model's friendly name, and make it a parent to all root level objects that should go into LOD_400. Repeat for LOD_100, LOD_50 etc.
To keep your scene tidy, you can make use of Blender's layers to isolate LODs from each other. You could for example create all objects of LOD_400 in layer 1, LOD_100 in layer 2 etc. All you have to do is add an empty at (0,0,0) in each layer, and in the end add an Empty named friendly_name, make that a parent to all LOD_XXX empties, to obtain a hierarchy with Empty friendly_name as the root of your scene. You can use the outliner to get a good overview of your scene hierarchy and edit it from there.
FSX Animation Tool
FSX Animation Tool is also located in Blender's Toolshelf. Similarly to ACES' animation manager in gmax/3DSMax, it is used to "tag" animated objects in the scene, so that the animation can then be processed by the XToMdl tool. Open the tool by clicking on the black triangle/arrow to the left. If the toolset was previously initialized (see "Getting started" above), the list window should be populated with animation entries (i.e Ambient, Ambient2, etc.). To tag an object, do the following:
- Keyframe-animate your object. For "Ambient" type animations, the range is defined by you; for aircraft parts, the range is defined in the SDK (example: the rudder would have a range of 0-100 frames, with keyframes at least at 0, 50 and 100).
- In the list window, scroll down to the animation entry corresponding to the animated part, select it (marked blue) and,
- With your object selected, click Assign. The object is now tagged with the animation entry. An object can only be tagged with one animation entry!
You can check which tag has been assigned to the object by going to the "Properties" Panel, object context, FSX Properties rollout: it shows an "Animation Tag" field, a "Length" field which displays the animation range as defined in the modeldef.xml (or 0 in case of "Ambient" type animations; use this to cross-check with your object's animation range) and a Clear button used to untag the object's animation. You can untag all objects in the scene at once by clicking the Clear All button in the FSX Animation Tool. Be careful, this can not be undone!
Hint: Instead of scrolling down the list to find an animation entry, you can use the "search" feature of the list window. Acces it by clicking the small "+" at the bottom left of the list window. Enter a search string/phrase in the search box and hit "Enter".
Skinned animations are partially supported at the moment (2014/01/16), meaning that only one animation tag can be used per armature. This will be fixed in a future release, to allow for each bone to carry an animation tag. For skinned animations to work, use an armature modifier with Vertex groups, envelopes won't work. You can use weight painting to define the influence of bones on the vertices. To assign a tag to a bone/armature,
- Go into Pose mode
- Select the bone you want to tag
- In the FSX Animation Tool, select the animation entry you want to use
- Click Assign
For bones, the FSX Properties are located in the bone context of the Properties panel.
FSX Attachpoint Tool
FSX Attachpoint Tool is also located in Blender's Toolshelf. It works analogously to ACES' Attachpoint Tool, with the difference that it doesn't support Library objects and Empties. An attachpoint is a piece of geometry (i.e. an object) to which an effect, a visibility condition, a mouse rectangle (or clickspot), a "platform" property or a "nocrash" property can be "attached". Combinations thereof can be applied to a single object. Refer to the SDK's document "Using modeling Tools: The Attach Tool" of the Modeling SDK for an in-depth description of the functionality of the different options.
To attach an effect to an object:
- Select the object
- Tick the "Effect" checkbox in the Attachpoint Tool. Options for "Effect" should automatically rollout at the bottom of the tool.
- In the "Name" field, enter a name for your attachpoint. Care must be taken, as attachpoint names must be unique throughout the model/scene!
- In the "Effect" field, enter the filename (without extension .fx) of the effect you want to attach. The available effects can be found in the main FSX folder, subfolder "Effects".
- In the "Param" field, a list of parameters for the effect can be set, as described in the SDK (i.e. DAY=1;DAWN=0 etc.).
- When all is set, click the Attach button.
Note: the object needs to have a material or else effects won't work.
To set a visibility condition on an object:
- Select the object
- Tick the "Visibility" checkbox
- Choose a Visibility tag from the dropdown
- When all is set, click Attach
To make an object clickable in the sim:
- Select the object
- Tick the "MouseRect" checkbox
- Select a MouseRect/Clickspot definition from the list window
- When all is set, click Attach
To define a platform:
- Select the platform object
- Tick the "Platform" checkbox
- In the "Name" field, enter a unique(!) name for the attachpoint (i.e. a name that has not been used before).
- Choose a platform type from the dropdown
- When all is set, click Attach
Note: For some reason, you have to export at least two objects in a model containing a platform, in order for it to compile successfully.
To exclude an object from crash detection:
- Select the object
- Tick the "No Crash" checkbox
- When all is set, click "Attach"
To clear an object from its attachpoint, click the Clear button with the object selected.
Example: Landing light
There is a minor difference when adding a landing light compared to ACES tools in gmax/3DSMax. After creating your geometry (a simple triangle/polygon object), set the transform orientation to "Local" and rotate the object so that its positive Z-axis points in the desired direction of the light beam. Now setup the attachpoint tool:
- Check "Effect" and "Visibility", uncheck everything else.
- Enter a name for the attachpoint (attachpt_landing_4 in the example in the picture)
- Enter the effect's filename without the .fx extension, i.e. fx_landing
- Under Visibility, choose "general_light".
- Click Attach
That's it! You've just added a landing light to your model.
This section describes how FSX Materials are integrated into Blender. For a description of the parameters and their functionalities, refer to SDK document "FSX Material" of the Modeling SDK. All the parameters are simply replicated in the FSX Material Params rollout in the Properties panel in Blender. However, to enable the FSX Material Params, tick the checkbox at the top of the rollout. Currently unsupported features are detail texture and fresnel ramp. These will be added in a future release. It is also worth mentioning that you have to use "normal" materials, as Blender2FSX doesn't support node materials.
The main difference from Blender to gmax/Max with regard to FSX materials is the way texture maps are handled. To create a texture in Blender, select the Material under the material context of the Properties panel, then go to the texture context of the Properties panel.
- Select a free slot in the list at the top of the panel
- Click "New". The panel will populate with options.
- Choose type "Image or Movie"
- Choose the image source file for your texture
- Under Mapping:Coordinates, choose "UV" (you can specify the UV layer as an option)
- Now in the "Influence" rollout, for a
- diffuse map: tick the Diffuse:Color checkbox, untick everything else.
- specular map: tick Specular:Intensity, untick everything else.
- emissive map: tick Shading:Emit, untick everything else.
- bump map: tick Geometry:Normal, untick everything else.
By "untick everything else", I mean that in order to have the correct diffuse map for example, no other texture in the same material should have Diffuse:color ticked in the Influence rollout. You are free to play with the different options, as long as you make sure that only one texture has the crucial option ticked. An exception to this rule are virtual cockpit textures (see below).
For EnvMaps, the texture type is "Environment Map" instead of "Image or Movie". Blender2FSX automatically recognises EnvMaps as long as the type is set correctly and Diffuse:Color is checked under the "Influence" rollout. The setups of EnvMaps differ from Blender to FSX. In order to see the same reflection in Blender renders as in the sim, you will have to reorganize the EnvMap (a.k.a Cube map) as shown in the picture to the left.
Virtual cockpit textures
Virtual cockpit textures are created in the panel.cfg file. Their size is determined by the size_mm and pixel_size entries of the corresponding [VCockpitXX] section, where the arrangement of the gauges on the VC texture is also defined.
In your virtual cockpit, you need to map polygons that will display gauges to the virtual cockpit texture. For this purpose, you need to create a dummy texture that reflects the arrangement of the gauges on the VC texture. The following is taken from the panel.cfg of the default C172 (©Microsoft):
[VCockpit02] size_mm=512,512 pixel_size=512,512 texture=$C172s_2 background_color=0,0,0 gauge00=Cessna!Heading_Indicator, 0, 0,163,162
To make a dummy texture from this VCockpit texture, we would create a 512x512 (see size_mm=) texture sheet and name it $C172s_2 (see texture=) and save it with our favourite paint program. The $-sign at the beginning of the name is important: it tells FSX and Blender2FSX that this is a virtual cockpit texture. We would now proceed to place copies of the gauge artwork on the sheet at the positions defined in the panel.cfg. In this example, we could place the background bitmap of the Heading_Indicator gauge at the top-left corner (0,0) and make sure it's 163 by 162 pixels wide. We would then save the texture (as .png or something else) and head back to Blender.
Back in Blender:
- Create a material for the gauge polygon and name it something sensible like "material_VC_1".
- Under the FSX Material Params rollout, tick the "Is Virtual cockpit texture" checkbox (scroll all the way to the bottom)
- Add a texture for material_VC_1, type= "Image or Movie"
- Point the file source to the newly created $C172s_2.png dummy texture
- Mapping:Coordinates, choose "UV"
- Influence: tick Diffuse:Color and (if you don't use a separate emissive texture for night lighting) Shading:Emit
- Go to the UV/Image Editor and unwrap your polygon
- Map it to the dummy texture
Your gauge polygon is now ready for export.
Exporting to FSX
Calling the exporter module of Blender2FSX is straightforward: Go to File>Export>DirectX for FSX(.x). The main window will change to a file selection dialog, with a box to enter the filename at the top and export options displayed at the bottom left of the window.
The export options are pretty much self-explanatory. Nevertheless...
Export selection Use this option if you want to export only a part of your scene.
In my case, I generally keep layers with the finished work separated from layers with garbage (from boolean operations and such) and helper objects. I also use a lot of Empties (to correct my animations in Blender) that I don't need and want to export. So at export time, I set my "finished" layers to be visible and then Select>Select All By Type>Mesh and choose Export selection.
Apply modifiers This tells Blender2FSX to apply all modifiers (except armature modifiers) on exporting.
This is internal to the export process, so your scene objects will retain their modifiers. Leaving this unchecked will result in having the meshes show up as if there were no modifiers on the stack.
Export animations will generate the creation of a .xanim file along with the .x file. It contains all the animations information of the scene.
Skinned mesh enables the export of animated armatures.
Export MDL creates a filename.MDL file in the folder where your filename.x file is created. This .MDL file can be directly copied to an aircraft's model folder.
Log Verbose causes the exporter to run in Debug mode. Debug messages are output to the Blender system console which can be accessed via Window>Toggle system console.
On occasions, the exporter might quit with an error. For example when:
- There is no friendly name or GUID set. Obviously, you have to set a friendly name and GUID first.
- The exporter can't find the modeldef.xml or the XToMdl.exe. These have to be in the Modeling SDK\bin folder and Modeling SDK\3DSM7\plugins folder respectively. Don't move them away from there. It can also occur that your registry entry "SdkRootDir" points to an obsolete file (maybe after a failed/corrupted installation attempt of the SDK); in that case, clean your registry.
In case the exporter throws an error that you can't figure out, feel free to report it in the support thread.
FSDeveloper is a great place with lots of knowledgeable people who help each other whenever they can. I have learned so much on these forums, thank you all for that. I also want to thank the gurus over at blenderartists.org who got me started on python scripting by patiently answering my noobish questions. And Chris Foster who wrote the official DirectX exporter for Blender. I want to thank the community for keeping me motivated in the accomplishment of this Toolset. May it grow and become better over time. Thank you for reading... Captx-6562