Resource Types & Structure

In Transport Fever 3, the game resources are not distinguished by their folder, but by their individual file endings.

The game resources as well as the mod resources consist of code files (scripts, configurations, …), 3D files, texture files and soundfiles. The following table contains an overview over all used file endings in Transport Fever 3. Below are additional infos for the most common ones.

To reference another file, it is possible to either reference relative to the current file or absolute from the base game content directory or the root of a mod:

"/assets/<...>/filename.mdl" -- absolute path
"tex/logo_mga.dds" -- path relative to current file

To reference files in another mod than the current one or from the base game, the whole path is prefixed:

"/assets/<...>/filename.mdl" -- absolute path in the current mod
"::/assets/<...>/filename.mdl" -- absolute path in the base game
"mod_id::/assets/<...>/filename.mdl" -- absolute path in mod ''mod_id''
 
"tex/logo_mga.dds" -- path relative to current file in the current mod
"::tex/logo_mga.dds" -- path relative to current file but in the folders of the base game
"mod_id::tex/logo_mga.dds" -- path relative to current file but in the folders of the mod ''mod_id''

In general, the lua and Teal based static resources consist at least of the data() function that is executed once when the game loads all the resources at the start of a savegame:

function data()
return {
  -- content of data struct depending on type of configuration
}
end

Beside the static metadata file, many of the resources like constructions have a dynamic script part. The static resource file has a reference to the script file like in the following example:

...
updateScript = {
  fileName = "underground_station.script@updateFn",
  params = {
    key = value,
  }
},

The fileName follows the pattern: resourceRef@functionKey where resourceRef may be a full path as described above. The functionKey refers to a key in the result of the data() function in that script file.

The params struct is injected as the first parameter into these referenced functions and is commonly called captureParams:

function data()
return {
  updateFn = function(captureParams, params)
    ...
  end,
  ...
}
end

The model resources consist of the following file types:

• .mdl for model definitions
• .msh for mesh index files
• .msh.blob for mesh 3D data
• .mtl for material definitions
• .ani for extracted animations

Model files are a special kind of configuration file as well, thus their structure is similar with a data()-function.

function data()
return {
  boundingInfo = { ... }, -- optional bounding box used e.g. for render borders
  collider = { ... },     -- optional collider for collision calculation
  lods = { ... },         -- geometric information for 3D data and textures
  metadata = { ... },     -- metadata depending on model type
  version = 2,            -- required to distinguish from the old Transport Fever 2 model format
}
end

Detailed information about bounding boxes, colliders and the lod tree can be found in the model documentation.

The mesh files contain the threedimensional mesh information known as the actual 3D model. A mesh can consist of more than one submesh. This data is stored in a binary blob file that contains all the positions, orientations etc. of every vertex, edge and face. To tell the engine where the right information is stored in the binary blob file, there is a second file with indices. This text based file can be edited with any text editor.

function data()
return {
  subMeshes = { ... },
  vertexAttr = { ... },
}
end

Both files share the same name, but the blob file has .blob as a suffix. For example, if the index file is called cube_lod_0.msh, then the blob file is called cube_lod_0.msh.blob. Read more about meshes and the internal structure of these files in the mesh documentation.

Materials contain the reference to texture files. The basic structure is a data() function as well.

function data()
return {
  order = 0, -- used to determine rendering order between materials of same type
  params = { ... }, -- parameters vary depending on type
  type = "PHYSICAL_NRML_MAP",
}
end

There are many different material types available. For a full overview of available types, see the material documentation.

If animations are extracted from .mdl files to external files, they are located in .ani files.

These files contain a data() function as most of the other resources:

function data()
return {
  times = { 0, ... }, -- timestamps in milliseconds from 0 as begin of animation 
  transfs = {
    { 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, }, -- transformation matrix for each timestamp
    ...
  },
}
end

The number of timestamps must equal the number of matrices!

The preferred texture format for Transport Fever 3 is .dds with compression and mip maps. In some rare cases and for ui elements the .tga format is files and compressed .dds files.

The .dds textures are compressed and have a smaller filesize, reducing the memory usage.

The common compression types supported by Transport Fever 3 are:

• BC1/DXT1 with binary alpha information
• BC2/DXT3 with 4bit alpha
• BC3/DXT5 with interpolated alpha
• BC7/DX11 with interpolated alpha
• BC5/3Dc for normal maps
• BC4/R8/L8 for m8 bit greyscale masks

While DXT1 has the smallest file size, it is only suitable where no transparency or full transparency (either 100% opaque or 100% transparent) is needed.

For normalmaps, the 3Dc ATI2A2XY standard is required. See external tools documentation for more information on tools supporting these compressions.

.tga files usually are used for UI elements and smaller graphics. To provide graphics with high resolution for 4k-monitors, the ui icons usually are provided in double scale, meaning a 24 px large icon is actually 48 px large in the file. The file name ends with @2x.tga in that case.

While in most cases there is no mandatory directory structure for mods, it is recommended to use a similar directory structure as used in the base game of Transport Fever 3. Below is a description of all relevant folders inside of the content directory of Transport Fever 3. Only those which are relevant for a specific mod need to be included in a mod.

The directories in Transport Fever 3 are grouped by game element, not by filetype. Thus the folders contain 3D models, sounds and additional script files all in one place: