Skip to content

Guides

These guides explain how Transport Fever 3 mods are put together. Everything here is taken from files that ship with the game: the Teal type definitions of the engine API, the base game's own scripts and content, the official VS Code template, the campaign mods and the DLC packages. Where the files do not answer a question, the guide says so instead of guessing.

The API reference is generated from the same definition files. The guides link into it whenever a type or function comes up.

How the site is organised

Section Content
Guides (this section) Hand-written explanations with excerpts from the game files
Reference: Engine API api.engine, api.cmd, api.gui, api.res, api.type, api.util, api.modhub, app and the globals from main.d.tl
Reference: Base game scripts Definitions of the base game's Lua/Teal libraries (construction utilities, React GUI framework, mission framework, ...)
Globals A–Z Every global name in one list

The guides in reading order:

  1. Getting started: editor setup with the official VS Code template, where mods are listed in the game, a minimal mod.
  2. Mod structure: mod.json, _metadata/modinfo.json, content/, tealdef/, file paths and the mod script entry points.
  3. Scripting: the GUI and engine states, reading entities and components, changing the game through commands, game scripts and events.
  4. Constructions: .con files, the updateFn result, modules and metaconstructions.
  5. Models and assets: .mdl, .mtl and model metadata.
  6. GUI: the React-style framework the base game GUI is built with, plugins and recipe replacement.
  7. Missions: the mission framework and a walk-through of campaign mission 01.

What a TF3 mod consists of

A mod is a folder with a mod.json and a content/ folder. The game loads models, vehicles, constructions, scripts and the in-game windows from files in content/. The base game itself has the same layout: base/mod.json lists the game settings (map size, town density, costs, ...) as mod parameters and points to ::/base/mod.script for its setup code.

Most content files are Lua scripts that return a table from a data() function. A construction (.con.lua), a model (.mdl), a material (.mtl), a game script (.gs.lua) or a generic resource (.res.lua) all follow this pattern. Behaviour lives in .script.lua or .script.tl files, and content files point at functions inside them with references such as "small_stops.script@updateFn".

Scripts can be written in Lua or in Teal, a typed dialect of Lua. The base game is mostly Teal (.tl): it ships about 640 .tl files and 130 .script.tl files next to plain Lua. The game bundles the Teal compiler (base/content/base/base/tl.lua), and the campaign mods ship .tl sources directly, so Teal files are loaded without a separate build step. The .d.tl files are type definitions only; they are what the VS Code template and this site's reference use.

The script states

The API definitions talk about separate script states. The header of api/tealdef/api/cmd.d.tl names three of them:

The module is available on both the GUI State and the Engine State (and the Console State as well). However, it works in a slightly different manner depending on where it is used from.

State What the definitions say about it
Engine state Runs the simulation. api.cmd commands sent here are executed immediately (api.cmd). Game script functions update, postUpdate and handleEvent run here, judging by how the base game uses them.
GUI state Runs the user interface. Commands are executed in the next simulation step, and the callback is called the frame after. Several api.gui functions are marked "Only available in GUI thread". Game script functions guiUpdate and guiHandleEvent belong here.
Console state Mentioned only in cmd.d.tl. Commands behave as in the GUI state. Nothing else about it is documented in the files.

api.engine gives read-only access to the whole engine state "from both the GUI State and the Engine State" (api/tealdef/api/engine.d.tl). Changes always go through commands. The scripting guide covers this in detail.

Further reading

Two comments in the definitions point to the official wiki for more background:

  • api/tealdef/api/type/mod.d.tl: "Refer to https://wiki.transportfever3.com/doku.php?id=modding:moddefinition for more details about mod and mod interface in general"
  • api/tealdef/api/res.d.tl (getBaseConfig): "See https://wiki.transportfever3.com/doku.php?id=modding:baseconfig for a detailed explanation."

The wiki lives at https://wiki.transportfever3.com.

About the source paths

Excerpts are labelled with their path inside the unpacked game files. api/tealdef/... and base/tealdef/... are the definition folders of the game installation. base/content/..., mods/release/<mod>/... and dlcs/<dlc>/... are content folders. The game ships most content in zip archives; in the unpacked tree each archive became a folder of the same name, which is why paths such as base/content/scripts/scripts/gamescript.d.tl repeat a folder name. The mod structure guide explains the mapping.