Mesh metadata file

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. Do not rely on this behaviour- we may add validation in the future and it may apply retroactively.

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 following 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.
• 'material-type' - A string which specifies the material type to use. This causes the game to ignore any material type suffix on the material name. Be careful when overriding material types in this manner, as other requirements (such as texture slot bindings) may vary between material types. The material type string does not include a leading "m." - so "notex" is a valid entry here, but "m.notex" is not.
• 'textures' - A subcontainer list with zero or more texture containers. Each texture container is named for the material texture slot to which the texture is to be assigned ("albedo", "normal", "parameter", "detail-albedo" or "detail-normal"). If this list is present at all, it overrides ALL automatic texture assignment from the FBX file; a partial override is not supported. The following subtags are accepted within each texture container:
  • 'texture-resource' - A string within the provides the texture resource name (eg. "foo.texture"). As always, texture resource names are equivalent to texture.txt file names without the trailing ".txt". The resource name may include sub-folder or parent-folder path prefixes, which are resolved relative to the folder containing the metadata file.
• 'bend-normals-upward-ratio' - The default value (0.0) will not modify the mesh normals imported from FBX. The maximal value (1.0) will force the normals to point directly upward. Mid-range values may be used, although care should be taken with normals which are pointing straight downward to start with. This is supported from v4.7 and will be ignored in any prior version. As Trainz is Z-up, "directly upward" means (0.0, 0.0, 1.0).

Mesh Metadata File Example

materials
{
  example0
  {
    two-sided 1
    material-type "pbrmetal"
    bend-normals-upward-ratio 0.0
    textures
    {
      albedo
      {
        texture-resource "albedo.texture"
      }
      normal
      {
        texture-resource "normal.texture"
      }
      parameter
      {
        texture-resource "parameter.texture"
      }
    }
  }
  example1.m.onetex
  {
    two-sided 1
  }
}