Table of Contents

Mod Components

Mods are folders with a specific file hierarchy: 

  mods/
    urbangames_sample_mod_1         (1)
      config/                       (2) (optional)
        ...
      documents/                    (3) (optional)
        ...
      res/                          (4) (optional)
        ...
      mod.lua                       (5)
      image_00.tga                  (6) (optional)
      strings.lua                   (7) (optional)
      workshop_preview.jpg          (8) (optional)
      filesystem.lua                (9) (optional)
  1. The directory name has the form <id>_<major_version>. The ID should be as specific as possible, so it should definitely contain the author’s name (or organization) and the mod name. The major version number is an integer starting at one.
  2. Optionally contains mod-related config files (Lua files). These files can be “required” from other Lua files, i.e. the config directory is added to Lua’s package.path list.
  3. Contains user documentation like manuals or read-me files. This directory is ignored by the game.
  4. Most content (like models, textures etc.) goes into this directory. Everything in here can be thought of as if it had been copied (with overwrite) to the base res/ folder.
  5. The main file, contains metadata (like name, description etc.) and script code. See below for more information.
  6. An image of 320×180 pixels, shown in the game. It is scaled depending on the UI scale level.
  7. Contains translations of the mod’s texts. See below for further information.
  8. An image, shown in Steam workshop, when the mod is published.
  9. Defines files and directories to be removed/hidden from the game. See below for more information.

Major Versions
Different versions of the same mod are independent of each other, but when starting a new game, only the latest version is shown to the user.

mod.lua

The basic structure of the file is as follows. 

function data()
return {
  info = {
    name = _("Sample mod"),         
    description = _("modDesc"),
    authors = {
      {
        name = "Urban Games",
 	role = 'CREATOR',
      },
    },
    minorVersion = 0,              
    severityAdd = "WARNING",       
    severityRemove = "CRITICAL",   
    params = { ... },     
    url = "https://...",         
  },
  -- runFn = function (settings, modParams) ...
  -- postRunFn = function (settings, params) ...
}
end

The info block contains the basic informations about mods:

The _(“text”) indicates that the text will be translated (see strings.lua below).

See the scripting basics to find out more about the script functions that can be provided in the mod.lua.

A small demo mod was provided in the game release notes once the mod parameter feature was introduced. You can download it here too.

strings.lua

function data()
return {
  en = {
    modDesc = "This is a sample mod.",
  },
  de = {
    ["Sample mod"] = "Beispiel-Mod",
    modDesc = "Dies ist eine Beispiel-Mod.",
  }
}
end

This file contains translations for strings, specified as a list of key/value pairs for each language. If a key does not exist for a given language, the English text is used. If this isn’t defined neither, the key itself is displayed. For a list of possible language codes, see the directory res/strings/ and have a look at the information on localization.

filesystem.lua

function data()
return {
  hiddenDirs = {
    "res/models/model/vehicle/truck/"
  },
  hiddenFiles = {
    "res/models/model/vehicle/train/borsig_1860.mdl",
    "res/models/model/vehicle/train/br75_4.mdl"
  }
}
end

Allows to specify files and directories that are to be hidden from the game, i.e. it has the same effect as deleting the file(s).

A soft way of filtering resources is to use a file filter.

Resource Structure

The directory structure in mods is similar to the one from the Transport Fever 2 game resources. Below is a description of all relevant folders located below the res-folder. Only those which are relevant for a specific mod need to be included in a mod.

If additional resources should be added by a mod, the file names should not match existing file names. If existing resources (from game or other mods) should be overriden by a mod, the directory structure and file names have to be exactly replicated. The load order of mods depends, which files are used. The last one overrides the others.

Thus it is recommended not to override existing files whenever it is possible to preserve compatibility to other mods!


Resource Types

Publish a Mod