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.

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:

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

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.

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.

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.

• 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
  • auto_ground_tex: configurations of ground textures applied around landscape assets (trees and rocks)
  • bridge: configurations of rail and road bridges
  • cargo_types: configurations of cargo types
  • climate: configurations of climates
  • construction_sound: configuration of sound effects
  • environment: configurations of environments
  • game_script: game script files used by mission scripts (and mods)
  • grass: configurations of grass and other small plants visible on some terrain materials
  • ground_texture: configurations of ground textures, e.g. around constructions
  • multiple_unit: configurations of multiple units
  • name2: lists of people, street and town names
  • railroad_crossing: configurations of railroad crossings
  • sound_set: configurations of sound sets
  • street: configurations of streets
  • style_sheet: configurations of various user interface elements
  • terrain_generators: configuration scripts of the terrain generation and asset distribution, e.g. forests
  • terrain_heightmaps: heightmap templates for brush tool
  • terrain_materials: configurations of terrain materials used by terrain generation as well as brush tools
  • track: configurations of tracks
  • traffic_light: configurations of traffic lights
  • tunnel: configurations of rail and road tunnels
  • ui: configurations of common categories in construction menus

• construction:
  • asset: asset constructions for mainly decorative elements
  • building: building constructions for town buildings built by the game
  • depot: constructions for street, tram or rail depots
  • industry: constructions for industries
  • placeholders: placeholder constructions for the fallback mechanism
  • station: station constructions for all types of transport
  • street: street constructions e.g. roundabouts
  • waterway: water constructions e.g. buoys

• fonts: font types used by the game

• models: all 3D resource files like models, meshes, materials and animations.

• scripts: generic scripts used in various places
  • mission: script files used by missions
  • modules: script files used by modular constructions
  • terrain: script files for the terrain generation and asset distribution, e.g. forests

• 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