This page gives a brief introduction into the used scripting language. See the documentation of resource types for the internal structures of files.

For all scripts and the other external resources which are not hard coded into the game binary, the LUA language is used. LUA is a script language which is used by many programs to offer extendability and customization.

Files with LUA content are plain textfiles and can be edited with any text editor. Common used editors are Notepad++ and Visual Studio Code which both support syntax highlighting of LUA code.

The most common syntax structures used for Transport Fever 2 are described briefly below. A full reference of the LUA syntax is available at the website of LUA.

Functions can be called by their name from other functions or the game engine.

local function functionname(parametername1, parametername2)
  -- code
  return resultname
end

Functions are defined by the keyword function followed by a name for the function. In brackets, some parameters may be required too. Then they can be called inside the function code below. If no parameters are needed, the brackets are left empty. If the function should return a result, the return keyword is used. The end marks the end of the function. All code between function and end belongs to the function.

An exemplaric function call looks like this:

multiply(5, 21)

Variables can be used to temporarily store some values or data structs in code.

--define variable
local variablename
 
--define and write variable
local variablename = -- content
 
--override variable
variablename = -- new content

To define a variable, the keyword local followed by an identifier is used. Transport Fever 2 does not support global variables, thus local is mandatory! A variable can be filled with content by using the keyword = followed by the content. To read content from a variable, simply call the variable by its name.

In many places of Transport Fever 2, data structs are used to store more than single values or key-value paired contents. They are called arrays or tables too.

Most of the configurational data in Transport Fever uses keys for the several properties.

local structname = {
  key1 = value1,
  key2 = value2,
  key3 = value3,
  -- ...
}

These values later can be called by using structname.keyname, e.g. structname.key2. To add a new key at a later point, use structname[key] = value.

In many cases, the storage of a list of similar contents is needed.

local array = { value1, value2, value3 }

These values later can be called by using an index number. In most cases, these structs are one-indexed, meaning the first index is 1. The total number of values can be gathered by using #variablename. In the above example, #array would return 3 and the indices 1,2 or 3 could be used.

There are several solutions for looping code. The two common ones are while- and for-loops.

A while loop checks a condition and loops as long as the condition returns true

while condition do --condition could be something like #result < 10
  -- looped code
end

A for loop has an index that counts the number of loop runs. It's exit condition is determined by comparing the index to an end value

for i = startvalue, endvalue, stepwidth do
  -- looped code
end

The index starts with the startvalue and is modified by stepwidth every time it finishes a loop run. if stepwidth is omitted, the step is 1. As soon as the index is greater or equal to the endvalue, no new loop runs are started.

To iterate over all key-value pairs in a table, it is possible to use the pairs function:

for k,v in pairs(t) do 
  -- looped code
end

In the looped code, the key can be used with k and the value can be used with v.

To skip some code under certain circumstances, conditionals are used.

if condition then
  -- some code
elseif othercondition then
  -- some other code
else
  -- some default code
end

If the condition applies, some code is executed. Otherwise optional other conditions are checked. If no condition applies, optionally the default code applies. Otherwise the execution jumps below the end.

The most common data types in Transport Fever 2 are:

local stringvariable = 'this is a string' -- any text surrounded by ' or "
local booleanvariable = true -- or false (equal 1 or 0)
local integervariable = 123 -- any number without commata
local floatvariable = 1.25 -- any number with fractions of 1, be aware that . is used!

In conditions as well as in some codes, operators are used for mathematical operations or compares. There are several other operators as well.

• + for addition
• - for subtraction
• * for multiplication
• / for division
• % for modulo
• ^ for exponentiation

• == equal
• != not equal
• ~= not equal
• < less
• > greater
• ⇐ less or equal
• >= greator or equal

• and
• or

• .. to combine strings: “string a ” .. “string b” results in “string a string b”

Some files use functions from other script files. These can be imported:

-- import
local scriptvariablename = require "scriptname" -- scriptname without fileextension!
 
-- use
scriptvariablename.functionname(parameter)

The imported scripts are expected to be in res/scripts. If they are in a subfolder like res/scripts/terrain, this subfolder has to be added to the scriptname:

-- import
local scriptvariablename2 = require "subfolder/scriptname" -- scriptname without fileextension!