# Trainz/Tutorial for Blender
## Newcomers start here

Blender is a complicated professional grade 3d modeling tool which has been used to create static and animated models, computer games, and animated, and short films. You can either go directly to Trainz Specific Moving House tutorial below or you may wish to spend time learning to use the software proficiently before attempting to create content for Trainz. There are many sources of information on Blender, including high school and college level courses, forums, and tutorials.

### Courses

* A free high school level course, created by James Chronister, of Central Dauphin High School, in Harrisburg, PA.
* A free college level course, created by Neal Hirsig of Tufts University.

### Sources for help

Besides the official Blender site, from which the software can be downloaded, and at which the user can find forums, and tutorials there are a number of third party sites which offer tutorials or forums supporting Blender. As of first quarter 2013, these include (but are not limited to)
* Blenderartists.org
* Blenderguru.com
* Blendertut.com
* Blendertutor.com
* cgcookie.com
* rab3d.com
Youtube also hosts a number of channels of material by people creating Blender tutorials.

### Other Considerations

* Because Trainz uses phototextures exclusively, users wanting to create content will be well advised to have working knowledge of image manipulation software which is capable of writing image files in jpeg and uncompressed ~.tga formats.
There was a major update to Blender effective with version 2.50, issued in July 2010, which dramatically changed the user interface. Unfortunately, many of the tutorials for Trainz were created with the older interface, and while users well versed in more recent versions of Blender can complete the tutorials, less accomplished users who want to use the older interface can still obtain that version of the software used in the tutorials from the download site.
The first thing you have to do is install Blender. So go directly to http://en.wikibooks.org/wiki/Trainz/Tutorial_for_Blender#Getting_started and follow the instructions on installing Blender and the exporter.

### Trainz Specific Moving House tutorial

The recommendation is to watch the video tutorials http://en.wikibooks.org/wiki/Trainz/Tutorial_for_Blender#Video_tutorials_from_Blender.org before attempting the basic house tutorial but it is not essential to do so.
Next you need to create something then export it.
* Tutorial to build a basic house:
* Tutorial to build a basic house:2.65
To texture this house download kuid:86627:2491 or any version of it such as kuid2:86627:2491:3. You want the texture file from it (Terrace one.tga). Use that file and the texture tutorial to texture the house. It is a 3.25 Mb download so if you don't have a first class ticket you might do better downloading it from TrainzProRoutes.com. The object is called Leopold Lane slate roof with front yard and pavement.
* Tutorial to texture a basic house:
* Tutorial to texture a basic house: in 2.65
To export the house:
* Tutorial to export a basic house:
* Tutorial to export a basic house: in 2.65
To convert it into a moving house:
* Tutorial to create a moving house:
* Tutorial to create a moving house: in 2.65
If we change the shape we can actually get a reasonable basic wagon out of it.
Also please note that Paul Hobbs has three blender tutorials here: http://www.44090digitalmodels.co.uk/
These tutorials cover a lot of material quite quickly and Paul is very knowledgeable.

## About this page

    The intention of this page is to assist people in exporting their Blender creations directly to Trainz using the Blender Exporter for Trainz. Only items that are pertinent to the exporter will be described here. If you are stuck in Blender or have a question about Content Creation itself, then you find a lot of explanations and experienced people under the following links:
    Blender Documentation
    Blender Community
    TRS2006 Content Creation Guide
    Trainz Discussion Forums
Tutorials:

## Video tutorials from Blender.org.

Start with the Interface.avi then follow with the 3dview.avi
    Blender getting started tutorials
    Blender video tutorials
    Blender animation video tutorial View this one to see how to make a roof.
Under the heading Textures is a basic tutorial that will guide you through creating a cylinder in Blender then exporting it as a scenery object and also as a wagon into Trainz. Sample config.txt files for cylinder are available on the DLS. Please do the video getting started tutorials first.
Blender is a big complex product but we only need a sub section of the features for building models for Trainz, so start with the tutorial under Textures then have a look through the getting started videos, especially the interface ones.
Things you may find useful when working with Blender.
Under File is "load factory settings", in Blender it is possible to change the default this one gets you back to sanity.
When texturing with an external .tga file the exporter expects a certain type of texturing. Even if you can see it in Blender it may not export. F6, choose as texture type "Image" and load your image file.
b is box select, ie select everything in the box.
Trainz requires absolute sizes and positioning. Type "N" to bring up a properties dialog so you can type in dimensions directly. Note the name is entered here OB:a.limback etc. You can select or search and select an object in the outliner window / view, then mouse over to a 3d view where you can tab to edit. You may need to experiment in outliner to find the view that lets you select.
Working with four 3D windows above the button window makes sense. If you go into user preferences (click the mouse just below the file add labels and pull them down) click on the view name button each quadrant will be labelled.
Number pad 0 is camera view, the others are 1 3 7. <Ctrl>3 or <Shift>3 gives the opposite side etc. 5 changes from ortho view to perspective.
fa: next to the www.blender.org 2.46 gives the number of faces, multiply by 2 to get poly counts. M move the selected item to a different level to see the poly count for a selected item. You can reduce the poly count be selecting unseen faces then deleting them.
F9 brings up the double sided button to turn off double sided texturing.
Use append (<Shift><F1>)to combine things from two files. http://wiki.blender.org/index.php/Manual/Using_Linked_Libraries
To change the texture file name F6, then change the file name under still.
To pick out an item by name use the outliner.
When creating an animated load note that the first and last frame seem to interact so the highest load should be the frame before last or a wagen with no load may show the high load when empty. Also export with the frame number set to the highest number.
To tile a texture in Blender "Select your plane, press F, press A until all the faces are selected, and then in the UV image editor press A a few times until everything is selected. Press S and scale it up. That is it... just scale it bigger then the UV texture window and it will automatically tile for you"
The following link shows how to (use) import blue prints into Blender.
http://www.the-blueprints.com/index.php?tutorials/blender/
Importing from GMAX into Blender
The process is:
http://www.44090digitalmodels.co.uk/
first tutorial setting up GMAX.
Page 6 and 7 refer to Tempest game pack this gives you a MD3 export. It also tells you were to download the tempest game pack. If you get desperate I think I have it somewhere. Getting out of GMAX is the most difficult part.
Then go here: https://svn.sourceforge.net/svnroot/...trunk/blender/
copy all the scripts into your Blender script folder.
Import md3.
references:
http://blenderartists.org/forum/showthread.php?t=91838
http://en.wikibooks.org/wiki/Blender...pts/md3_import

## Getting started

    What you need to create content for Trainz with Blender is obviously Blender itself Note 2.49b the version that many Trainz specific tutorials use can be obtained here Blender2.49b and the Blender Exporter for Trainz. The script was developed for Blender 2.45, by Torsten but any later version should work also. To use the Blender Exporter for Trainz, you must unzip the archive and copy the included file trainz_exporter.py into the script directory of Blender. This is normally the folder scripts located in the subdirectory .blender, so if you install Blender on a Windows system using the default path, you have to copy the file trainz_exporter.py from the archive into the folder C:\Program Files\Blender Foundation\Blender\.blender\scripts. On some Blender installations it maybe found in Application Data\Blender Foundation\Blender\.blender\scripts under document and settings, application data maybe a hidden folder / directory in windows which makes locating it difficult sometimes especially on Windows 7 machines where you may have to turn off UAC to reach it. Alternately if you have two different versions of blender installed or have upgraded from one version to the another you will find additional folder in the "\Application Data\Blender Foundation\Blender" location. Open the folder for the current version of blender your using for example "Application Data\Blender Foundation\Blender\2.60\scripts\addons\"
For Blender 2.5 and later you need the exporter at bitbucket also by Torsten bitbucket.org. The scripts that are available for download work with blender 2.65 at the time of this writing.
You also need to copy in the Auran XML importer, needed for Blender etc. http://online.ts2009.com/mediaWiki/index.php5/Downloads then download Trainzimporter.rar
Every time Blender starts it scans this directory and include any scripts found into its menu structure. So if you start or restart Blender after copying the exporter script then you call it using the Blender menu File > Export > Trainz Export. After selecting what you want to export and if no problems occur you find yourself in Blender's file save dialog. Choose the desired location and filename and press Save to finally create the resource file. You should always check the Blender console for infos or warnings, as the exporter only stops at fatal errors.
Help for Blender is here: http://blenderartists.org/forum/
and this thread on the forum contains lots of useful information. http://forums.auran.com/trainz/showthread.php?89501-Blender-Exporter-for-Trainz&highlight=Blender

## Blender settings

We are still experimenting with the Blender settings in order to get the best results in Trainz. Nevertheless, the following suggestions should be noted:
* In Blender it is not possible to set a reference scale for Blender units, unlike in GMAX where we can specify that one GMAX unit equals, say, one metre. In Blender, simply assume that one Blender Unit (BU) is one metre. This is the assumption that is built in to the Trainz Blender exporter. If you want to use imperial units, then you may wish to explore the Blender Mesh Attribute Editor script.
* If you want to move an object to an absolute position, then change to Object Mode via Tab ↹ then press N. The Transform Properties window will appear, then you can enter the values you need. A word of warning, however: LocX, LocY and LocZ refer to a coordinate in the local coordinate system. These refer to a coordinate in the world coordinate system only if the object does not have a parent. If you have already assigned a parent, then you must enter the location relative to that parent.
* Not all material properties visualized in Blender will have an effect in Trainz, and some effects achievable in Trainz are unable to be visualized in Blender. Therefore be sure to take a look at your model in Trainz, and do not trust what you see in Blender.
* Regarding textures: only diffuse, opacity, reflection and normal maps have any effect in Trainz. You can also export meshes that do not have any texture.
* If your installation folder is on your boot drive and in Program Files, you should also ensure that your temp folders (set in user preferences) are somewhere else or Blender will have problem writing temp files.

## Objects
### Meshes

    Meshes are the Blender objects you will see in Trainz. You can build your objects by manipulate Blender primitives or even place vertices and create faces. Just keep in mind the following things:
   * center your creation around the point of origin, as Trainz place this point at cursor position when you insert the asset
   * Faces can be double or single sided, in Blender this is a mesh and not a material option. You will recognize the difference only in Trainz, as Blender render faces always double sided.
   * every mesh needs a material; you can use one material for different meshes
   * keep an eye on vertex and face count
    The Exporter only recognizes meshes which are visible during export. Make sure all objects you want to export are visible and you have selected all needed layers too! There are two reasons for this behaviour: First, nothing will be exported what you not see(maybe a long forgotten test mesh). The second reason is that you can hold big or animated objects in one Blender file and export only the needed parts by changing visibility(here the layers comes into play).

### Bones

    The term bone in this section stand in general for a helper object to build up hierarchical animation systems. It is not related to the subobject Bone contained in Blender Armatures. Up to now, the Blender Exporter only recognizes Lattices as valid bone-objects.
    Here are two tutorials to get a clue about animation basics in Blender:
       • Animation do this video tutorial first to understand the basics like where the frame number is.
       • Next for simple animation such as we use in Trainz do this tutorial.
    As soon as you want to animate your asset, there is no way around using bones. You can create bones by placing a Lattice(Add > Lattice) and rename it to something like b.r.something as it is described for the bone naming conventions in CCG.
    Note the animation works by making the bone b.r.rot etc a parent of object then the animation is applied to the bone.
    If you use bones you need to build up a complete hierarchy, that mean starting from a root bone all other bones or meshes need to be child of this root bone or any subordinated bone. The Exporter will fail if you have loose meshes or bones, because unbound meshes will not shown in Trainz.
    The root bone should be located at the point of origin and should not be rotated. Best practice might be to place it in top view (Hotkey NumPad 7) and leave it untouched. The root bone also must not be animated; it serves as parent for any not animated mesh within this asset and for any bone which is not driven by/depending on an animated parent.
    To export bones they must be visible; so watch your Outliner and your Layers.

### Attachment Points

    Attachment points are used in Trainz to attach effects, tracks or even other meshes. To create an AP you have to add an Empty first(Add > Empty). Afterwards place and rotate it like you need and give it a name following the CCG-Rules for APs(a.whatsoever, do you remember? ;)). APs don't need a parent, as this information will get lost during export. To although made animation possible, Trainz use an extended naming schema. Assume you have a bone b.r.john and an AP a.doe. To tell Trainz that a.doe should be animated like b.r.john, you must rename the AP to a.r.john/a.doe. In your config.txt this AP is still to refer as a.doe.
    What is valid for meshes and bones, is also valid for attachment points: If they are not visible, they will not be exported.

## Materials
### Colors

    You can manipulate diffuse and specular color in Blender to give the material in Trainz the appearance you want. Both you find at the material panel, Col for diffuse and Spe for specular color:
    There are two other colors supported by Trainz: ambient and emissive.
    The ambient color in Blender work different from Trainz and as in most cases ambient and diffuse color will be equal, ambient color is copied from diffuse color during export. The emissive color is used for self illumination in Trainz and not provided in Blender. As things normally have the same color even if lighted or light, the Exporter here also copies the value of diffuse color.
    If you plan to use textures you should set the diffuse color to pure white, else your textures will appear darker in Trainz than expected.

### Opacity

    Also on the material panel you find the slider for Opacity, in Blender called Alpha(slider A down at the right side). A value of 1 means the material is completely visible, a value of 0 render your material completely invisible. If you use texture maps which also affect the opacity, then better leave the Alpha-slider at its right position as the over all opacity will not be higher then the material opacity.

### Specularity

    Specularity can be adjusted using the Shaders panel. The interesting sliders are Spec (specularity) and Hard (hardness) in the middle of the panel:
    The Spec ("specularity") slider adjusts the intensity of specular color from 0 (no specular highlight) to 2 (full specular highlight), while the Hard ("hardness") slider adjusts the intensity of the reflected light. A high hardness value gives a hard specularity (imagine glass or an polished surface), whereas a low hardness value gives a dull shine (like asphalt or rough/dirty metal). The hardness range (0 to 511) will be scaled down by the Trainz Exporter to 0 to 128. A hardness value below 4 switches off specularity in order to avoid strange effects in Trainz.

### Self Illumination

    The brightness without to be lighted. You find the slider Emit in the lower right corner of shader panel. The more emissive you order, the more your material glow in diffuse color.

## Textures

This is the area that causes the most problems.
This is the simplest case so do it first, once you have this part working you can add complexity.
Right click the image below and save it as Blender cylinder texture.jpg. Trainz can use .jpg files but it is much better to convert it to Blender cylinder texture.tga.
Step 1: After starting Blender, delete the default cube. Press Space then create a cylinder of 8 sides. Press N, which displays the Transform Properties dialog.
Step 2: By changing the values in the Transform Properties dialog, you can change the dimensions and rotation of the object. Here the cylinder has been raised by 2 metres by changing LocZ to 2.00 and its direction has been changed by setting its RotY to 90.
Step 3: Press F5. In the Links and Pipeline pane, select ADD NEW from the dropdown menu that currently displays MA:Material.
The dropdown menu should now display MA:Material.001.
Step 4: Press F6. In the Texture pane, select ADD NEW from the dropdown menu that currently displays TE:Tex.
The dropdown menu should now display TE:Tex.001. Select Image from the Texture Type dropdown menu. The Map Image and Image panes will appear.
Step 5: In the Image pane, press Load then navigate to your image file.
Double-click the image file and its name will appear in the second field at the top of the file-select dialog. Press SELECT IMAGE and the image's metadata will appear in the Image pane.
Step 6: Press F5 then navigate to the Map Input pane. Press the UV button to change the map input to UV.
Step 7: Change one of the 3D display windows to UV/Image Editor and press the button immediately to the right of the Image button in order to select the texture file you just loaded.
Step 8: In order to map the texture, we have to unwrap the mesh in Edit mode. Change from Object mode to Edit mode by pressing Tab ↹.
Step 9: Make sure the entire mesh is selected by pressing A. Press U and select Unwrap (smart projections) to unwrap the mesh.
Accept the default settings by clicking the OK button.
Step 10: In order to edit the UV mapping, click the UV Island select mode button in the UV/Image Editor's toolbar. The button looks like an equilateral triangle with little squares representing the vertices.
Step 11: Move the faces of the mesh into position on the texture map. First, in the UV/Image Editor window, select the eight faces that comprise the lower end of the cylinder. Right-clicking selects one face, and ⇧ Shift+right-click selects multiple faces in succession. Once selected, position the faces over the orange circle on the texture map. To do this, use the Grab tool (press G and move the mouse). If necessary, you can constrain the Grab tool to the x- or y-axis by pressing G+X or G+Y, respectively. You can rotate the faces if necessary using the Rotate tool (press R). Scale the faces down to fit inside the circle by pressing S then dragging the mouse. Position the faces that comprise the top end of the cylinder on the blue circle of the texture map in the same way.
Scale down the faces of the cylinder's side in order to avoid a coloured dot in the middle.
For a preview of the result, press F12.
Step 12: Return to Object mode by pressing Tab ↹. Now it's time to export the object to Trainz. Go to the File menu and select Export\Trainz Export (im, km, pm).... Export the object to cylinder.im to match the sample kuid. Copy the cylinder.im file, texture file and texture.txt file into a scenery object clone such as kuid:86627:1791 available on the DLS. The scenery object should show up in Trainz.
If you don't have the Trainz Exporter script, get it from the SourceForge project page. Copy the script file into Blender Foundation\Blender\.blender\scripts\.
To create a wagon or locomotive, we need to add attachment points and have a different config.txt file such as kuid:86627:1792 (available on the Trainz Download Station).
First we need to rotate the object so that it sits along the track. In Object mode, press N to enter the Transform Properties dialog. Note the RotY and RotZ values here.
We are going to add more items to the scene and in order to select items easily in Blender we use the Outliner. Select Outliner from the Window type list (first button in the toolbar of the lower window). Bring up the Outliner, then press the View button in the Outliner's toolbar, then select Show Outliner.
Next we add the empty which will become our attachment point.
Trainz expects to see a specific name on the attachment point so we change the OB: name in the Transform Properties dialog from Empty to a.limfront.
In the Transform Properties dialog, change the LocZ value to 0.89, the LocY value to -4.5 and the LocX value to 0.0.
We need to add another attachment point for the rear coupler. Duplicate the a.limfront attachment point by pressing ⇧ Shift+D. Rename the duplicate to a.limback. Change its LocY value to 4.5.
We also need to add attachment points for the bogies. Add the following attachment points:
* OB: a.bog0 with parameters LocX = 0.0, LocY = -1.0 and LocZ = 0.0
* OB: a.bog1 with parameters LocX = 0.0, LocY = 1.0 and LocZ = 0.0
If you are using the sample wagon config, you also need to add:
* OB: a.bog2 with parameters LocX = 0.0, LocY = 0.0 and LocZ = 0.0
Now save your work (Name your file 'cylinder') and export the model to Trainz. File/Export/Trainz Export. Copy the cylinder.im file, texture and texture.txt file into a wagon object clone such as kuid:86627:1792 available on the Trainz Download Station. The wagon object should show up in Trainz. Note the sample kuid has two cylinders so if you see one you have been successful.

### General

At first some common things to textures:
* NEVER use compressed image formats such as .jpg, as they often distort colors, waste resources while loading (to extract they need additional memory and CPU-time) and have the same footprint in memory as an uncompressed picture format. A good format to use is Targa (.tga), as it is uncompressed (don't use the RLE-option!) and also has the ability to store an alpha channel if required.
* Make your textures as small as possible. What ever should work is the creation of your texture twice as big as finally used and afterwards scale them down with enabled antialiasing. You get nearly the same detail grade as in the original map and need only 1/4 of its memory.
* Always use "power of 2" values as map dimensions (i.e. 64x64, 128x128, 128x512). Such textures could processed very fast because "power of 2" - numbers are the native language of your hardware. If you don't abide by this rule your meshes will be white in Trainz. You don't have to use square maps, but you must avoid an aspect ratio above 1:8 (this is unsupported in Trainz).
In Blender in order to access textures you must first add them to the project through the Texture pane in the Material buttons window. Press F5 to access the Material buttons window, then click the Add New button in the Texture pane to add a new texture.
| 3 - Blender Texture panel - empty | 4 - Blender Texture panel - texture object created |
After creating a texture (TE:) object you use the Map Input pane to tell Blender where the mapping information should come from, and the Map To pane to specify which material property should be influenced.
| 5 - Blender Map Input panel | 6 - Blender Map To panel |
The default map input choosen by Blender is Orco. This is okay for reflection maps, but for the other kinds of maps the Exporter script only accepts the UV map input. As mapping target (Map To pane) you can choose one or more of the following options:
      * Col, used for diffuse maps
      * Alpha, used for opacity maps
      * Ref, used for reflection maps
      * Nor, used for normal(bump) maps
You can assign other mapping targets and these textures will be exported, but you will not notice the slightest effect in Trainz.
What's now left to do is of course loading the texture itself. In Blender you define the content of a texture using the Texture pane (press F6 to access). The only Texture Type you can export to Trainz is Image, so all of the other options (DistortedNoise, Voronoi and so-on) can be ignored.
    Now select the appropriate image by pressing Load on the Image panel.
    There is only one option left, the option "no texture". The Blender Exporter for Trainz allows you to export models without any texture. This can speed up asset creation due to "quick checks" of the pure mesh directly in Trainz. To export without any texture you simply have to delete eventually assigned texture objects.

### Diffuse Textures

    Diffuse textures are the kind of textures used most often. They essentially define the surface of objects. To use them you need to select the UV button in the Map Input pane, and the Col button in the Map To pane. You can adjust the amount of texture with the Col slider on the right-hand side of the Map To pane.

### Opacity Textures

    Alpha textures are used to simulate transparent materials or to make parts of your object invisible. You can create dirty windows or let a simple plane look like a bogey part. An alpha map normally comes together with a diffuse map, so the needed UV mapping should already be done. As target select Alpha. The texture amount is controled by slider Var at the right side of Map To panel.
    You can combine diffuse and opacity texture if you use an image with alpha layer. You need to select the option UseAlpha at the Map Image panel and must select Col and Alpha as targets at the Map To panel.
    One little problem can occure if you work with opacity: Due to a bug in Trainz not completely opaque or transparent areas may overlap each other. You can take a look at the problem and one possible work around by downloading the two related examples from SourceForge.

### Reflection Textures

    These textures are a bit different in usage as the others, because Trainz map them automatically using spherical mapping. How this works you can imagine best if you create a smooth sphere and assign a reflection map. Which map part is shown depend on the direction in which the imaginary ray from the camera to the objects surface would be reflected. That's why you see the whole map on the surface of a smooth sphere.
    To use reflection maps you only need to press button Refl in Map Input panel and button Ref in the Map To panel of the designated texture. You will notice that no colors appear neither in material preview nor in render window. That's because Blender use reflective textures to modify the strength and not the color of reflection. But no fear, in Trainz you get your colors back ;).

### Hardness Textures

    You can assign hardness textures but you will be disappointed. They don't affect hardness, instead they will be typed as reflective texture during export. This behavior is copied from the original exporter, as any attempt to influence the "shinestrength" so far ends in a complete white unlighted object.

### Normal Textures

    A normal texture is used to fake highs and lows on an plain surface. To use it you need an UV Map Input and a Nor Map To. Please take care to use an normal map and not a bump map. Both are used for the same purpose, but they contain different data.

### Texture Combinations

The influence that a texture has on an object's appearance in Trainz is controlled by so-called "material name decorations". With one exception the Blender Exporter for Trainz selects the appropriate decoration depending on the textures you have assigned. This exception is m.billboard, as this material decoration is used for objects always facing the camera. Because the Exporter has no chance to detect if you want this behavior, you have to decorate the material name for yourself with the ending m.billboard. Generally the Exporter doesn't overwrite a known material decoration, so if you want to ensure your material will be exported as m.gloss, then simply append m.gloss for yourself to the material name.

#### List of all currently supported texture combinations

single textures:
* diffuse texture
* reflection texture
* hardness texture (will appear as reflection texture)
double textures:
* diffuse & alpha texture
* diffuse & reflection texture
* diffuse & hardness texture (the same as diffuse & reflection)
* diffuse & normal texture
triple textures:
* diffuse, reflection & alpha texture(in this case the alpha texture affects the reflection texture and not the diffuse texture)
* diffuse, alpha & normal texture(no reflection or hardness texture allowed)
* diffuse, reflection & normal texture (no alpha texture allowed)

## Events

    In case of animation export the original exporters ask you for an event file to bind events to specific frames. To use events with the Blender Exporter for Trainz is similar. Switching a Blender window to Text Editor window and create a new TX object via File > New (Hotkey Alt N). Enter for every event a line with frame number, event type and event name. If you finally rename this TX object to events, then the Exporter will parse this text and create the desired entries in your animation file.

## Examples

    Examples you find as additional files at the download section by SourceForge