Revision as of 00:59, 18 February 2017

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.

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.

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.

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.

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.

Mesh metadata files are in a simple text format similar to the config.txt format. They are not currently validated in any fashion beyond basic readability; if you mis-type a tag it will simply be ignored by the reader.

At the current time, the only use for a mesh metadata file is to specify additional material parameters. A "materials" block is added to the file, and within this you may name any of the materials present within your FBX file. Within each of those, you may specify one of the follow parameters:

• 'two-sided' - A boolean (0 / 1) value which indicates whether chunks which use this material should be rendered as two-sided (no backface culling) or one-sided (regular backface culling).
• 'blend-mode' - A string with one of the following values:
  • 'alpha-blend' - Chunks which use this material are rendered using a true alpha blend.
  • 'alpha-to-coverage' - Chunks which use this material are rendered using alpha-to-coverage. This technique is a fast approximation of alpha which sacrifices some visual detail in favour of performance and depth-independance.
  • 'alpha-masked' - Chunks which use this material are rendered using alpha masking. This technique discards pixels with low diffuse alpha values, resulting in holes in the geometry.
  • 'opaque' - Chunks which use this material are rendered fully opaque.

Mesh Metadata File Example

materials
{
  example0.m.onetex
  {
    two-sided 1
  }
  example1.m.onetex
  {
    two-sided 1
  }
}

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>

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.

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.

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.

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.

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

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.