FAQ development

From OpenTTD
Jump to: navigation, search

This article covers questions regarding development of OpenTTD, e.g. using SVN, downloading the source, setting up compilers, etc..


Contributing to the project

What can I do to contribute to the project?

This depends on your talents.

  • Without coding
    • Translating to other languages
    • Extend this Wiki, or better: Update out-dated stuff.
    • Graphics, sound and music: If you draw stuff, but you can't code; check out the forums for some project to contribute to. Note: If you do not cover all skills required for some project, it's smarter to join an existing project, than trying to find someone else to join your new project.
  • Add-on coding:
  • Main-game coding (C/C++):
    • See below.
  • Tool-chains for Add-ons (mostly python):

How to get in contact with people

Checkout the Community page for links to the various forums and platforms for each subject.

How does open-source work? What to expect from people?

As general advice, if you are new to open-source: Consider the different interests of people in the project. Don't expect people to have rational goals, or to share interests with you. Even if you seem to work on the same thing, some people are mainly interested in the result (what to do?), while others are mainly interested in the path towards some result (how to do something?).

This applies to both "inoffical add-ons" as for the "official branch": This is a volunteer project; everyone is here for fun, not for obligations. Some people develop stuff with the expectation that official maintainers are obliged to look at their stuff and include it into the main branch; but the truth is that people will only look at stuff when they are interested in it.

In every volunteer project you will find posts like "this patch has been around for 10+ years, I want it so badly, why is it still not in the main branch?". But don't let that spoil your fun :)

Contributing to the main game

What are the goals of the offical branch?

The main goals of the offical branch are:

  • Replicate the original gameplay.
  • Improve the user interface.
  • Allow extending the gameplay with add-ons.

In contrast, extending or altering the gameplay of the base game is not encouraged.

The rationale behind these goals is that people have different opinions about what OpenTTD is, and what it should be. When it comes to gameplay there are at least these groups of people:

  • Model railway (mostly singleplayer): Build "realistic" landscapes, rollplay a world, or even replicate historical scenarios.
  • Economical challenge (mostly singleplayer): Run a business with economical challenges.
  • Transport challenge (singleplayer or cooperative multiplayer): Build efficient track layouts with high cargo throughput and tons of vehicles.
  • Competitive speed run (competitive multiplayer): Maximize some goal in some limited amount of time.

When it comes to gameplay features there are at least these groups of interests:

  • Control freak: Micromanagement like conditional orders, refitting and loading, ...
  • Casual: Automatisation like cargodist, path based signalling, ...

To please everyone, the offical branch tries to stay close to the original gameplay; after all that is what everyone brought here. The preferred method to alter and extent the gameplay is via add-ons like NewGRF and GameScripts.

For the longest time, the official branch was also open to features which can be enabled/disabled, but the corner-cases that came with some configurations have rendered some parts of the code very complicated. Today new features have to work with all the already existing features, which is not only challenging in corner cases, but also requires spending considerable more work than just "making it work in the game mode, that I play".

The preferred method to allow gameplay extensions is to extent the add-on interface. This moves conflict solving away from the codebase to the player picking from the add-on options. It is more accepted for add-ons not working together, than the base game not working with certain setting combinations.

I do not agree with the goals of the offical branch, what can I do instead?

There exist many "patches" for the main game which add "gameplay features", which are often combined into patch packs. If your interest is in altering the main game in C/C++, you will likely find your home here.

The predominant version control system in this area is git. You may want to check out the forums for other people in this area. At the time of writing, "JGR's patch pack" is a good source for finding maintained patches to orientate at.

I've fixed a bug / added a feature. How can I submit it to the codebase?

  • Make a diff file (aka patch file) of your changes and submit it to Flyspray. Please watch the patch tracker carefully to see if the developers have any suggestions. If everything is OK with your patch, it will get merged into the SVN tree.
  • You may also create a thread on our forum and add your patch to the patch list.

I want to become an official OpenTTD developer! How?

  • This is a matter of trust. OpenTTD has many complicated and arcane mechanics with lots of corner cases. You can join the official team by proving that you fix more than you break.
  • The only way to get there is by constantly making patches, especially for fixing bugs. Check out the list of known bugs and be aware of our preferred coding style.

Source code

What is source code?

How can I obtain the source code?

Preferentially you obtain the source code via a version control system (VCS). They allow you to checkout the source easily and update to any version (maybe newest as nightlies got a new feature or some special one needed for a particular patch) you might need. If you plan to use patches, using mercurial or git is preferred do to their easier ways to update and handle patched versions.

Note that new revisions may appear in the git repository via HTTP only after a delay of several hours. This delay does not appear to happen using the git protocol.

You can also obtain the source via tar balls, but avoid this, if you can make use of a VCS:

What is the SVN version?

  • SVN aka Subversion is a version control system like CVS. Basically it tracks changes to the source code of the game. The SVN version is the latest (bleeding edge) source code for the game.

What operating systems does Subversion run on?

  • Any modern Unix(-like) (Mac OS X, Linux, BSD, ...), Win32, BeOS/Haiku, OS/2. Subversion is written in ANSI C and uses APR, the Apache Portable Runtime library, as a portability layer. The Subversion client will run anywhere APR runs, which is most places.

How do I get the SVN version then?

  • First you need to download the client software for your operating system which will connect to the SVN server and download the source code. You can get it from the SVN project homepage at http://subversion.apache.org/. If you are using Windows you may want to get TortoiseSVN as it integrates with Explorer nicely and you won't have to run command line stuff.

    Next you need to set up the client to use the repository url which is "svn://svn.openttd.org/trunk". This will depend on which software you get, but you can find out how to do this with the documentation included with it.

    On Linux (Unix) you can use command "svn co svn://svn.openttd.org/trunk/".

    On MacOSX Xcode can handle both SVN and Git by itself so no need to install anything (unless you haven't got Xcode yet).

Subversion has not been ported to my platform / I don't want to install more software - is there any other way I can get to the source code?

Now I have got the source code how can I compile it?

To test the compiler setup, try compiling the game from source code without applying any patch (see below), and run the resulting executable. If all goes well, you can be fairly sure the setup is good. If it fails, you know for sure the patch is not the source of the problems.

I had a problem compiling! What should I do?

  • This is not a compiling FAQ, try to ask your compiler vendor for help.

Why did the developers decide to use Subversion?

  • Subversion (SVN) was chosen over CVS because it is more advanced and easier to use. Also a lot of the developers don't like CVS any more now they know SVN.
  • SVN was "chosen" over distributed version control systems (DVCS) like Bazaar, Darcs, git, Mercurial and SVK because at the time the choice had to be made none of these existed. GNU arch was one of the few DVCSes that existed but was difficult to learn and understand. Later on a versioning API for NewGRFs was made out of the SVN revision so migrating to a DVCS would remove that capability breaking lots of existing NewGRFs.

What is the point of a version control system? Why don't they just upload the source code to an FTP directory?

  • Version control systems keep track of all the changes, when they were made and by who. If the developers later find out something they did was a mistake and broke something important they may have to rewrite it from scratch. With this they can just 'checkout' a revision from when it was working. It also allows the developers to add comments so they know what changes have been done.

How do I create a patch?

  • Bash (Linux) or cmd (Windows)
    • In Windows, make sure you have either the svn or git binary installed. They ship as default with most versions of Linux.
      • SVN: svn diff > mypatch.diff from the source directory
      • git: git diff origin/master HEAD /src > mypatch.patch from anywhere inside your repository
  • GUI
    • Tortoise SVN (Windows)
      • Right click on the source directory, select Create Patch and supply a location and a name of your new patch.

How to apply a patch?

It's usually best to apply patches to the revision stated by the patch creator.

Different version control systems use different ways of expressing changes. Currently, there are SVN type patches and HG/GIT type patches. To know what you have, open the patch file with a text editor, and look at the first few lines.

A SVN type patch starts like

Index: src/gfx.cpp
--- src/gfx.cpp (revision 20024)
+++ src/gfx.cpp (working copy)
@@ -641,14 +641,13 @@

and a HG/GIT type patch starts like

diff --git a/src/gfx.cpp b/src/gfx.cpp
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -641,14 +641,13 @@

The crucial difference is the a/ and b/ additions at the lines starting with --- and +++.

  • Unix shell (Windows using MSYS/MinGW, Mac OS X, Linux, ...): Type the following line into a console (replace patch_name with the filename of the patch):
patch -p0 < patch_name (for SVN type patches). However, in some cases you might need patch -p1 < patch_name (for HG/GIT type patches).
  • Windows, graphical: Make sure you have TortoiseSVN installed.

TortoiseSVN can only handle SVN type patches, it CANNOT handle HG/GIT type patches!!

Right-click on the folder with the OpenTTD source code, open the TortoiseSVN submenu and select 'Apply Patch...'. Browse to the patch file and select it. Then, right click on the 'File Patches' window and click on 'Patch All'. After you're done, close the TortoiseMerge window.
Personal tools