FBX file format

From TrainzOnline
(Difference between revisions)
Jump to: navigation, search
m
Line 24: Line 24:
 
* 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 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.
 
* 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.
 +
 +
 +
== 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. 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.
  
  

Revision as of 12:51, 7 November 2016

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.

Contents

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:

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.


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


Submit

As the asset is submitted into the Trainz Asset Database, Content Manager will import the FBX 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) 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" 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.


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.

Personal tools