On January 17th, 2009, a new feature has been added to OpenTTD. This Content Service feature allows downloading content from a central server (bananas.openttd.org). Authors of NewGRFs, AIs, Scenarios etc. first need to upload their work to the Content Service Website. Once added, OpenTTD players can easily download the NewGRFs, AIs, Scenarios etc. added to the central server using an in-game interface. Users only need to select what they want to download; the game handles installing all files.
Signing up for an account
BaNaNaS, like other OpenTTD web services, uses GitHub for authentication.
If you don't have a GitHub account, you have to sign up for one at github.com. See the GitHub docs on how to sign up for a GitHub account.
If you have a GitHub account, simply log in to your GitHub account.
After logging in on GitHub, go to bananas.openttd.org/login, click "Login via GitHub", and follow the prompts. After this, you should be logged into BaNaNaS as well.
Adding content to the service
Make sure you are logged in to BaNaNaS with your GitHub account first.
Click the Manager button in the menu bar. If this is the first time you'll be using the service to upload your work, you'll have to accept the terms of service. Read the terms carefully before accepting them.
Now you'll be presented with an overview of all content you uploaded earlier. Ofcourse, this overview is empty if you use the service for the first time.
Required general characterization of the content
To add new content, click the Upload New button at the top of the overview. A form will appear in which you'll have to provide all kinds of information:
This will be the name of your NewGRF, AI, Scenario etc. Please provide a useful name and not something like "My Scenario" because this is the name displayed in the in-game download interface. Make sure to get the name right, because it cannot be changed afterwards. Do not include a version number in the name of your content.
Whether you'll be uploading a Base Graphic package, a NewGRF, an AI, an AI Library, a Scenario or a Heightmap.
The version of the content (i.e. your NewGRF, AI, scenario,...) you will be uploading. You can type here whatever you like, but make sure to pick something sensible, something which tells users directly what version of your content is newer.
The license which you like to apply or have applied to your work. You can select either one of the available free licenses or provide a custom license. More on this later
The file containing your work. More on this also later.
A description of your work. This description, like most information you provide, will be displayed in the in-game download interface.
An url to the webpage dedicated to the content you're uploading or url to the appropriate topic at tt-forums.
Minimal OpenTTD Version
The minimal OpenTTD version required to use your work. When selecting Nightly or Custom, fill in the nightly revision number or the name and version of the required patchpack in the adjacent field.
Maximal OpenTTD Version
The maximum OpenTTD version. Similar to the previous entry, but now to set what version of the game was the last version on which your content worked. Leave blank, if it is supposed to work with current OpenTTD.
A comma seperated list of words describing your content. If you're adding a train newgrf then for instance add 'train' in the field. See the ingame download interface for more examples. It is good practice to look up what others have used and try to reuse existing tags whenever possible. For AIs there is a forum thread with some decisions regarding tags.
If your content requires other content to work, please select the content here. You can select more entries from the list by holding the control key. If your content doesn't require other content you can ignore this field.
After you've provided all information, just click the Upload button and wait until your content is uploaded.
In this field you'll have to select the license that applies to your work. You can select one of the predefined entries: GPL v2, GPL v3, CC-0 v1.0, CC BY v3.0, CC BY-SA v3.0, CC BY-NC-SA v3.0 or CC BY-NC-ND v3.0. If none of these licenses fit your work, select the option Custom.
If you've selected the custom option, you'll have to provide the license with your work. The license text needs to be in a file called either 'copying.txt', 'copying', 'license.txt' or 'license'.
Files to upload
You can in general upload a full package with all description and license information which the user should receive and see. The only necessary file(s) is the main file:
The main file(s) (required)
- NewGRF: exactly one .grf file
- AIs: a main.nut and an info.nut file.
- AI Libraries: a library.nut and a main.nut file.
- Scenarios: one .scn file.
- Heightmap: one .png or .bmp file.
- Base Graphics: one .obg file and exactly six .grf files in Base graphics packages as named in the .obg file and with the same MD5 checksums as defined in the .obg file.
The readme must be named 'readme', 'readme.txt' or 'readme.pdf'. It is recommended to use 'readme.txt' as this format can be displayed ingame. Additionally you may provide translations (see below)
The changelog must be named 'changelog', 'changelog.txt' or 'changelog.pdf'. It is recommended to use 'changelog.txt' as this format can be displayed ingame. Additionally you may provide translations (see below)
If you did select a common license in the step before you do not need to supply a license file. If you chose 'custom' you need to supply one. The acceptable names are 'copying.txt', 'copying', 'license.txt' or 'license'. If you've selected one of the predefined licenses, you must not provide a license file or otherwise the upload will fail.
You can provide translations for the readme or changelog files by attaching an ISO 639-1 language code (lowercase), and optionally also a country code (uppercase) for further differentiation. Some examples:
- 'readme_en_US.txt', 'changelog_en_US.txt' for US-English.
- 'readme_pt.txt', 'changelog_pt.txt' for Portuguese.
- 'readme_pt_BR.txt', 'changelog_pt_BR.txt' for Brazilian.
- 'readme_nb_NO.txt', 'changelog_nb_NO.txt' for Norwegian (bokmal).
- 'readme_nn_NO.txt', 'changelog_nn_NO.txt' for Norwegian (nynorsk).
When displaying readmes and changelogs within OpenTTD, it will first try to find a readme matching both the language and country code. If no such file exists, it will try only then language code without country. If there is no such file either, it will use the plain 'readme.txt' or 'changelog.txt' file.
Uploading the files
If you don't want to include a readme, changelog or custom license, you can just select the plain file (e.g. .grf, .scn, etc.) here. If you want or need to upload more than one file, you need to package the files first. These packages can be either in ZIP or TAR format (don't mistake TAR for RAR!).
Editing existing content
You can edit the properties of the content you uploaded earlier. Make sure you are logged in first. Click the Manager button in the menu bar. Now you'll be presented with an overview of all content you uploaded earlier.
Now click the Edit button in front of the entry you wish to, well, edit. You'll be presented with a form similar to the one for uploading new content with the only difference that not all fields are available. No you can edit the content's Description, URL, Version requirements and Dependency requirements as you see fit. Click the Edit button at the bottom to save the changes you made. If you don't want to save your changes, just navigate away from the page.
Updating existing content
It's not unthinkable that you create a new version of your content at some point in time. Using the update function allows you to replace an old version with a new one. Make sure you are logged in first. Click the Manager button in the menu bar. Now you'll be presented with an overview of all content you uploaded earlier.
Now click the Update button in front of the entry you wish to, well, update. You'll be presented with a form similar to the one for uploading new content with the only difference that the Name and Type field are unavailable. Now select the file to upload and make the necessary changes in the other field. Click the Upload button at the bottom to upload the new version.