Developing Simutrans

Now that you have learned how to compile Simutrans, you may be wondering how to introduce modification into the game code.


  • General programming concepts.
  • Knowledge of the C/C++ programming languages. If you are not familiar with those, you may understand some parts of the code but it will be difficult to read/write Simutrans code. So go check some tutorials before continuing.
  • Read the documentation/coding_styles.txtlink-external text if you want to contribute.

You may also want to use a IDE (Integrate Development Enviroment) to help you through the programming process. A popular among some Simutrans developers is Visual Studio Codelink-external, but you can use whatever you feel comfortable with, including a simple text editor.

Getting familiar with the codelink

The first thing to have in mind is that small portions of Simutrans code are still written in German. That is because the original developers (and later the first contributors) were German. Although some efforts have been done to translate the game code, you will still find German text. So, if you find something you don't understand, open your translator as it will be probably a German word.

Simutrans code is subdivided into directories that are self-explanatory. For example, the "music" directory contains music related code, the "gui" directory contains graphical user interface related code, the "network" directory contains code related to network games and so on... Generally, if you want to introduce a change you first search for the directory it may be in, and then search for the file that contains the code you need to change.

Otherwise, if you just want to explore the code, a good way to start if you don't have anything in mind is the main file (simmain.cc in the root directory) which is in charge of starting and exiting the program. Opening this file and looking for the simu_main() function will give you a nice overall view of the program execution process: how it takes the arguments, read options, search for paksets, enable music, etc... Try introducing some changes to this file and compiling the program to see how the behavior of Simutrans changes!

Submitting your changeslink

Once you are done with your modifications, you can submit your changes to the community. On the Simutrans Community we accept contributions from everyone, but that doesn't mean developers will accept your changes instantly. Those will need to be reviewed first.

Make a patchlink

You can make a patch including your code modifications using the diff utility. It is recommended to use svn diff or git diff from the CLI.
Copy to clipboard
#Subversion (default simutrans version system) svn diff >> yourpatch.diff #git (use -U option for unified diff files) git diff -U >> yourpatch.diff

Send your patchlink

Now head to the Patches & Projectslink-external subforum and submit you patch file, including an explanation of why it should be included into the game. After a review by a Simutrans programmer, if everything goes okay it will be submitted on the next revision.

Do NOT submit your changes by opening a pull request on GitHub - that repository is read only!


This is a list of code examples for modifications frequently done. Help expanding it is appreciated.

Reading/Writing parameterslink

The "dataobj" directory is where code related to game parameters is stored. Let's assume first we want to create a new environmental variable "new_parameter" of type "bool" (you can choose also int or string).

1. We first would need to define this new variable in dataobj/enviroment.h
Copy to clipboard
static bool new_parameter;

2. And also give it a default value on dataobj/enviroment.cc
Copy to clipboard
bool env_t::new_parameter = false;

Reading parameters from simuconf.tablink

You can read from simuconf.tab, but you can't write to it. The dataobj/settings.cc file is in charge of reading the simuconf.tab. Navigate to the end of the function settings_t::parse_simuconf() and add the following code:
Copy to clipboard
env_t::new_parameter = contents.get_int( "new_parameter", env_t::straight_way_without_control ) != 0;

That's it, Simutrans will now read this parameter from simuconf.tab (if there is any "new_parameter" parameter in the simuconf.tab).

Reading/writing parameters from/to settings.xmllink

You can both read parameters and write parameters to the settings.xml file (generated to your Simutrans personal directory), at the start and the end of the program respectively. To do so, we have to come back to dataobj/enviroment.cc and add the following code to the env_t__rdwr() function:
Copy to clipboard
if( file->is_version_atleast(122, 2) ) { file->rdwr_bool( new_parameter ); }

The if condition is checking the game version. The first number (122) is the major version, while the second number (2) is the minor version. Game will need to be at least this major or major and minor version to read/write this parameter. Change those accordingly. This is done to maintain compatibility with previous versions of the game.
Now, if you want to test it you will need to increment your game version. You can do so by editing "simversion.h" in the source root directory. If you didn't change the major version, change "SIM_SAVE_MINOR" and "SIM_SERVER_MINOR" (in this case, to 2). Otherwise, change "SIM_VERSION_MAJOR". Do not include this change in your patch.

Reading/writing parameters from/to savefilelink


Removing a deprecated parameterlink

If a parameter is no longer used you may be tempted to remove it. This can be safely done for the simuconf.tab file. However, you can't simply remove a parameter reading from settings and saves, as it is required to maintain compatibility with older versions.

In such a case, you have to check that such parameter will only be read for older versions with is_version_less():
Copy to clipboard
if( file->is_version_atleast(122, 2) && file->is_version_less(123, 2) ) { bool old_parameter = false; file->rdwr_bool( old_parameter ); }

Rate this page:

Contributors to this page: Roboron3042 .
Page last modified on Thursday October 19, 2023 10:01:23 GMT-0000 by Roboron3042.

Page discussion

There are no discussions currently on this page Start discussion

Online Users

6 online users

Newest Forum Posts