User Tools

Site Tools

Urban Games


Mod Components

Mods are folders with a specific file hierarchy:

    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.


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

The info block contains the basic informations about mods:

  • name is the mod name that is visible in mod lists and mod details.
  • description is the mod description that is visible in the mod details section.
  • authors is a block containing the authors of the mod and their roles.
  • minorVersion is the minor version. It is shown behind the mod name in lists and details when greater than 0.
  • severityAdd defines what kind of warning to show when the mod is added to an existing savegame. Can be NONE, WARNING, or CRITICAL.
  • severityRemove defines what kind of warning to show when the mod is removed from an existing savegame. Can be NONE, WARNING, or CRITICAL.
  • params is a block with custom mod parameters analogue to construction parameters. They can be used in runFn by calling modParams[getCurrentModId()].
  • url is a link to a website where the mod can be found for manual download. It is necessary to include the “https” prefix.

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.


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

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.


function data()
return {
  hiddenDirs = {
  hiddenFiles = {

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!

  • audio
    • effects: sound files for sound effects and sound sets of vehicles and industries
    • music: music tracks for the background music
  • campaign: the savegames used for starting the missions of the campaigns and the config for bonus medals in missions
  • config: the base config files used by the game
  • fonts: font types used by the game
  • shaders2: script files for the shaders used by the game engine
  • strings: texts for the languages supported by the base game (see localizations for information about custom translations of game texts)
  • textures: default neutral textures
    • environment: textures used by the environment, e.g. the skybox
    • ground_texture: textures used for ground textures, e.g. around constructions
    • models: textures used for most of the 3D models, e.g. vehicles, buildings and assets
    • streets: textures used for streets
    • terrain: textures used for terrain materials and grass plants
    • tracks: textures used for rails and sleepers of tracks
    • trees: textures used by trees
    • ui: icons and preview images for the user interface and menus as well as construction parameter image buttons

modding/modcomponents.txt · Last modified: 2022/04/06 18:03 by yoshi