Latest revision as of 16:09, 14 January 2021

The FBX file format is a proprietary file format owned by Autodesk, Inc. but used as a common interchange format for many products. As of trainz-build 4.5, Trainz uses FBX as a mesh import format.

[edit] Creating an FBX File

FBX files are typically created in modelling software such as Autodesk's 3DS Max, or the Blender Foundation's Blender. Export instructions for these software packages can be found here:

• HowTo/Export from 3DS Max using FBX
• HowTo/Export from Blender using FBX

While it is likely possible to create FBX files from a wide range of other software, we cannot guarantee that all software is capable of producing Trainz-compatible FBX files. The more that a given software is commonly used to produce in-game models in FBX format for other games, the more likely it will also work with Trainz.

[edit] Importing from FBX

No separate "import" step is required to source a Trainz mesh from FBX format. Content Manager will perform the necessary conversions when importing an asset.

[edit] Asset Configuration

The following configuration is used to import from FBX format:

• The config.txt file must specify a trainz-build version of 4.5 or higher.
• The mesh reference in the config.txt file (for example, in the "mesh-table" container) must use a "*.trainzmesh" file extension.
• If the FBX file contains animation tracks, the anim reference in the config.txt file should be named "<mesh-file-name>_<animation-track-name>.kin".
• The FBX file must be placed within the asset folder at the indicated location, but with a "*.FBX" file extension.
• If the FBX file references textures, an image file (eg. "*.tga") or a texture resource (eg. "*.texture.txt") with a matching file name must be present in the same folder as the FBX file.
• If the FBX file contains animation tracks, an animation event file may be present in the same folder as the FBX file. This should be named "<mesh-file-name>_<animation-track-name>.evt". This is not mandatory.

[edit] Mesh Metadata Files

Various attributes which users may wish to control are frequently not available in standard modelling packages, or are not exported to the FBX file format. An optional "<mesh-file-name>.txt" file may be included alongside the "<mesh-file-name>.fbx" file to convey these attributes. Where attributes are specified in this metadata file, they override any entries read from the FBX file itself. If an attribute is not specified, it is calculated from the FBX file.

See the mesh metadata file page for full details.

[edit] Animation Event Files

Animation event files are simple hand-created ASCII text files which provide additional sequencing data used to synchronise scripted behaviour with animation playback. They use the file extension "*.evt". Each line of the text file should contain three items separated by whitespace. The items are as follows:

<frame-number> <event-type> <event-name>

For example, if the FBX came from Blender and was called:

doors.fbx

the "*.evt" should be labeled

doors_scene.evt

Since Content Manager will create a *.kin file called:

doors_scene.kin

The frame number is a zero-based frame index. Animations are typically exported at 30fps, which means that 0 is the very start of the animation, 30 is one second into the animation, and so on. Events should be in ascending frame order. Frames must be in the form of three digits. For instance, if an event wanted to be triggered at frame 2, then it must be typed as 002

Event type must always be "Generic_Event" (without the quotes).

The event name is a word comprised of printable ASCII characters (not including whitespace or line break).

As the animation is played back within Trainz, each event sends a script message to the MeshObject with the major type "Animation-Event" and the minor type equal to the event name.

Please note that animation event files are processed by the mesh importer and the results are included into the Trainz animation file (*.kin). The game proper never uses "*.evt" files.

An example "*.evt" could look like this:

001 Generic_Event door_start
002 Generic_Event door_sealing
007 Generic_Event door_beeping

If everything is labeled properly, Content Manager should find the event and report it in the log while submitting the Asset. It will display how many events were found in each event file.

[edit] Submit

As the asset is submitted into the Trainz Asset Database, Content Manager will import the FBX, TXT and EVT files, and create a number of matching Trainz-specific files:

• A mesh file is created with the name "<mesh-file-name>.trainzmesh". Any existing file at this path is overwritten.
• One animation file is created per animation track, named as "<mesh-file-name>_<animation-track-name>.kin". Any existing files at these paths are overwritten.
• If necessary, "*.texture.txt" files are created for each source image. Existing files are not overwritten. It is likely that you will want to hand-customise the auto-generated files to configure alpha behaviour or etc.

[edit] Deleting Source Files

The source files (FBX, EVT, TXT) are not deleted in this process, however you may choose to delete them once the imports have been completed. Trainz will accept files in "*.trainzmesh" and "*.kin" format without requiring any equivalent "*.fbx", "*.txt" or "*.evt" files. You may alternatively leave the source files in place so that other users can load your source mesh directly into their own modelling package.

[edit] Renaming Binary Files

"*.trainzmesh" files and "*.kin" files may optionally be renamed after the initial import once the creating "*.fbx" has been removed- there is no point in renaming binary files while the source "*.fbx" file is still present, as the binary files will simply be re-exported with the original name. When renaming binary files, be sure to update any config.txt references appropriately. This technique can be used to create multiple "*.kin" files which all apply to a single mesh (ie. by importing several *.trainzmesh and *.kin pairs with effectively identical meshes but different animations, then discarding the duplicate meshes).

[edit] Open Source

Trainz reads FBX files courtesy of the ASSIMP BSD-licensed mesh importer. This product supports both "text" and "binary" FBX formats, but we recommend using binary format where possible. Our version of ASSIMP includes a small number of modifications to improve the robustness of the importer and compatibility with typical Trainz meshes. While the ASSIMP importer library does support a number of other formats beyond FBX, we do not offer this capability in Trainz at the current time.

[edit] Trouble Shooting

[edit] 3DS MAX

[edit] Channel Maps

Sometimes 3DS Max likes to add extra map channels without you realising, and FBX will most likely report an error such as "Error, T13316:FBX: ignoring binormal layer" or "Unable to determine vertex format".

You can remove the extras by:

1) Select mesh

2) Open 'utilities' tab in max

3) Click on 'more...'

4) Click on 'Channel Info'

5) Click on 'Channel Info' button

6) You'll see a list of ID/s etc. There will be a line marked '1:map" in the ID column, and another marked "2:map". Both will have the UVW channel in the 'channel name' column.

7) Select the '1:map' line and click on 'Name' at the top, and enter '-none-' and click ok

8) Select '2:map' and click on 'clear' at the top

Now try exporting.

[edit] Mesh / Bone Scale

Another one to check is your mesh scale. If any of your meshes are scaled to something other than 100% (X:100, Y:100, Z:100) your mesh is likely to look incorrect or animate incorrectly. Check all bones and meshes to make sure they are 100% scale.

[edit] Displacement Slot

When you render your scene with a pbrmetaldetail material and forget about the displacement slot, strange results will arise. Don't forget your displacement slot!

[edit] Bogey Animations

You must name your animation "anim.kin" in your bogey asset. You can leave the anim tag out of your config.txt as the anim.kin file is what the bogeys use.

[edit] Blender

[edit] FBX Format

There are several Blender addon FBX exporters however the default version supplied with Blender is known to work. Blender 2.8 and later only have the binary export version. Earlier versions of Blender had the plain text option. You should use the binary export format.

[edit] UV Maps

Blender, by default, creates a UV map for each new mesh. This is usually called "UVMap" although the name itself is not important. Before exporting make sure you only have one UV map as multiple maps may cause issues including a VE258 error. UV maps can be found in the Properties panel, object data properties section.

[edit] Warnings and Errors

We will be updating this section with more information as we continue testing the new systems.

• Warn, T13272: FBX-DOM (TOK_KEY, offset 0x14d27) source object for connection does not exist
• Error, T13272: FBX: length of input data unexpected for ByPolygon mapping: 2586, expected 2463
• Error, T17344: Failed to triangulate polygon (no ear found). Probably not a simple polygon?
  • Cause: probably a malformed mesh as a result of mesh reduction. Can be hard to find.

To fix these errors, check your UV and channel maps then re-export.