Latest revision as of 14:18, 10 June 2024

The Mesh metadata file allows content creators to control various mesh and material attributes which may not be available in standard modelling packages, or are not exported to the FBX file format.

It exists as an optional "<mesh-file-name>.txt" file included alongside the "<mesh-file-name>.fbx" file. 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.

[edit] Validation

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.

[edit] 'materials' array

materials
{
  material_name_a
  {
    ..
  }
  material_name_b
  {
    ..
  }
}

The "materials" array allows the creator to override attributes of the various materials present within the FBX file. Only the specified materials and attributes are overridden, all other materials and attributes are configured in the normal fashion. Each element in the array must be named exactly as per a single material in the FBX file, including any name suffixes.

Each material may be configured with the following attributes:

[edit] two-sided

two-sided 0

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

[edit] blend-mode

blend-mode opaque

The 'blend-mode' tag supports the following values:

• • 'alpha-blend' - Chunks which use this material are rendered using a true alpha blend. Due to technical limitations, render ordering of overlapping alpha-blend materials may be incorrect. This is not considered a bug; it is the creator's responsibility to avoid this becoming problematic.
  • '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.

[edit] material-type

material-type onetex

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.

[edit] textures

textures
{
  albedo
  {
    texture-resource "my-albedo.texture"
  }
  normal
  {
    texture-resource "my-normal.texture"
  }
}

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 for the parent material; a partial override is not supported. The following subtags are accepted within each texture container:

[edit] texture-resource

A string which 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 texture files must be present within the same asset as the mesh. The resource name may include sub-folder or parent-folder path prefixes, which are resolved relative to the folder containing the metadata file.

[edit] bend-normals-upward-ratio

bend-normals-upward-ratio 0.0

The 'bend-normals-upward-ratio' tag allows the input normals to be reoriented towards the sky.

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. As Trainz is Z-up, "directly upward" means (0.0, 0.0, 1.0).

Supported in content format v4.8 and later.

[edit] clutter-wind-type

clutter-wind-type none

This tag only applies to materials of type m.foliage. Supported values are "none" (default), "vertex-color", and "position-z". The details of this attribute can be found here.

Supported in content format v5.4 and later.

[edit] clutter-sample-method

clutter-sample-method origin

This only applies pertains to materials of type m.foliage. Supported values are "origin" (default), "node-origin", "per-vertex", and "contiguous-geometry". The details of this attribute can be found here.

Supported in content format v5.4 and later.

[edit] clutter-geometry-root

clutter-geometry-root bottom

This only applies pertains to materials of type m.foliage. Supported values are "bottom" (default), "top", and "center". The details of this attribute can be found here.

Supported in content format v5.4 and later.

[edit] fadeInEndDistance

fadeInEndDistance 0.0

This only applies pertains to materials of type m.foliage and m.clutter. This defines the fade-in distance for materials of this chunk. Below this distance, chunks of this material are fully transparent and thus invisible (but still rendered; this is not a performance optimisation). Beyond this distance, the chunks start to become opaque.

This is typically used in conjunction with Mesh-table LOD to allow cross-fading between clutter LODs. The LOD transitions offer performance gains, while the cross-fading pays a small performance penalty but reduces potentially jarring visuals.

[edit] fadeOutEndDistance

fadeOutEndDistance 200.0

This only applies pertains to materials of type m.foliage and m.clutter. This defines the fade-out distance for materials of this chunk. Beyond this distance, chunks of this material are fully transparent and thus invisible (but still rendered; this is not a performance optimisation). Below this distance, the chunks start to become opaque.

This is typically used in conjunction with Mesh-table LOD to allow cross-fading between clutter LODs. The LOD transitions offer performance gains, while the cross-fading pays a small performance penalty but reduces potentially jarring visuals.

[edit] detail-scale

detail-scale 0.09

This only applies pertains to materials of type m.pbrmetaldetail. This controls the scaling ratio between the regular texture and the detail texture. The tag has a minimum value of 0.001.

[edit] diffuse-color

diffuse-color 1.0, 1.0, 1.0, 1.0

The 'diffuse-color' tag allows the RGBA diffuse color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support a diffuse color input.

[edit] emissive-color

emissive-color 0.0, 0.0, 0.0, 0.0

The 'emissive-color' tag allows the RGBA emissive color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support an emissive color input.

[edit] specular-color

specular-color 1.0, 1.0, 1.0, 1.0

The 'specular-color' tag allows the RGBA specular color of the material to be overridden. The standard RGB color range is between 0.0 and 1.0, but higher (HDR) numbers are permitted. This does not add a new capability to the material; it is ignored where the material does not support a specular color input.

[edit] specular-power

specular-power 10.0

The 'specular-power' tag allows the specular power of the material to be overridden. The value must be between 10.0 and 128.0 inclusive. This does not add a new capability to the material; it is ignored where the material does not support a specular power input.

[edit] rotate-mesh

 rotate-mesh 90, 0, 0

The 'rotate-mesh' tag allows the entire input mesh to be rotated on import. This is useful in cases where the orientation of the mesh is incorrect, but the FBX file cannot be regenerated or cannot easily be rotated in the modeller application. The three parameters describe an Euler rotation (roll, pitch, yaw) expressed in degrees.

[edit] 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
  }
}