**Add-ons** are extensions for *SuperTux* which are distributed
separately from the main distribution. In most cases, they are sets of
levels contributed by users or groups of users. They may, however,
include custom [[tilesets|Tileset]], which may give these
levels a very distinct look.

Add-ons can be downloaded from within *SuperTux*. Simply ensure you
have an internet connection, and select “Addons” from the main menu,
where you can choose to install the currently available add-ons.

The addons are managed in two repositories:

* https://github.com/SuperTux/addons
* https://github.com/SuperTux/addons-src

`addons` contains the `.zip` files that are downloaded by SuperTux,
while `addon-src` contains the levels in extracted form to make it
easier to modify and debug them.

The process of updating the `addons` repository is documented at:

* https://github.com/SuperTux/addons/blob/master/README.md

Manual installation
-------------------

If you cannot use the *Add-on manager* for some reason (for example if
you built *SuperTux* without *libcurl*), you can download the add-ons,
which are distributed as `.zip` files. Just copy the file(s) to your
*SuperTux 2* config directory (`~/.supertux2/` on UNIX / Linux,
`%USERPROFILE%\supertux2\` on Windows).

    $ wget -P ~/.supertux2 $ADDON_URL

Creating Mods
=============

So you've played SuperTux, beating all the levels, including the bonus levels, and now you want more. Happily, you're in luck. The Supertux Fan Site had loads of levels but supertux.info/pmlvls.php is no more. But now you want to actually play them, instead of looking at the screenshots, or create your own fun levels. These instructions are for you.

Creating Levels
---------------

Levels are created in different ways depending on which version you are using, as the format changed between 0.1.x and 0.3.x. Also, 0.3.x has a separate editor and game. Anyway, these will create some .stl files for you to enjoy.

### SuperTux 0.1.x

Create as many levels as you want using the built-in editor. Try reading the editor help first by pressing F1.

#### Creating Worldmaps

There's another editor from <http://roofrabbit.com/supertux.html#editor> written in VB that you can use to create worldmaps, or you could try to use [FlexLay](http://flexlay.berlios.de).

### SuperTux 0.3.x

Download the SuperTux Editor from [Download/Unstable](Download/Unstable "wikilink"). The [Editor FAQ](Editor_FAQ "wikilink") might be helpful. Alternately, you could create 0.1.x levels and then modify them using a text editor or the [Scheme converter script](http://supertux.lethargik.org/svn/supertux/trunk/supertux/tools/levelconverter-0.1.3_0.2.0.scm) into version 2 levels. See the [File formats](File_formats "wikilink") page for details.

Packaging Levels
----------------

Once you've made these beautiful levels, you want to let the world see them. Just follow these easy steps, which will make archives usable directly as addons for 0.3.x and allow one-step unpacking in 0.1.x:

-   Pick a “meaningful name”. This name will be used as file and directory name - the user won't get in touch with it. So pick a short but descriptive name. Your name or acronym should be sufficient, for example. Here, we will use *my-levels* as example.
-   Create a new directory hierarchy: `levels/`*`my-levels`*
-   Copy your levels (\*.stl files) into your that folder.
-   If you made a [worldmap](worldmap "wikilink"), you have to put it
    -   **0.1:** in `levels/worldmaps/` as *`my-levels`*`.stwm`, or
    -   **0.3:** in your `levels/`*`my-levels`*`/` as `worldmap.stwm`.
-   To make it an addon, create a *`my-levels`*`.nfo` text file in the top level of your directory hierarchy and fill it with the following information. See the [\#.nfo files](#.nfo_files "wikilink") section below for details.

`(supertux-addoninfo`
` (kind `“`<Type:`` ``Level,`` ``Level`` ``Subset,`` ``World,`` ``...>`”`)`
` (title "`

<Title Here>
")

` (author `“<Your name here>”`)`
` (license `“<Pick a license; all official levels are at least GPL 2 / CC-by-sa >”`)`
` (http-url `“<Place where you plan to upload it>”`)`
` (file `“<Name of your directory>`.zip`”`)`
`)`

-   So that it shows up in the “Contrib Levels” menu, you need to create an `levels/`*`my-levels`*`/info` file. You really only need this:

`(supertux-world`
` (title (_ `“<Name as will appear in menu>”`))`
` (description `“`<Description`` ``of`` ``your`` ``levels>`”`)`
` (hide-from-contribs #f)`
` (levelset `<Do you have a worldmap? Yes ⇒ #f, No ⇒ #t>`)`
`)`

-   Use a ZIP utility to package up your directory into `my-levels.zip`.
-   Once you're done, your tree should look like this:

**0.1:**

`my-levels.zip`
`!`
`+-- levels/`
`!   !`
`!   +-- my-levels/`
`!   !   !`
`!   !   +-- `*`*.stl`*
`!   !   +-- info`
`!   !`
`!   +-- worldmaps/`
`!       !`
`!       +-- my-levels.stwm`
`!`
`+-- my-levels.nfo`

**0.3:**

`my-levels.zip`
`!`
`+-- levels/`
`!   !`
`!   +-- my-levels/`
`!       !`
`!       +-- `*`*.stl`*
`!       +-- info`
`!       +-- worldmap.stwm`
`!`
`+-- my-levels.nfo`

-   You've made a package. Now log on to [IRC](Contact#IRC "wikilink") and let us know about your addition! :)

### .nfo files

An **.nfo file** is a file in the typical Lisp-syntax which describes your add-on in some detail. It can originate from two locations:

-   As the file *`my-levels`*`/`*`my-levels`*`.nfo` within your add-on.
-   As a text-file retrieved from an URL.

#### Valid keys

  
*(As of [6398](Template:Revision "wikilink"))*

kind  
Type of your add-on. This is used when displaying information about your add-on to the user. If in doubt, use “Levels” here.

title  
Title (name) of your add-on

author  
Your name

license  
License under which your levels are provided. “GPL 2+ / CC-by-sa 3.0” is the preferred license for *SuperTux* content.

http-url  
URL pointing to this add-on, i.e. the .zip-file. Used for downloading the add-on based on the information provided in the (separate) info file.

file  
Filename used to store the add-on. Be conservative and use “*my-levels*.zip”. This field is intended to be used when the info file is downloaded from a URL.

md5  
MD5-sum of your .zip-file. This field only makes sense when downloading the info file from an URL.

Installing Levels
-----------------

This is the hard part. People don't follow these guidelines, because they didn't exist, and so make lots of strange directory layouts. But there are some general rules:

-   If it's advertised as a 0.3.x addon, it probably is. To install this, just unpack it in your supertux data directory, or better yet put it in your .supertux2 directory. (See [Console](Console "wikilink") for the location; it's the directory with the config file in it) Starting with Subversion [5458](Template:revision "wikilink"), you can also put the archives into the data folder without bothering to unpack them.
-   If they followed these instructions for 0.1.x, you can still just unpack the archive into the supertux data directory.
-   For other levels, you'll have to install them manually. Unpack the archive to a convenient location. If there's a README file, see if it has instructions for installation and follow those.
-   If there's no README file, try following the packaging instructions above, skipping the zipping instructions. Then you can copy the stuff in your layout directly into the supertux data directory.

TODO
----

This doesn't tell you all there is to know about modifying SuperTux; check back from time to time for updates. If you are knowledgeable about the following things, try adding them to this tutorial:

-   Intros or extros for levels
-   Scripting .nut files
-   Adding new images or sounds
-   Replacing game files
-   Installing a new supertux executable

<Category:Development>
