HowTo/Export from Blender

Latest revision as of 15:09, 14 January 2021

Please note that this document is obsolete as of trainz-build 4.5. See HowTo/Export from Blender using FBX instead.

[edit] Blender

Blender is an open source free 3D modelling application supported by the user community. For more information on Blender and its capabilities, please visit the Blender website.

[edit] Exporting Models from Blender to Trainz

You can export model from Blender to Trainz in either Indexed Mesh (IM) or FilmBoX (FBX) format. The FBX format was introduced to Trainz from trainz-build 4.5. IM files are obsolete although still acceptable and content creators are encouraged to use FBX. See HowTo/Export from Blender using FBX.

This tutorial is also obsolete and may not be maintained.

IM meshes can be exported from Blender using a Blender addon developed by USCHI0815 (Torsten). This addon was available on the BitBucket site but has been removed after a re-organisation of the site. If you want a copy of the exporter you may be able to obtain one from another Trainz Blender user by asking on the Trainz forums. The current and probably last version of the Blender exporter is V0.96.

[edit] Caveat

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

[edit] 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.

[edit] Requirements

To export to Trainz you need the following:

Trainz (TS09 or later preferred)
TrainzMeshImporter.exe. This is provided by N3V.
Blender Version 2.79 or earlier. The exporter will not work for Blender 2.80 and later.
A copy of the Blender Trainz XML exporter.
Windows - most modern versions.

[edit] 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.

[edit] Install Blender Exporter for Trainz

Obtain a copy of the exporter from another Trainz content developer. The file is written in the Python language and the filename is called "export_trainz.py".
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.

[edit] 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.
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.79\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.

[edit] 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.

[edit] Exporter Output

[edit] 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.

[edit] 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:

[edit] Mesh Errors

Objects without a parent where a root bone exists.

[edit] 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.

[edit] Animation Errors

More than one root bone

[edit] 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:

[edit] 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.

[edit] Mesh Warnings

Vertices influenced by more than four vertex groups.

[edit] 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.

[edit] 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".

[edit] 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.

[edit] 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 name 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 can cause problems with some 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 name you want. The script does not change a syntactically correct material name (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

[edit] 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.

[edit] Additional Notes

[edit] 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".

[edit] 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.

[edit] 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.

[edit] References

Material Types