Blender2FSX Toolset manual

From FSDeveloper Wiki
Revision as of 15:19, 25 May 2024 by BASys (talk | contribs) (Replaced Applicable-FSVersion for MSFS with MSFS2020, added MSFS2024.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Blender2FSX/P3D Toolset is an addon for the 3D-modelling application Blender. This Wiki page is intended to introduce the reader to the use of Blender2FSX/P3D to export models created in Blender for use in Microsoft Flight Simulator X (FSX & FSX: SE) and Lockheed Martin Prepar3D (P3D) and shows some things to consider when modeling for FSX/P3D in Blender. It is NOT a generic tutorial on how to build models in Blender.

Requirements

  • Windows 10 & 11
  • Microsoft Flight Simulator X SDK including updates to SP2 or Acceleration
  • Lockheed Martin Prepar3D SDK v1.x, v2.x, v3.x, v4.x & v5.x (FSX Steam Edition should use the Prepar3D SDK v1.x)
  • Make sure that ALL SDKs that you are planning on using are installed prior to installing/ activating this Toolset!

Installing Blender2FSX/P3D Toolset

Installing

  • Download the latest Blender2FSX/P3D Toolset that is in the Resource Section.
  • Start Blender
  • Go to "Preferences" (Edit->Preferences). Click on the "Add-ons" tab and then click on "Install...".
  • In the file manager, navigate to where you have downloaded the Toolset file, select it and click on "Install Add-on". This will extract the content of the zip file to your Blender script folder (by default under %APPDATA%\Blender Foundation\Blender\<version number>\scripts\addons)

Activating the Toolset

To activate the Toolset in Blender,

  • To activate the addon: clicking on the check-mark next to "3DView: P3D/FSX Toolset". That should enable the addon and the various panels and properties. Close the Preferences window.

To ensure that the addon was correctly installed, press "N" key on your keyboard while the mouse pointer is in the main viewport. This should open the main panels of the addon under the tab named "P3D/FSX".

  • FSX/P3D File Properties
  • FSX/P3D Animation Tool
  • FSX/P3D Attachpoint Tool
  • FSX Verify Tool

You can deactivate Blender2FSX/P3D at any time by unticking the checkbox within the Preferences window.

The Tools

This section describes the functionality of the tools included with Blender2FSX/P3D.

Note: It is recommended that you read the FSX SDK documentation, section "Modeling SDK", as Blender2FSX/P3D 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

File Properties Tool

FSX File Properties is a tool located in Blender's Toolshelf in the 3DView, which can be accessed by pressing N 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 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 & P3D 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.

General guidelines

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 some of them gives you more creative freedom.

  • Always have a scale of (1,1,1). Any object that doesn't have a scale of (1,1,1) may show unwanted behavior in the sim, especially when animated. To reset the scale of an object, hit Ctrl+A > Scale.
  • 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.
  • Avoid non-ASCII characters wherever possible in all your names (objects, materials, attachpoints, etc.). While there is some "safename" functionality for most of the export process, errors might occur if naming a material "Matérial" or an effect "mañana"... The same applies to file and folder names in your project path. Using special characters in folder names may result in XToMdl not functioning properly, i.e. a corrupt .MDL file on export.

LODs

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.

Using layers

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

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!
FSX Properties

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 meshes

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 tab of the Properties panel, where you can check which animation tag has been assigned to the bone.

It is important to note that every vertex needs to be assigned to a vertex group/bone. You will need a static bone for the non-deforming part of your mesh.

Constraints can be used on bones just as on regular objects.

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.

Effects

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.

Attachpoint Tool

Visibility

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

Mouse Rectangle

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

Platform

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.

No Crash

To exclude an object from crash detection:

  • Select the object
  • Tick the "No Crash" checkbox
  • When all is set, click "Attach"

Clear Attachpoint

To clear an object from its attachpoint, click the Clear button with the object selected.

Example: Landing light

Attachpoint Tool: Adding a landing light effect

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.

FSX Materials

FSX Material: Texture slots

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.

Texture maps

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. (visible texture)
    • specular map: tick Specular:Intensity, untick everything else. (influences the reflections of the diffuse texture)
    • emissive map: tick Shading:Emit, untick everything else. (night texture, formerly known as _LM texture)
    • bump map: tick Geometry:Normal, untick everything else. (adds some kind of surface roughness)

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

Hint: Don´t forget to check the "FSX Material Params" in the Material, otherwise none of the above options will work. You will then only see the diffuse texture.

Environment map for Blender

Environment maps

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

Export options

The export options are pretty much self-explanatory.

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.

Exporter errors

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