modding:developerinfo:scripting

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

modding:developerinfo:scripting [2019/03/19 10:18] (current)
Line 1: Line 1:
 +====== 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 [[:​modding:​developerinfo:​directorystructure|Directory structure]]):​
 +
 +<code lua>
 +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
 +</​code>​
 +
 +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.
 +
 +<code lua>
 +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)
 +</​code>​
 +
 +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%:
 +
 +<code lua>
 +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)
 +</​code>​
 +
 +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)