Material sharing

From TrainzOnline
Jump to: navigation, search

Each render chunk in a mesh file references a single material. It is beneficial for performance reasons to reduce the number of materials in use. To this end, it is possible to share a single material between multiple render chunks within a single asset.



Material sharing operates within mesh files stored in a single asset. None of the techniques described here operate across mesh files stored in separate assets. The location of the files is the important point, not the asset which eventually uses the meshes.

Each material within the asset has a unique name defined by the content creator in their 3D modelling software. If the exact same material name is used multiple times, Trainz will consider these to be references to a single material rather than multiple separate materials. The first time a given material name is encountered when loading from a given asset, the material data is loaded into a new material instance. On subsequent encounters, the already-loaded material instance is referenced and the material data stored in the mesh file is ignored.

Performance Benefits

There are numerous benefits to material sharing. Some are important to understand, while others just work in the background to give minor speed boosts. The major benefits include:

  • Mesh stitching can only occur between render chunks using a single material. While a single render chunk from a single mesh file can always be stitched between multiple instances of that mesh file, material sharing allows you to induce stitching between multiple render chunks from multiple mesh files. Please note that material sharing removes a barrier which prevents mesh stitching from operating to its full capacity, but it does not force mesh stitching to activate; other barriers may also exists. You should review the requirements for mesh stitching and undertake in-game testing of your asset to ensure that your expected level of mesh stitching is actually occurring in practice.
  • Texture atlas techniques tend to rely heavily on mesh stitching and thus you must correctly share materials for these techniques to work as expected.
  • If multiple render chunks within a single mesh file use the same material, certain import-time mesh optimisations may be possible, resulting in a higher-performing mesh. This can effectively reduce the number of render chunks in the imported mesh, which in turn reduces the number of draw calls required to render the mesh.
  • In instances where mesh stitching is not available, E2's internal render chunk sorting may allow more optimal use of the GPU by reducing the number of state changes required to perform a given number of draw calls.
  • Material sharing does NOT allow hardware instancing. Hardware instancing requires that multiple instances of the same meshes are used.

Shared Parameters

The asset-unique material name defines sharing. Within a named material, ALL material parameters are shared. This includes:

  • Material type.
  • Texture slot bindings.
  • Lighting settings (such as specular power, emissive color, ambient color, etc.)
  • Overrides set in the mesh metadata file.


It is possible for the content creator to activate material sharing by using the exact same material name in multiple meshes of a single asset, when the materials in the mesh files are in fact configured differently. This may happen either deliberately (ie. wanting to activate material sharing) or accidentally (ie. by exporting a given scene, making material changes, then exporting again, and using both resultant meshes). In either case, this is very problematic because the in-game rendering will (1) not match the settings in the mesh files, and (2) vary depending on which mesh is loaded first, which isn't strongly defined.

The current version of Trainz will typically diagnose this problem and report VE186.

Personal tools