HowTo/Export from Blender

Revision as of 14:11, 13 October 2015

Introduction of Blender

Blender is an open source free 3D modelling application or tool supported by the contribution of programming and development time by the user community. For more information on Blender and its capabilities, please visit the Blender website. Blender evolves rapidly and it is not uncommon to see releases about every two months. As of 11 October, 2015, the current version is 2.76. For those working with a tutorial written based upon an older version of Blender, all past versions of Blender can be downloaded on the Blender past releases page.

Blender is extendable through the use of "add-ons" produced either by the Blender Foundation or by Blender users. One of those add-ons is the Trainz Blender exporter that was built and is maintained by USCHI0815 (Torsten). Torsten usually announces updates to the Exporter through the Trainz Content Creation Support forum. As of 24 April, 2014, the current version of the Blender exporter is V0.96.

Caveat

Blender is not currently supported by N3V as an officially sanctioned modeling platform for producing Trainz assets.

About This Tutorial

The scope of this tutorial has been extended to include installation of Blender and installation of the Blender Exporter since this has been an issue discussed several times in the N3V Content Creation forum.

Requirements

To export to Trainz you need the following:

• Trainz (TS09 or later preferred)
• TrainzMeshImporter.exe. This is provided by N3V.
• Blender (v. 2.57 or later is recommended).
• The Blender Exporter.
• Windows XP, Vista, Windows 7 (32 or 64 bit) or Windows 8 (32 or 64 bit) or Mac OS X (32 or 64 bits).

Blender Installation Notes

Blender is available for a number of operating systems including Windows XP, Windows Vista and Windows 7. Both 32 bit and 64 bit versions are available. You can choose either the installer version or a zip archive. Please read any notes on the Blender.org download page: particularly if you are upgrading from a previous version.

Installer Version

The Installer Version is the easiest way to install Blender but there can be complications. If you install Blender into the default directory you should choose "Use Application Data Directory" during installation of Blender. Otherwise it might not be possible to save your preferred Exporter options due to insufficient permissions.

Blender Zip Archive Version

The zip archive version allows you to unzip the entire Blender folder structure and locate it in any location that suits you. The only drawback is that you will need to set up your own links to the Blender executable (Blender.exe).

Installing the Exporter

The Blender exporter add-on must be installed in the "scripts\addons" area of the Blender data space. The following process will install it in the correct location.

Install Blender Exporter for Trainz

• Download the exporter.
• Start Blender.
• Open a new project(File -> New).
• Open User Preferences(File -> User Preferences...).
• Select Add-Ons panel and press button "Install from file..." down at the panel button bar.
• Select and install downloaded file: you don't need to extract it.
• Enable "TRAINZ Exporter" in Add-On list and press button "Save As Default" to keep it enabled for all subsequent Blender starts.

Install the N3V TrainzMeshImporter

• Download the TrainzMeshImporter.exe. The file is in the RAR format that can be extracted by most zip file management programs.
• Before using the exporter you must copy the TrainzMeshExporter.exe to the same location as the Blender Exporter add-on. The following will help find that location:

• Start Blender and leave the default cube mesh in place.
• If necessary, open the console window so you can read the error messages. In versions 2.5 through 2.63a, the console window is opened using the "toggle system console" menu entry in the "help" menu in the Blender menu bar. Beginning with version 2.64, the "toggle system console" menu has been moved to the "window" menu in the Blender menu bar. Those running a Blender version 2.49 or earlier can disregard this step, as the system console is in a window that is open whenever Blender is active.
• Go to File->Export and select "Trainz Mesh and Animation". Use the default settings but make sure that the save location is a temporary or working space.
• The Exporter will complain about a missing file in a specific folder. The missing file is TrainzMeshImporter and the folder name is the location you need.
• The location is usually in the form of "ERROR" file "C:Users\your name\AppData\Roaming\Blender Foundation\Blender\2.59\scripts\addons\TrainzMeshExporter.exe" not found". This example is typical of using the default Blender Installer. If you chose to install Blender using the zip archive then the location will be different.
• Copy TrainzMeshExporter.exe to the location provided. If you cannot access the AppData folder see the Additional Notes section for help.
• Once you have copied TrainzMeshExporter.exe to the correct location retry the export.

Exporting an Asset

The creation of an asset suitable for Trainz is a long and complex process. For the purposes of this tutorial we will only export the standard Blender cube. Some knowledge of Blender and creation of assets for Trainz purposes is assumed.

• Start Blender and save the default cube as "cube.blend" in your preferred working location.
• Create a simple material such as "cube.m.onetex" and allocate a simple colour texture file. For the purpose of this tutorial leave the default mapping technique to "generated". This will cause an error.
• UV map the cube to the texture.
• Save the Blender file.
• Go to File->Export and select Trainz Mesh and Animation.
• The dialog box that appears gives a output save location for the XML, log, texture description and other files produced by the process. Select your preferred location.
• All the other options can be left as default. If you were exporting a mesh that included animation, then you would also select "Export Animation Data".
• When you are ready, select "Export Trainz" in the top right hand corner.
• This export process will fail with an error since the "generated" mapping option for textures is not supported when using an image file. Go back to the Texture section and change the mapping option to UV and then export again. This time it should export correctly.

Exporter Output

Files Created

The Exporter produces:

• An XML file. This is used by TrainzMeshImporter.
• The IM mesh file required by Trainz.
• The texture description files (nnn.texture.txt) required by Trainz.
• The KIN animation file required by Trainz if animation is used.
• A log of the export process.

Error Reporting

Errors are reported in the Blender System Console and the Exporter log. Errors will prevent the production of the target IM file and therefore must be addressed. Typical errors are:

Mesh Errors

• Objects without a parent where a root bone exists.

Material Related Errors

• No UV layer for UV mapped objects. Blender usually creates a default.
• Use of the same material for both single and double sided meshes. Recommend only using single sided meshes.
• Objects without an assigned material. Recommend assigning a material for each object.
• Faces without a material in an object. The faces will have been collected into a Vertex Group to enable correction. This error can also be caused by material slots in blender to which no material is assigned.
• Use of similar material names if character case is ignored. i.e. "Black" and "black" are considered the same by Trainz.
• Not using UV mapping for textures that are either using alpha, normal or specular.
• Not using UV or reflect mapping for diffuse textures.

Animation Errors

• More than one root bone

Warnings

Warnings are basically flaws or possible flaws that the user may wish to address. Warnings do not prevent production of the IM output files. Some typicals warnings include:

Animation Warnings

• Possible incorrect location and rotation of root bone.
• Bones not found or no animation data found.
• Events not found or unrecognised.
• Event frame numbers in wrong positions.

Mesh Warnings

• Vertices influenced by more than four vertex groups.

Name Warnings

• Unrecommended characters. Material, texture, object and path names should only be composed of a-z, A-Z, 0-9 or -_./\ characters. A typical error is use of a space character in a path name. The Exporter will change Blender file names that include upper case letters to lower case letters. Generally, it is recommended you avoid the use of upper case characters in names.

Material Warnings

• Surfaceless faces in an object. The Exporter will gather these faces and put them into a Vertex Group to aid identification. The Vertex Group can be found in the triangle panel associated with the Safety Valve object.
• Objects exported with double sided faces. This will become an error if a material is used for both single and double sided objects.
• Material renamed. If the name does not match one of the standard Trainz material names then the Exporter will try and effect a solution. Typically a name such as "black" will be renamed "blackm.onetex".

The Export Log

The Exporter Log contains a record of events during the export process including errors and warnings. The numTriangles report is the number of polygons (aka polys) in the mesh.

Material Recognition by the Exporter

The Exporter tries to identify materials in use by the asset mesh and will provide a warning if the detected material decoration varies from that declared in the Blender file. The term "material decoration" is one of the standard Trainz material names such as "m.onetext" or "m.tbumptex". The following decision process, provided by Torsten, may be useful for developers.

The decision which material decoration is used is made by the texturing schema used for the material:

no texture used -> m.onetex

one texture used:

invalid texture -> m.onetex

diffuse texture -> m.onetex

reflection texture -> m.reflect

two textures used:

diffuse & alpha -> m.onetex

diffuse & reflection -> m.reflect

three textures used:

diffuse & alpha & reflection -> m.gloss

normal texture used:

normal & diffuse & alpha & no reflection -> m.tbumptex

normal & diffuse & reflection & no alpha -> m.tbumpgloss

normal & diffuse & no alpha & no reflection-> m.tbumpenv

As material m.notex causes problems with specific assets, m.onetex is used instead. It also works perfectly without any texture. The problem with m.tbumptex and m.tbumpenv is that, besides the usage of an alpha texture (which is not used for m.tbumpenv), both use a diffuse and normal texture. In this case m.tbumpenv is chosen.

Generally, you can use any material decoration you want. The script does not change a syntactically correct material decoration(e.g. Materialm.billboard would pass unchanged). It only drops a message to remind you that you either use an unsupported material(as warning) or that it had chosen another material(as info).

If you check the issue and find it to be OK than you can safely ignore those messages.

Blenders texture influences are nearly equivalent to MAX material maps. Because diffuse textures and reflection textures both influence diffuse color, the decision between them is made by checking texture mapping coordinates to:

MAX map -> Blender texture influence

Ambient Color -> Shading Ambient

Diffuse Color -> Diffuse Color & UV mapping

Specular Color -> Specular Color

Specular Level -> Specular Intensity

Glossiness -> Specular Hardness

Self-Illumination -> Shading Emit

Opacity -> Diffuse Alpha

Filter Color -> Diffuse Translucency

Bump -> Geometry Normal

Reflection -> Diffuse Color & Reflection mapping

Refraction -> not available(not found?)

Displacement -> Geometry Displacement

Torsten's Hints

These hints are reproduced from the Exporter script since many will not want to edit or view the actual script contents.

In Trainz models you can have two kinds of special objects: attachment points and bones. For attachment points, the exporter expects objects of type "Empty". For bones, objects of type "Lattice" and "Armature" will be accepted. All of them need to be named according the naming conventions in effect for attachements( a.* ) and bones( b.r.* ). Objects of other type and objects with proper type but names not matching this conventions will be ignored as attachment points or bones.

If you want to export animations with events, than you have to create a Blender TX object and enter the lines as you would do to create an event file. By renaming this object to "events" you ensure the exporter will not ignore your event list.

It is possible to make parent-child-relations between meshes to simplify the design process. However, the chain must be end with a valid parent bone.

Additional Notes

Blender Data Files

Blender keeps certain data files, such as add-on utilities, in a special location. This has given Trainz content creators some difficulties due to access rights. If you used the Blender Installer then this is usually in the Windows logged on user space.

Say, for example, your user name is Patrick, then the location is likely to be similiar to "C:\Users\Patrick\AppData\Roaming\Blender Foundation\Blender\2.59\scripts\addons".

If you cannot see this folder in the user folder then it is likely the folder has been hidden by Windows. You can unhide folders in the Windows Explorer by going to Tools->Folder Options->View and selecting "Show hidden files, folders and drives".

Under The Hood or, How the Exporter Works

Basically the Blender export process works in three phases:

• Phase 1 is the checking process where the Exporter does some validation. Where it can, the Exporter will make minor corrections and just issue a warning. Warnings do not stop the process but an error will. The warnings and errors should provide enough information to enable correction.
• Phase 2 is the creation of the XML file required by the TrainzMeshImporter. The XML file is a text file using a common language used by many applications. It is also N3V's preferred import format.
• On succession completion of the first two phases, the Exporter passes control to the TrainzMeshImport program which takes the XML file plus other information and produces the IM mesh file used by Trainz.

Acknowledgements

Many thanks to USCHI0815 (Torsten) for his time and effort that went into producing and supporting the Blender Exporter. Without it there would be no Blender models in Trainz.

Thanks to Mick_Berg and Jananton for their comments, and to Mick_Berg for his Blender installation tutorial.

Tutorial Updates

Please feel free to update as necessary and correct errors in this tutorial. It is a WiKi contribution and intended to be maintained this way.

References

Material Types