Inhaltsverzeichnis
- <a href='#Prerrequisites' class='link'>Prerrequisites</a>
- <a href='#Getting_familiar_with_the_code' class='link'>Getting familiar with the code</a>
- <a href='#Submitting_your_changes' class='link'>Submitting your changes</a>
- <a href='#Make_a_patch' class='link'>Make a patch</a>
- <a href='#Send_your_patch' class='link'>Send your patch</a>
- <a href='#Examples' class='link'>Examples</a>
- <a href='#Reading_Writing_parameters' class='link'>Reading/Writing parameters</a>
- <a href='#Reading_parameters_from_simuconf.tab' class='link'>Reading parameters from simuconf.tab</a>
- <a href='#Reading_writing_parameters_from_to_settings.xml' class='link'>Reading/writing parameters from/to settings.xml</a>
- <a href='#Reading_writing_parameters_from_to_savefile' class='link'>Reading/writing parameters from/to savefile</a>
Now that you have learned <a href="en_CompilingSimutrans" title="en_CompilingSimutrans" class="wiki wiki_page">how to compile Simutrans</a>
, you may be wondering how to introduce modification into the game code.
Prerrequisites<a href="#Prerrequisites" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
- 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 <a class="wiki external" target="_blank" title="External link" href="https://github.com/aburch/simutrans/blob/master/documentation/coding_styles.txt" rel="external nofollow">documentation/coding_styles.txt</a> 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 <a class="wiki external" target="_blank" title="External link" href="https://code.visualstudio.com/" rel="external nofollow">Visual Studio Code</a>
, but you can use whatever you feel comfortable with, including a simple text editor.
Getting familiar with the code<a href="#Getting_familiar_with_the_code" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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 changes<a href="#Submitting_your_changes" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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 patch<a href="#Make_a_patch" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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 patch<a href="#Send_your_patch" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
Now head to the <a class="wiki external" target="_blank" title="External link" href="https://forum.simutrans.com/index.php/board,33.0.html" rel="external nofollow">Patches & Projects</a>
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!
Examples<a href="#Examples" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
This is a list of code examples for modifications frequently done. Please help expanding it.
Reading/Writing parameters<a href="#Reading_Writing_parameters" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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
enviroment.h
Copy to clipboard
static bool new_parameter;
2. And also give it a default value on dataobj/enviroment.cc
enviroment.cc
Copy to clipboard
bool env_t::new_parameter = false;
Reading parameters from simuconf.tab<a href="#Reading_parameters_from_simuconf.tab" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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:
settings.cc
Copy to clipboard
env_tnew_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.xml<a href="#Reading_writing_parameters_from_to_settings.xml" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
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:
enviroment.cc
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 savefile<a href="#Reading_writing_parameters_from_to_savefile" class="heading-link"><span class="icon icon-link link" ><img src="img/icons/link.png" alt="link"></span></a>
TODO
Die letzten Wiki-Kommentare