User Tools

Site Tools


modding:developerinfo:scripting

Scripting

Overview

The main file of every mod is mod.lua. This file contains the mod's metadata as well as the functions that are executed when the game is initialized.

The file has the following format (also see Directory structure):

function data()
return {
  -- metadata
  info = {
     -- as described in Directory structure
  },
 
  -- options to show in the advanced game settings menu (optional)
  options = {
    -- format: category = { list of key/name pairs }
    terrain = { { "test1", _("Test entry 1") }, { "test2", _("Test entry 2") } },
  },
 
  -- main function
  runFn = function (settings)
 
    -- put your code here!
 
  end,
 
  -- returns whether active or not (only needed for DLCs)
  checkActiveFn = function (settings)
    return true
  end
}
end

The basic process is as follows: the options from all active mods are collected and presented to the user. The user can then select an entry in each category. When the game starts, this configuration (table/dictionary) is passed to the function runFn (parameter settings) which can then act accordingly. The initial set of options (and the base run function) is defined in res\config\base_mod.lua.

The main script code goes into the function runFn. There are multiple ways how a mod can do its work:

  • Config variables: the game configuration can be changed directly by setting the appropriate values in the configuration table.
  • File filter: a function that is invoked for all files in a directory. The function can then decide whether the file should be included or not. The file filter can access the data in the file, making it a very versatile tool.
  • Modifier: a function that is invoked after a resource file has been loaded. It is used for modifying the data on the fly.

Config variables

The configuration variables are accessible via the global game.config table. The initial configuration is defined in the file res\config\base_config.lua which is a good place to look up possible variables (to change) and their default value.

Examples

Modify terrain tool costs:
game.config.costs.terrainRaise = 5.0

Add cargo type:
table.insert(game.config.cargotypes, { id = “MAIL”, name = _(“Mail”) })

Change terrain/vegetation property:
game.config.terrain.vegetation.treeLine = 400.0

File filters

File filters filter the content of a directory, i.e. they define which files are visible to the game. Mods can install as many file filters as needed, and multiple file filters per category can be specified (to form a filter chain).

The following code installs a filter for vehicles which removes all non-steam-locomotives from the game.

local function myFilter(fileName, data)
  if data.metadata.railVehicle and data.metadata.railVehicle.engines and
      #data.metadata.railVehicle.engines == 1 and data.metadata.railVehicle.engines[1].type ~= "STEAM" then
    return false
  end
  return true
end
 
addFileFilter("model/vehicle", myFilter)

File filters can be specified for the following categories:

  • model/vehicle
  • model/tree
  • model/industry
  • model/other
  • multipleUnit
  • street
  • track
  • bridge
  • tunnel
  • railroadCrossing
  • construction
  • autoGroundTex

Modifiers

Modifier functions allow to modify resources on the fly at the time they’re loaded. This is useful to edit the same value in multiple files; in fact, it’s much more convenient than copying and editing all affected files by hand. Furthermore, multiple modifiers can be added by different mods without one mod overriding the files of the other.

For example, the following modifier function sets the top speed of all rail vehicles to 125%:

local function myModifier(fileName, data)
  if data.metadata.railVehicle then
    data.metadata.railVehicle.topSpeed = 1.25 * data.metadata.railVehicle.topSpeed
  end
 
  return data
end
 
addModifier("loadModel", myModifier)

Modifiers can be defined for the following catgories:

  • loadModel
  • loadMultipleUnit
  • loadStreet
  • loadTrack
  • loadBridge
  • loadTunnel
  • loadRailroadCrossing
  • loadConstruction
  • loadSoundSet
modding/developerinfo/scripting.txt · Last modified: 2019/03/19 10:18 (external edit)