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