Creating a Package

Basics

A valid Thunderstore package is a zip file which must contain at least the following files at the root of the zip:

File naming is case-sensitive and must match the above exactly!

In addition to these required files, the package can include any number of additional mod-specific files.

Currently there's a maximum package size limit of 5 242 880 000 bytes (or roughly 5 GB), but this is a soft-limit and can be increased if needed. If you do face this scenario, contact us and request an increase.

Example of a minimal package viewed with 7-Zip:

Icon

A valid icon has to be exactly 256x256 in resolution and in PNG format.

Transparency is supported, although if used, it is recommended the icon has clear borders that work with any background color as icons might be displayed in a variety of themes (e.g. with 3rd party mod managers).

APNG is technically valid, but only the first frame will currently be displayed on the site.

README

Structure

The readme supports markdown syntax, closely but not exactly matching that of GitHub's. You can view GitHub markdown docs here and general markdown docs here.

As the markdown used by Thunderstore doesn't match GitHub 100%, it is recommended the Markdown Preview tool built in to Thunderstore is used for previewing the content.

Encoding

The readme has to be UTF-8 compatible (use Notepad++ or VS Code to check for encoding if you aren't sure). If you're using a new enough version of Windows, you can also check the encoding while saving the file:

Manifest

The manifest.json file is what tells Thunderstore and other tools some critical technical information about your package (such as the name & version). Some of it may also be used for presentation.

The file should be in standard JSON format (UTF-8 encoded) with the following contents:

Name

Max length of a name is 128 characters and it cannot contain characters other than abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_.

Underscores are replaced with a space in most views when displaying the mod name, so it's recommended they are used in place of where space normally would.

Description

Short description of the package, will be displayed in list views and other views where a full length readme cannot be shown. 250 characters max.

Version Number

The version number of the package, following the 3-numbered Major.Minor.Patch semantic version format.

For example, version 1.3.2 is newer than 1.2.23 but older than 2.1.0. Be mindful that these are not decimal numbers, and adding an extra zero at the end is significant. For example 1.0.10 is 9 patch versions higher than 1.0.1. Each version number part is a full number.

Dependencies

Dependencies declared in the manifest are automatically installed by the mod manager when a package is installed.

The dependencies field should be a list of strings, each string being a reference to a valid Thunderstore package.

The format used by Thunderstore to refer to other packages is as follows: {team name}-{package name}-{package version}, and you can find a Dependency string field matching this format on each package page:

Example dependencies:

[
    "MythicManiac-TestMod-1.1.0",
    "SomeAuthor-SomePackage-1.0.0"
]

Website URL

A website URL is optional, although an empty string is required even if no URL is included. If included, it will be added to the package page as a link.

Full example

{
    "name": "TestMod",
    "version_number": "1.1.0",
    "website_url": "https://github.com/thunderstore-io",
    "description": "This is a description for a mod. 250 characters max",
    "dependencies": [
        "MythicManiac-TestMod-1.1.0"
    ]
}

Creating the ZIP file

Windows

To create a package ZIP file on Windows, the easiest way is as follows:

1. Highlight all the files you intend to pack using Windows explorer

   1. Tip: Use ctrl + click to select multiple files

2. Right click any of the selected files

3. Choose the Send to -> Compressed (zipped) folder

After doing the above, a zip file with a name matching one of the files should be created.

Other

On other systems, any tool capable of creating standard ZIP files should suffice. Our recommended option is 7-Zip, which is available on all platforms.