Revision as of 18:21, 24 August 2011

Caveat

Blender is not currently supported by N3V as a modeling source for Trainz, however third-party tools exist for this purpose.

(Warning - this page is under development. Some sections are incomplete and all sections require validation)

Introduction

Blender is a free 3D modelling tool supported by it's 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 several minor releases each year. The current version, as at August 2011, is Version 2.59.

Blender is an extendable program 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.

Requirements

To export from Trainz you need the following:

• Trainz (TS09 or later preferred)
• TrainzMeshImporter.exe. This is provided by N3V.
• Blender V2.57 or later.
• The Blender Exporter.
• Windows Vista or Windows 7 (32 or 64 bit).

Installing the Exporter

The Blender exporter add-on must be installed in the "scripts\addons" area of the Blender data space. For Blender 2.5x this is usually in the Windows logged on user space. However the location can vary depending on your Windows configuration. For simplicity, these instructions assume only one user for the target Windows computer. The Blender add-on must also be enabled within Blender.

(These instructions are paraphrased from Torsten's V2.57 exporter announcement.

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.

Install Blender Exporter for Trainz

Start Blender;

Open a new project(File -> New);

Open User Preferences(File -> User Preferences...);

Select Add-Ons panel and press button "Install Add-On..." 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.

Installing the N3V TrainzMeshImporter program

Before using the exporter you must also copy the TrainzMeshExporter.exe to the same location as the add-on;

In Blender, go to the Help menu in the top panel and click on Toggle System Console if not already enabled. This will allow viewing of errors.

To find the location where you have to copy TrainzMeshImporter.exe to, simply try to export Blenders "default cube". Exporter will complain about a missing file in a specific folder.

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

Note that the AppData folder is hidden by default by Windows. You may need to "Show hidden files and folders" in the folder option for the user's folder.

Once you have copied TrainzMeshExporter.exe to the correct location retry the export.

Exporting an Asset

(work in progress)

Exporter Output

TBD

Error Reporting

Most errors are reported in the Blender System Console and the Exporter log. Some errors are only reported in the system console. Errors (check) will prevent the production of the target IM file and therefore must be addressed. Typical errors are:

Use of the same material for both single and double sided meshes. Incorrect texture mapping coordinates. Only UV and Reflection are permitted.

(more?)

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.

(more?)

The Export Log

TBD

Material Recognition by Blender

The Exporter tries to identify materials in use by the asset mesh and will provide a warning if the actual material decoration varies from that declared in the Blender file. The following decision process, provided by Torsten, may be useful for developers:

The decision which material decoration is used is made by the used texturing schema 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 perfect without any texture. The problem with m.tbumptex and m.tbumpenv is that beside the usage of an alpha texture (which is not used for m.tbumpenv) both use a diffuse and normal texture. In such a case always m.tbumpenv is choosen. Generally you can use any material decoration you want; the script does not change a syntactical correct material decoration(e.g. Materialm.billboard would pass unchanged), it only drop 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's possible to make parent-child-relations between meshes to simplify the design process. However, the chain must be end with a valid parent bone.

References

Material Types ...

TBD

Acknowledgements

TBD