modding:developerinfo:scripting
Differences
This shows you the differences between two versions of the page.
|
modding:developerinfo:scripting [2019/03/19 10:18] |
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)
Page Tools
