# Thunderstore Wiki

Helpful information and documentation for Thunderstore.io

##  For Users:

For help with [Thunderstore Mod Manager](https://get.thunderstore.io/):

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/gytzW1FXiZkegLdZyQNC" %}
[Game won't launch modded](/mod-manager/game-wont-launch-modded)
{% endcontent-ref %}

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/DOozQ79SEsomIwips25b" %}
[Common Issues](/mod-manager/common-issues)
{% endcontent-ref %}

## For Developers:

Mods on Thunderstore are uploaded as **packages**. For help with packages:

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/wivcdo8JwOEB6b6yW8CQ" %}
[Creating a Package](/mods/creating-a-package)
{% endcontent-ref %}

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/7UihDgT8oCuPCSYm7vCr" %}
[Updating a Package](/mods/updating-a-package)
{% endcontent-ref %}

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/0vezZx8kyuQDFEyhWIqy" %}
[Packaging Your Mods](/mods/packaging-your-mods)
{% endcontent-ref %}

{% content-ref url="/spaces/6knfQnTz0CipH0b96qdV/pages/tWw2ClMLdDC3H5zivHKv" %}
[Mod not visible?](/mods/mod-not-visible)
{% endcontent-ref %}

## Contact Us

If you couldn't find the answer you were looking for on the wiki, or you need to contact Thunderstore staff quickly, reach out [on our Discord server](https://discord.thunderstore.io/).

Alternatively, see <https://pages.thunderstore.io/p/contact-us> for more ways to contact us through email (responses to emails may be significantly slower than Discord).


# Your First Upload

Publishing your first mod on Thunderstore, step by step.

This page walks you through publishing your first mod on Thunderstore from start to finish.

If you have uploaded before and just need the package requirements, see [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package) instead.

## Quick checklist

* [ ] Thunderstore account and team created
* [ ] Mod files in the correct folder structure for your game
* [ ] `manifest.json` (validated)
* [ ] **Mod installed from a zip and tested on a clean profile, in game**
  * [ ] Mod functions as intended
* [ ] `icon.png` (256x256, PNG)
* [ ] `README.md` (UTF-8 format), reviewed with Markdown Preview and ideally with screenshots
* [ ] All of the above zipped at the **root** of the zip
* [ ] [Global Rules](/moderation/global-rules) read
* [ ] Uploaded to the right community with categories set

{% stepper %}
{% step %}

## Create an account

Register at [thunderstore.io](https://thunderstore.io/) by signing in with Discord, GitHub or Overwolf.

You need an account to upload, but not to download mods.
{% endstep %}

{% step %}

## Create a team

Every package on Thunderstore is owned by a **team**, not by a user account. You cannot upload without one.

Teams are not created automatically, so you need to create one yourself. If you are modding solo, you can simply create a team named after your own username. You can do that at [thunderstore.io/teams](https://thunderstore.io/teams/), or click the user icon in the top right and choose **Teams**.

{% hint style="warning" %}
Your team name becomes part of your package's identity and cannot be changed later. It appears on your package page and makes up part of the dependency string other modders use to depend on your mod, in the format `TeamName-PackageName-Version`. Pick something you are happy to keep.
{% endhint %}

Teams are also how you add collaborators later, so if you are working with other people, pick a team name that fits the whole group.\
\
Remember that those with Owner rights have the same access as you. Keeping contributors as Members gives them enough access to update and interact with your packages.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2Ffl877FLBf4wrCRj5uO5w%2Fcreate-team.png?alt=media&amp;token=6a350fbb-2846-4021-97fd-6ecaac538c73" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

## Build your package

A Thunderstore package is a zip file containing `icon.png`, `README.md` and `manifest.json` at its root, plus your mod files. The file names have to match exactly, including the extension.

[Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package) has the exact requirements for each of those, and a minimal example package you can download and copy.

Thunderstore only checks the required files, so an upload can go through and still not install correctly. Mod managers do their best to work out where files should go. If your mod is not installing correctly in a mod manager, refer to [Packaging Your Mods](https://wiki.thunderstore.io/mods/packaging-your-mods). You can test this before uploading by using the **Import local mod** functionality, located inside the mod manager's settings.

### Your manifest

Your `manifest.json` tells Thunderstore and mod managers what your package is. A minimal example:

```json
{
  "name": "MyFirstMod",
  "version_number": "1.0.0",
  "website_url": "https://github.com/yourname/MyFirstMod",
  "description": "A short summary of what your mod does.",
  "dependencies": []
}
```

* `name`: your package name. Letters, numbers and underscores only, no spaces. Changing it later creates a new package
* `version_number`: in Major.Minor.Patch format, for example `1.0.0`
* `website_url`: a link to your source code or mod page. Can be left as an empty string
* `description`: a short summary shown in the mod listings, 250 characters at most
* `dependencies`: other packages your mod needs, each in the `TeamName-PackageName-Version` format. Leave the list empty if there are none
  {% endstep %}

{% step %}

## Test it in game

Test the zip you are going to upload, not just your mod files. When you make the icon and README is up to you, plenty of authors work on those while the mod is still in progress.

Zip your files the way [Step 6](https://wiki.thunderstore.io/mods/your-first-upload#create-the-zip) describes, then install the zip using the mod manager's **Import local mod** option and test the mod. Installing from a zip rather than copying files in by hand also catches a wrong folder structure from Step 3.

Test that:

* The mod manager installs or loads the package without errors
* The game launches with the mod installed
* The mod does what you intended it to do
* Config options are generated and take effect, if your mod has any
* No unexpected errors in the log are associated with your mod

{% hint style="danger" %}
Test on a clean profile. Your own profile with other mods may have dependencies, config files and leftovers that new users will not have.
{% endhint %}

If something is wrong, fix it, rebuild the zip and test again.
{% endstep %}

{% step %}

## Write your README and make your icon

This is what people judge your mod on before they install it. They see it in this order: icon, short description, categories, and only then the README if they want more.

### Your icon

`icon.png` has to be exactly 256x256 and a PNG. Beyond meeting that requirement, it is worth spending a little time on, because it sits next to every other mod in the listings and is the first thing people see.

* Make it readable at small size
* Give a hint of what the mod actually does or adds
* Many users prefer icons that are not AI generated

### Make your README worth reading

Your `README.md` is your mod's page. It is what people read before deciding to install, and it is the first thing they check when something does not work.

New to Markdown, or not sure what Thunderstore supports? [Markdown Guide](https://wiki.thunderstore.io/mods/markdown-guide) covers what you need for a package README. Paste your README into [Markdown Preview](https://thunderstore.io/tools/markdown-preview/) as you write to see how it will render.

Cover at least:

* What the mod does, in the first two lines
* What it changes or adds in game
* Dependencies, if there are more than the obvious ones
  * A mod that only needs BepInEx or one well known library does not need a list
* Configuration options, if there are any
* Known issues or incompatibilities
* Credits and contact, if you want feedback

**Show it, do not just describe it.** Screenshots, GIFs or a short video clip do far more than a paragraph ever will, especially for anything visual such as models, textures, UI or effects. A single good screenshot near the top of the README is one of the cheapest things you can do to get people to install your mod.

A pattern that works well: a showcase section near the top, split by feature, with a line of explanation and then the images or GIFs that demonstrate it. Detailed configuration and reference material goes further down, where the people who need it will still find it.

{% hint style="info" %}
Images have to be linked from somewhere they are publicly hosted, such as your GitHub repository or an image host. Files inside your package are not served as images on your package page, so a path pointing at a file in your zip will show as a broken image.

Use a direct link to the image file: `![Description of the image](https://example.com/screenshot.png)`

To show another package's icon, link it directly: `https://gcdn.thunderstore.io/live/repository/icons/Author-Package-1.0.0.png`
{% endhint %}

### **Your changelog**

`CHANGELOG.md` is optional, but it is where people look when a version breaks something. It follows a different convention from your README: newest version at the top, a heading for each version, and a short list of what actually changed. Some authors also group changes under subheadings such as Added, Changed and Fixed.

```
## 1.1.0
- Added a config option for spawn rate
- Fixed a crash when loading a save with no mods

## 1.0.0
- Initial release
```

"Various fixes and improvements" tells nobody anything. Name what changed.

### Final README check

Open your README one more time and check that:

* The README matches what the mod actually does
* Dependencies and config options are listed
* Your images load
* There are no typos left
  {% endstep %}

{% step %}

## Create the zip

Two tools worth running before you zip:

* [Manifest Validator](https://thunderstore.io/tools/manifest-v1-validator/) catches errors in your `manifest.json`
* [Markdown Preview](https://thunderstore.io/tools/markdown-preview/) shows how your README will render, so you can spot problems before they are public

{% hint style="info" %}
The markdown preview tool cannot check file encoding. If your README contains special characters, confirm the file is saved as UTF-8 without BOM in your text editor.
{% endhint %}

Select the **files**, not the folder containing them, then compress the selection.

{% hint style="danger" %}
If you zip the folder instead of its contents, your files will not be at the root of the zip and the package cannot be uploaded.
{% endhint %}

Step by step instructions for Windows and other systems are in [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package).

This is the zip you upload, so build it fresh from your final files. If you changed any mod files since you tested in Step 4, install this zip and test it once more before you upload.
{% endstep %}

{% step %}

## Upload

Open the [upload page](https://thunderstore.io/package/create/) and fill in the form.

You will be asked for:

* **Upload file**: your zip, up to 10GB
* **Team**: the team the package will be published under
* **Communities**: which community or communities the package is listed in
* **Categories**: how people filter and find your mod. The list only appears once you have picked a community. Pick what genuinely applies to your package, and check how similar mods in that community are tagged, since communities apply categories differently. This is also where you set the **AI generated** category. See **AI generated** content in the [Global Rules](https://wiki.thunderstore.io/moderation/global-rules#ai-generated-content) for what counts
* **Contains NSFW content**: set this to Yes if the content is not suitable for children

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FXtnbVVvrcadGWhEEOADL%2Fupload-form.png?alt=media&amp;token=5685b118-82bc-4444-a0db-4d9b403df693" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Check the **NSFW flag** before you submit. It cannot be changed without publishing a new version, and it is not carried over between versions, so you need to set it again on every upload. Categories can be edited later under **Manage Package**, but the files in a version cannot, so anything missing or wrong in your README stays on your page until you publish a new version. Run through the final README check before you submit.
{% endhint %}

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FvLr4qUTJRrtF8RXcD2T6%2Fupload-submit.png?alt=media&amp;token=4135fa0c-9e9a-4c41-90c2-865a2a63639e" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Modding a game that does not have a community on Thunderstore yet? See [Adding a new game](https://wiki.thunderstore.io/ecosystem/adding-a-new-game).
{% endhint %}
{% endstep %}

{% step %}

## Check your package page

Once the upload succeeds, open your package page and confirm:

* The icon displays correctly
* The README renders the way you expected
* The description reads well in list views
* The categories are correct
* The NSFW flag is set correctly
* Any dependencies you declared are listed
  {% endstep %}

{% step %}

## Publishing an update

The files in a version cannot be changed after upload. To change your mod, you upload a new, higher version. See [Updating a Package](https://wiki.thunderstore.io/mods/updating-a-package) for how to do that without accidentally creating a second package.

Categories and other package settings can be edited at any time under **Manage Package**, without uploading a new version.&#x20;
{% endstep %}
{% endstepper %}

## Before you publish

All packages are subject to the [Global Rules](https://wiki.thunderstore.io/moderation/global-rules), plus any rules specific to the community you upload to. Read them once before your first upload. Many takedowns come from uploading content you do not have permission to distribute, such as reuploading someone else's mod without their permission.

## If your upload is rejected

| Message                | Usual cause                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Missing required files | The zip contains a folder rather than the files at its root                                                                     |
| Invalid icon           | Icon is not exactly 256x256, or is not a PNG                                                                                    |
| Invalid manifest       | Malformed JSON, or a missing field                                                                                              |
| Invalid name           | Package name contains spaces or characters that are not allowed                                                                 |
| Invalid submission     | Your package needs a manual review. Reach out to the moderators in the [Thunderstore Discord](https://discord.thunderstore.io/) |

Requirements for each of these are in [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package).

Uploaded successfully but something is wrong afterwards?

* Package does not appear where you expect: [Mod not visible?](https://wiki.thunderstore.io/mods/mod-not-visible)
* Mod does not work when installed with a mod manager: recheck [Packaging Your Mods](https://wiki.thunderstore.io/mods/packaging-your-mods) for your game
* A new version created a second package instead of updating: [Updating a Package](https://wiki.thunderstore.io/mods/updating-a-package)

Still stuck? Two good places to ask:

* **The** [**Thunderstore Discord**](https://discord.thunderstore.io/) for anything about the site itself, uploading, or moderation
* **Your game's own modding community** for anything specific to that game. This is usually the faster answer, since the people there know the quirks of the game


# Creating a Package

Requirements for a valid Thunderstore package

### Basics

{% hint style="info" %}
This page only outlines the basic requirements of a Thunderstore package. For game and loader specific instructions, see [packaging your mods.](/mods/packaging-your-mods)
{% endhint %}

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

| Name          | Description                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| icon.png      | PNG icon for the mod, must be 256x256 resolution.                                |
| README.md     | Readme in markdown syntax. Will be rendered on the package's page.               |
| manifest.json | JSON file with metadata of the package. See [Manifest](#manifest) for structure. |

{% hint style="info" %}
Packages can also contain a [CHANGELOG.md](https://wiki.thunderstore.io/updating-a-package#changelog)
{% endhint %}

**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](https://pages.thunderstore.io/p/contact-us) and request an increase.

Example of a minimal package viewed with [7-Zip](https://www.7-zip.org/):

![Minimal Thunderstore package opened with 7-Zip](https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FgqErDuxdt77cbiWvi72r%2Fimage.png?alt=media\&token=e15f0cb4-9685-4f5b-a27b-6091abb16d43)

{% file src="/files/3gnb7z8IO410Z5SIia4j" %}
Example package
{% endfile %}

### Icon <a href="#icon" id="icon"></a>

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).

Animated PNG files are technically valid, but only the first frame will display on some pages / embeds.

### README

#### Structure

The readme supports markdown syntax, closely but not exactly matching that of GitHub's. You can view GitHub markdown docs [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) and general markdown docs [here](https://commonmark.org/help/).

As the markdown used by Thunderstore doesn't match GitHub 100%, it is recommended the [Markdown Preview](https://thunderstore.io/tools/markdown-preview/) tool built in to Thunderstore is used for previewing the content.

![Markdown Preview Tool Example](https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F1i5lST1Gu5KEXTCHY81v%2Fimage.png?alt=media\&token=68326f58-d3fc-4bd2-8995-4385e0f13f14)

#### Encoding

The readme has to be UTF-8 compatible (use [Notepad++](https://notepad-plus-plus.org/) or [VS Code](https://code.visualstudio.com/) 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:

![Windows notepad save dialog](https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FDWH6yCWAWzS9onyvXl4k%2Fimage.png?alt=media\&token=3f4ceebd-6076-4331-bb3c-ecb5435c69f0)

{% hint style="info" %}
UTF-8 Is generally compatible with other encodings, as many of them share a similar structure for common characters. Generally you will only hit encoding issues if special characters are involved, in which case converting to UTF-8 should solve the issue.
{% endhint %}

{% hint style="info" %}
The markdown preview tool is unable to check for file encoding, as that is a property of the file save format, and the validator does not read files.
{% endhint %}

### 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](https://en.wikipedia.org/wiki/JSON) (UTF-8 encoded) with the following contents:

<table><thead><tr><th width="150">Key</th><th width="410">Description</th></tr></thead><tbody><tr><td>name</td><td>Name of the mod, no spaces. Allowed characters: <code>a-z A-Z 0-9 _</code></td></tr><tr><td>description</td><td>A short description of the mod, shown on the mod list. Max 250 characters.</td></tr><tr><td>version_number</td><td>Version number of the mod, following the <a href="https://semver.org/">semantic version format</a> Major.Minor.Patch</td></tr><tr><td>dependencies</td><td>A list of other packages that are required for this package to function. </td></tr><tr><td>website_url</td><td>URL of the mod's website (e.g. GitHub repo). Can be left an empty string.</td></tr></tbody></table>

{% hint style="info" %}
You can use the [Manifest Validator](https://thunderstore.io/tools/manifest-v1-validator/) tool to validate your manifest before packaging it to a zip.
{% endhint %}

#### 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](https://semver.org/) 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.

{% hint style="info" %}
Thunderstore will always display the highest package version regardless of upload date
{% endhint %}

{% hint style="info" %}
To update a package, simply increment its version number and re-upload it.
{% endhint %}

#### 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:

![Dependency String Location](https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FoFFs99IQIXPT2RGV7Go4%2Fimage.png?alt=media\&token=64cc2806-9427-4814-bcc4-c59cf1f54747)

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`

![Send to zipped folder windows dialog](https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2Fd8yttTvnrLOnEbUwc1aT%2Fimage.png?alt=media\&token=46327010-af7a-4cea-b442-1472c1cb7df5)

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

{% hint style="warning" %}
Make sure to select individual files to create a zip of instead of the directory they're within. If you zip the directory instead, the files will not reside at the root of the zip, thus making the package invalid.
{% endhint %}

#### Other

On other systems, any tool capable of creating standard ZIP files should suffice. Our recommended option is [7-Zip](https://www.7-zip.org/), which is available on all platforms.


# Updating a Package

Instructions for how to update your mod on Thunderstore

Packages can be updated with new versions (you cannot modify existing versions) through [the same page](https://thunderstore.io/package/create/) that you uploaded the original package.

* Unzip your original package.
* Add or modify your `README.md`, `CHANGELOG.md`, code, and other assets.
* Modify the `manifest.json` file's `version_number` field to a higher version number. Do not modify the `name` field or it will be uploaded as a new package instead of updating the old one.
* [Upload it again](https://thunderstore.io/package/create/) under the same Team (otherwise it will be uploaded as a new package instead of updating the old one).

{% hint style="warning" %}
Version numbers follow the [semantic versioning](https://semver.org/) syntax without suffixes, and the highest available version will be displayed on the website & mod manager as the latest version.

\
Be careful with semantic versioning, v1.0.20 is higher than v1.0.3
{% endhint %}

**Example of modifying the manifest.json:**

```json
{
    "name": "ExamplePackage",
    "version_number": "1.0.0",
    "website_url": "",
    "description": "This is an example",
    "dependencies": []
}
```

```json
{
    "name": "ExamplePackage",
    "version_number": "1.0.1",
    "website_url": "",
    "description": "This is an updated example!",
    "dependencies": []
}
```

**Package versions are immutable!** Once a version is successfully uploaded, it can no longer be edited. Any further changes (including README.md edits) will require uploading a new version. Immutability is required for the ecosystem to offer conflict-freeness guarantees and efficient caching.

{% hint style="success" %}
When updating a package, you can leave the *Categories* field blank and it will use the categories you selected when you uploaded your package the first time!
{% endhint %}

### Changelog

Thunderstore supports `CHANGELOG.md` files which use the same markdown as your `README.md` file.

**Example:**

```
## v3.0.0
- Added X feature
- Added Y feature
- Fixed Z bug

## v2.0.0
- Added X feature
- Fixed Y bug
- Fixed Z bug

## v1.0.1
- Fixed text formatting in `README.md`

## v1.0.0
- Full release
- Fixed X bug
- Fixed Y bug

##
<details><summary>Show pre-release updates</summary>

## v0.5.1
- Fix X bug

## v0.5.0
- Beta release
- Add X feature
- Fix Y bug

## v0.1.1
- Fix X bug

## v0.1.0
- Alpha release

</details>
```


# Packaging Your Mods

Different ways to package mods for different games

When a mod is installed with Thunderstore Mod Manager, the files might not be copied as-is into the profile folder. For example files placed in subfolders might end up getting copied to the root folder. How exactly the files are copied depends on the mod loader used by the game.

## BepInEx Games

**Folders**

The Thunderstore Mod Manager will empty the contents of folders in your package's .zip file unless they are inside specifically named folders. The name of the folder decides where the file will be extracted to. Here are the common folder routes in most games that use BepInEx for modding (the BepInEx folder can be omitted):

* BepInEx/plugins
* BepInEx/core
* BepInEx/patchers
* BepInEx/monomod
* BepInEx/config

For a full list of install rules for each game, check the [ecosystem-schema](https://github.com/thunderstore-io/ecosystem-schema/tree/master/games/data)

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FSaYdK9GSZLzd5VpOLvRn%2Fimage.png?alt=media&amp;token=5c218eb9-5bd4-456b-b9c7-37296a279986" alt=""><figcaption><p>An example of a Thunderstore package having its folder emptied into the root of the package folder</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FMO0vv0WPXJH8neFKhJCR%2Fimage.png?alt=media&amp;token=fd1d3feb-baa4-4150-845f-20451482d811" alt=""><figcaption><p>An example of the Thunderstore package having its folder preserved</p></figcaption></figure>

## MelonLoader Games

{% hint style="danger" %}
For **Backpack Hero, BONELAB, BONEWORKS, HardBullet, Patch Quest, and RUMBLE** refer to <https://github.com/ebkr/r2modmanPlus/wiki/Structuring-your-Thunderstore-package#melonloader-legacy-support>
{% endhint %}

{% hint style="warning" %}
This guide is intended only for games using MelonLoader v0.7.0 or higher.
{% endhint %}

**Folders in a package's zip**

* Place the required files (manifest.json, icon.png, and README.md) at the root of the zip
* Place **regular mod dlls** either at the root of the zip or in a *Mods* subfolder
* Place **MelonLoader plugins** in a *Plugins* subfolder
* Place **external libraries** in a *UserLibs* subfolder
* Place **data files** in a *UserData* subfolder

**Folders when installed to a profile**

* Thunderstore Mod Manager will install files and folders in a package's *UserData* folder as-is to `UserData/TeamName-PackageName`
* All other files and folders will be installed as-is to `Mods/TeamName-PackageName`
  * MelonLoader will load the mods, plugins, and libraries from there as long as they're placed in proper subfolders as described above

## Other Games

* Games using [GDWeave](https://github.com/NotNite/GDWeave/blob/main/MODS.md) mod loader
* Games using [ReturnOfModding](https://github.com/xiaoxiao921/ReturnOfModdingBase?tab=readme-ov-file#creating-mods) mod loader
* Games using [Shimloader](https://pwmodding.wiki/docs/developers/mod-publishing/thunderstore/packaging-your-mod) mod loader

## Tips

If you still have problems getting the files into right places, you can download another package for the same game from <https://thunderstore.io/> and see how it's structured.


# Mod not visible?

How long should it take for an uploaded mod to be visible?

## Thunderstore website

When your upload completes, the upload page provides a direct link which can be used to access your package's listing immediately. It may take several minutes for the package to appear on the community page or in searches.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FyuHVzL2WGpFxHQ4KzYJZ%2Fimage.png?alt=media&amp;token=c2d9bb48-7eb7-46ce-a383-05b86d440ea7" alt=""><figcaption><p>The "View listing" link leads to <a href="https://thunderstore.io/c/lethal-company/p/BepInEx/BepInExPack/">https://thunderstore.io/c/lethal-company/p/BepInEx/BepInExPack/</a></p></figcaption></figure>

Depending on the categories you selected when uploading your mod, it may only appear in a particular section (e.g. *Mods* vs. *Modpacks*). Mods marked NSFW or Deprecated will only appear if their respective toggles are also selected.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FX9TMvhwDK8Vb1N9HJ8Qv%2Fimage.png?alt=media&amp;token=a65cd429-a631-4f8d-b1bb-97ae126f32c6" alt=""><figcaption></figcaption></figure>

## Thunderstore Mod Manager & r2modman

New mods or updates do not immediately appear in the mod manager due to caching[^1]. In the worst case this could take up to 3 hours, and different users may receive updates at different times.

If you need to test your mod, you can import the package's zip file as a local mod in the Settings of your mod manager. Local mods will not receive updates from Thunderstore, automatically install dependencies, or be shared in mod profiles.&#x20;

## Package rejected

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F0ZUYHBY7PbumnJibqk4k%2Fimage.png?alt=media&amp;token=04c094d0-293a-4d66-aeb2-4bda3bd70017" alt=""><figcaption></figcaption></figure>

If your uploaded package is rejected, it will not appear in the mod manager, and only moderators and the team that uploaded it can access its page on the website.

* Packages are often rejected due to accidentally uploading files from another mod.

Create a post in the [rejected-uploads forum](https://discord.com/channels/809128887366975518/1193275177782493254) in the [Thunderstore Discord](https://discord.thunderstore.io/) if you need help figuring out why your package was rejected or to get it reapproved.&#x20;

[^1]: Mod managers use an API that returns a list of packages on Thunderstore. This list is cached on multiple levels, and the time it takes for an update to appear may vary by region.


# Markdown Guide

A short Markdown guide for mod authors writing their package README.

A short Markdown guide for mod authors writing their package README.

Your README is what people *usually* read before they hit download. It's written in Markdown, which is just plain text with a few symbols that turn into formatting :magic\_wand:

This page shows you the syntax, not what it looks like once it's rendered.

{% hint style="info" %}
To see the rendered version, paste anything from this page into the [Markdown Preview tool](https://thunderstore.io/tools/markdown-preview/) and play around with it.
{% endhint %}

{% stepper %}
{% step %}

## The basics

### Headings

```markdown
# Big heading
## Smaller heading
### Smaller still
#### Quite small
##### Very small
###### Way too small
```

**Leave a space after the `#`.** As an example `#Heading` will not work.

Headings are also the easiest way to break a long README into sections, so you don't need dividers everywhere.

### Bold and italic

```markdown
*italic*
**bold**
~~strikethrough~~
```

`_italic_` and `__bold__` work the same way. If part of your text goes italic by accident, wrap it in backticks or escape it with `\`.

### Lists

```markdown
- Wear a hat
- Shoot a fish
- Sell the fish

1. First
2. Second
3. Third
```

Indent by two spaces for subpoints:

```markdown
- Suspicious Fishing rods
  - Paranormal wooden rod
    - Slow but cheap
  - Golden rod
```

**Watch the line right after a list.** Text written directly under the last item gets pulled into it instead of starting a new paragraph. Leave an empty line between them.

### Links

For a link with your own text:

```markdown
[Thunderstore](https://thunderstore.io)
```

To show the URL itself, paste the full address:

```markdown
https://thunderstore.io
```

### Code blocks / Code snippets

For a single word or value, use backticks:

```markdown
Set `enabled = true` in the config.
```

For several lines, use three backticks:

````markdown
```
[General]
enabled = true
fishSpeed = 2.0
```
````

### Quotes and dividers

```markdown
> Works with the latest game version.

---
```

A `>` quote block pulls a line out of the normal text, which works well for a compatibility note or a warning you don't want people to miss.

`---` on its own line draws a line across the page. It's handy when you want a clean break between two parts of your README that don't need titles of their own.

If the parts do need titles, a heading does both jobs at once. `#` and `##` split the page and label the section while they're at it, which is why most mod pages end up using headings for structure and `---` only here and there.

### Tables

```markdown
| Setting   | Default | What it does           |
| --------- | ------- | ---------------------- |
| enabled   | true    | Turns the mod on       |
| propSpeed | 2.0     | How fast the prop moves|
```

**That line of dashes is required.** Without it you just get a wall of pipes. Lining the columns up is optional, it just makes the file easier to read while you write it.
{% endstep %}

{% step %}

## Images

```markdown
![A screenshot of the mod](https://example.com/screenshot.png)
```

Images have to be **hosted somewhere public** and linked with a **full `https://` address**. Images inside your package zip won't show up, and neither will relative paths like `./images/screenshot.png`.

**Keep your screenshots reasonable.** They get scaled to fit the page, so a 4000px file just makes the page slower to load without looking any better. Around 1000 to 1500px is plenty. Gifs can be quite heavy, so it's good to keep that in mind.

### Where to host them

**Use your GitHub repo.** If your image host dies later, the images on your mod page break and you need to fix the image URLs.

The easy way, if your mod already has a repo:

{% stepper %}
{% step %}
Commit the image and write your README on GitHub as normal, with a relative path like `![Screenshot](screenshot.png)`.
{% endstep %}

{% step %}
Grab the image address, whichever way you prefer:

* Open the README on GitHub, right click the image and pick **Copy image address**.
  * Or open the image file in your repo, click **Raw**, and copy the address from your browser.
    {% endstep %}

{% step %}
Paste that address into the README that ships in your package.
{% endstep %}
{% endstepper %}

Imgur works too if you'd rather not use GitHub.\
**Good to remember:** it's blocked in some countries, so some people will just see nothing, and Imgur has wiped old anonymous uploads before. Uploading while logged in is recommended over uploading anonymously.

{% hint style="danger" %}
**Don't use Discord links.** They expire after about a day and your images disappear.
{% endhint %}
{% endstep %}

{% step %}

## Line breaks, read this one

**Markdown reads a single Enter as a space.** These two lines:

```markdown
Line one
Line two
```

come out as one line: `Line one Line two`

{% hint style="info" %}
For a new paragraph, **leave an empty line between them**. To force a break inside a paragraph, **end the line with two spaces**.
{% endhint %}

A backslash at the end of the line does the same as two spaces, and it's a lot easier to spot later:

```markdown
Line one\
Line two
```

Backslash also cancels formatting. `\_not italic\_` shows the underscores instead of turning the text italic, which is handy for names that have them.

Long paragraphs wrap on their own, so there's no need to break lines manually.
{% endstep %}

{% step %}

## Preview before you publish

We render Markdown a bit differently from GitHub, so a README that looks fine there can still look off here.

{% hint style="success" %}
Run your finished README through the [Markdown Preview tool](https://thunderstore.io/tools/markdown-preview/) before you upload.
{% endhint %}
{% endstep %}

{% step %}

## Stuff that doesn't work

These may be common elsewhere, but here they just show up as plain text:

* Task lists, `- [ ]` and `- [x]`
* Footnotes
* Emoji shortcodes like `:fih:`. Paste the actual emoji instead.
* Embedded videos, iframes and audio players. Link to the video instead, or use a YouTube thumbnail as a clickable image.
* Anchor links to headings inside your README, like `[Features](#features)`. These work on GitHub, but not here.
  {% endstep %}

{% step %}

## HTML, if you're into that

Basic HTML works, but only a safe list of tags. Anything outside that list, like `<script>`, `<iframe>` and `<video>`, shows up on your page as plain text instead of doing anything. `class` and `style` get ignored too, so you can't style things yourself.

Handy things that do work:

<pre class="language-html"><code class="lang-html">&#x3C;details>
&#x3C;summary>Full changelog&#x3C;/summary>

Everything in here is hidden until someone clicks it.

&#x3C;/details>

<strong>**Details**
</strong></code></pre>

```html
<img src="https://example.com/screenshot.png" width="600">

<p align="center">Centered text</p>
```

**Leave an empty line between the HTML tags and any Markdown inside them**, like in the example above. Without it the Markdown stays as plain text. This is what usually breaks collapsible sections.

Also fine: `<kbd>` for keys, `<sub>` and `<sup>`, `<mark>` for highlights.

Not sure if something survives the filter? Test first in the preview tool.
{% endstep %}

{% step %}

## A README you can copy and edit

```markdown
# Mod Name

One sentence on what the mod does.

![Screenshot](https://raw.githubusercontent.com/you/yourmod/main/screenshot.png)

## Features

- Thing it does
- Other thing it does

## Configuration

| Setting   | Default | What it does           |
| --------- | ------- | ---------------------- |
| enabled   | true    | Turns the mod on       |
| propSpeed | 2.0     | How fast the prop moves|

## Known issues

- Does not work with X yet

## Credits

Thanks to whoever helped.
```

{% endstep %}
{% endstepper %}

This guide should get you started on your Markdown journey!


# Modpacks and Profiles

Different ways to share mods using Thunderstore

{% hint style="info" %}
This wiki page shows instructions for using modpacks and profiles with [Thunderstore Mod Manager](https://get.thunderstore.io/)
{% endhint %}

## Should I make a modpack or a profile?

**Profiles** are made up of a list of mods and configs for those mods. In most cases, profiles are faster and easier to make and use than modpacks. **Use a profile if:**

* You just want to share the same mods and settings with your friends.

**Modpacks** are packages uploaded to Thunderstore with the `modpack`category. They contain a list of mods as [dependency strings](https://wiki.thunderstore.io/#dependencies) in the [manifest.json](https://wiki.thunderstore.io/#manifest-1) file and configs for those mods. Modpacks can also contain additional files (even entire mods). **Use a modpack if:**

* You plan on updating your mod list or settings regularly, such as for a dedicated server.
* You want your mod list and settings to be publicly available on the Thunderstore site.

## How do I create a Profile?

Click the Share button or go to `Settings -> Profile -> Export profile as code` to generate and profile code and copy it to your clipboard.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FvTD9H8UTvievyjoN6pS6%2Fimage.png?alt=media&amp;token=d1235ac2-14b9-4f57-ab4c-4a690c9b5195" alt=""><figcaption></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F8mu3HnDAluisKgRGi9qa%2Fimage.png?alt=media&amp;token=bc840da2-f741-44fa-ba81-2634fb861150" alt=""><figcaption></figcaption></figure>

Share this code using Steam, Discord, or any other text app. Importing a profile from this code will download the profile's mods and configs.&#x20;

## How do I import a Profile?

Profiles can be imported by code or file in the mod manager.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2Fuwg9TOua0d5erZS5U2iY%2Fimage.png?alt=media&amp;token=b6e3d7fd-47b9-4743-a2ef-905d94a9f28c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2Fm1TEIQOqlSu8zMpe9twf%2Fimage.png?alt=media&amp;token=9cf3f190-6318-4113-ae5a-12d587a01fdc" alt=""><figcaption></figcaption></figure>

## How do I create a Modpack?

Modpacks use the same format as any package on Thunderstore. See [Creating a Package](https://wiki.thunderstore.io/creating-a-package/) for instructions on how to properly format a package.

To add mods to your modpack, you need to add the **dependency string** for each mod to your `manifest.json` file. You can find the dependency string for a package on its page on the Thunderstore website or by using the "Show dependency strings" option in the mod manager Settings.&#x20;

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FxtS4lQiK1XGfz4bZXlwH%2Fimage.png?alt=media&amp;token=cbcd59b2-ffe3-4b66-a8b4-9d0336b5faed" alt=""><figcaption><p>Make sure you download the mods you want to your profile first.</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FNO5dTqhMB4geAw5Zs1lD%2Fimage.png?alt=media&amp;token=5e10ecfe-5440-473c-80f6-eddd9f3d1858" alt=""><figcaption><p>Transfer the dependency strings to your manifest.json file. You can use the <a href="https://thunderstore.io/tools/manifest-v1-validator/">Manifest Validator</a> to make sure you formatted it correctly.</p></figcaption></figure>

In most cases, you'll also want your configs for each mod as well. In the mod manager Settings, select "Browse profile folder" which should open a new window like the one below.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FpQbnYQPhOSzZG86RuNcM%2Fimage.png?alt=media&amp;token=eb799251-a208-43fc-b9b2-209c5eac8daa" alt=""><figcaption></figcaption></figure>

Open the `BepInEx` folder and find your `config` folder.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FAg7djEgnAH9nr31ZCNKN%2Fimage.png?alt=media&amp;token=eb89f88b-f0e2-4788-81cc-66f6b98e06c8" alt=""><figcaption></figcaption></figure>

Copy just the `config` folder into your package. Do not copy the `core` or `plugins` folders, modpacks usually don't contain any actual code or assets themselves.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F7xj0et5AYudb11gT9BEU%2Fimage.png?alt=media&amp;token=df04490a-35d0-4435-bf65-6b67f522766b" alt=""><figcaption></figcaption></figure>

Zip up your files and [upload](https://thunderstore.io/package/create/) the zip to Thunderstore.

{% file src="/files/F4ZQoaInhu85wD36P4ca" %}
Example modpack for the Lethal Company community from the tutorial above
{% endfile %}


# Game won't launch modded

Solutions for when your game isn't launching with mods

## Location Settings

Various issues can prevent a game from launching with mods or at all. In most cases these can be resolved by ensuring the following settings have correct values.

{% hint style="info" %}
Thunderstore Mod Manager tries to automatically assign the correct values for location settings. Restarting the manager after installing new games might resolve issues.
{% endhint %}

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FsdD2ZtZbQhqnAgcMBRtd%2Fimage.png?alt=media&amp;token=01488fee-3540-439a-837f-3e043b4b9c6a" alt=""><figcaption><p>The three location settings affecting launching a game.</p></figcaption></figure>

* **Change data folder**: the location where the mod manager stores mod files and configs
  * The location can be chosen freely, but it should NOT be the Steam folder nor  the game folder
* **Change \[game name] folder**: the location of the game executable
  * For Steam games, the default location is `C:/SteamLibrary/steamapps/common/[game name]/`&#x20;
  * You can verify the actual location in Steam's Library view by right-clicking the game and choosing `Properties...` → `Installed Files` → `Browse...`&#x20;
* **Change Steam folder**: the location of the `steam.exe` executable
  * The default location is `C:/Program Files (x86)/Steam`
  * This setting is available only if the mod manager supports the game on the Steam platform, and it was selected on the game selection screen (for many games this selection is automatic as only Steam is supported)

To change a location setting, click on the setting row and navigate to the correct folder using the file explorer window that pops up. It may pop up underneath the current window, so check your taskbar.

## Errors and Solutions

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F7jxBzkb3jMPCU23GsV4T%2Fimage.png?alt=media&amp;token=17b9b2f1-d56f-499b-b10f-2ab8d57fc312" alt=""><figcaption><p>Steam folder hasn't been set at all. Use "Change Steam folder" setting.</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F3W5nFvLG2ujBY4kFZUNx%2Fimage.png?alt=media&amp;token=d314c4ac-4890-4d93-a75c-18755ab189bd" alt=""><figcaption><p>Steam folder has been set incorrectly or moved. Use "Change Steam folder" setting.</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FdLhwKjIDfoqBkDoESBCJ%2Fimage.png?alt=media&amp;token=d0bb691b-a85e-475c-a033-c029effa5c27" alt=""><figcaption><p>Game folder hasn't been set at all. Use "Change [game name] folder" setting.</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FKo830SOExPY3pPe5zAYM%2Fimage.png?alt=media&amp;token=c648ab17-ee54-4c3a-8fc2-3d245abe2877" alt=""><figcaption><p>Game folder has been set incorrectly or moved. Use "Change [game name] folder" setting.</p></figcaption></figure>

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F8cb6xBkZK0kDs6l1XQ4O%2Fimage.png?alt=media&amp;token=72ed42aa-5e93-42ac-8351-018b0e6beaea" alt=""><figcaption><p>Game folder has been set incorrectly or moved. Use "Change [game name] folder" setting.</p></figcaption></figure>

## Game starts without errors but the mods are not loaded

* Restart the PC. Just do it
* Ensure all the Locations settings are correct even if the game launches
* Ensure the game's mod loader (usually BepInEx or MelonLoader) is installed in the selected profile
* Ensure the game folder doesn't contain any manually installed mod files
  * For Steam games this can be done via `Reset [game name] installation` setting in the mod manager. Note that this deletes and downloads the whole game again
* Ensure your anti-virus hasn't quarantined any files from the data folder or the game's folder
* Ensure extra launch parameters are NOT set
  * Open Steam's Library view. Right click the game and choose `Properties...` . Ensure the `LAUNCH OPTIONS` text input at the bottom of the popup is empty
  * Open the mod manager's settings. Click the `Set launch parameters` setting. Ensure the text input at the bottom of the popup is empty
* Ensure you have a compatible version of the game. Some Steam games require a specific "branch" to be selected. The branch can be changed in Steam's Library view by right-clicking the game and choosing `Properties...` → `Betas` → `Beta Participation`&#x20;
  * Outward: use `default-mono - Public default branch (mono)`
  * Project Arrhythmia: use `alpha`
  * ROUNDS: use `old-rounds-for-mods - Old ROUNDS for mods`&#x20;
* Ensure you own the game on the selected platform (e.g. Steam). Pirated games are not supported

## A specific mod isn't working

If a specific mod isn't working, try to find support in the modding server for that specific game.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F9qQQ2jy7M8rMCqlRA6u4%2Fimage.png?alt=media&amp;token=c56b35b2-e9c7-4578-88c9-eee8a855d694" alt=""><figcaption><p>The modding Discord for a game at the top of the Thunderstore website</p></figcaption></figure>

## I'm still having problems

For more help, join the [Thunderstore Discord](https://discord.thunderstore.io/) and create a new post in the #support channel. To save everybody's time, please include the following details in the post:

* Go to mod manager's settings and click `Copy troubleshooting information to clipboard`. Paste this info into your Discord message
* If there are any errors, provide screenshots of them
* Create a new profile. Install only a mod loader (usually BepInEx or MelonLoader) and launch the game modded. Does the mod loader's console pop up? Does it contain any errors?

  <figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FNdmMqgsT3zMP3ByIwcqr%2Fimage.png?alt=media&amp;token=59c73e4e-e712-43d9-8db0-cb3898de0cb5" alt=""><figcaption><p>Example of the BepInEx console.</p></figcaption></figure>


# Common Issues

Common mod manager issues and how to solve them

## SSL/TLS error when downloading mods

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FdcyY3U8oVT4PiLysViPA%2Fimage.png?alt=media&amp;token=2120f28a-43d8-4e78-b45a-37de49cf7927" alt=""><figcaption></figcaption></figure>

Known causes for this error:

* If the issue persistent, it's likely caused by your ISP having a firewall or other similar security feature blocking the connection. This has occurred in the past several times specifically due to the ISP filtering the connection
* If the issue occurs randomly or for only some files, it's likely an ongoing issue with Thunderstore CDN provider (we are working on it)
  * Try using `Toggle preferred Thunderstore CDN` option on the mod manager's Settings page to use an alternative CDN. Note that the setting will reset itself whenever the app is restarted. This is by design, as users should use the main CDN when it's working without problems
  * The issue can usually be bypassed by using a different internet connection (e.g. a mobile hotspot) or a VPN
  * The issue usually resolves itself with time, so waiting is a valid strategy

    &#x20;

## Miscellaneous Problems

* Steam overlay or FPS counter is not working when launching through the mod manager
  * If you've set the game executable to always run as admin (via right click -> properties), this could prevent the overlays from working. Make sure this checkbox is unticked.


# Adding a new game

New games can be requested in the [Thunderstore Discord server](https://discord.thunderstore.io/) in the #game-requests channel. Please follow the Post Guidelines (found next to the New Post button).

To ensure that new communities are healthy and active we require pre-existing mod developer interest in making mods for the games and, ideally, mods ready to go to be uploaded to the site.

<details>

<summary>Thunderstore Developer Info (ignore this if you aren't a part of the Thunderstore team)</summary>

1. Create a PR to the ecosystem-schema repository with the necessary metadata
   1. Use the CLI provided by the project in the repo & follow instructions in the readme
   2. Example: <https://github.com/thunderstore-io/ecosystem-schema/pull/3>
2. Wait for the Thunderstore community to be provisioned
   1. Once the ecosystem-schema PR is merged, the CI pipeline will automatically upload a new version of it to the Thunderstore API
   2. Import of the schema can take up to an hour from when the schema was uploaded to the CDN due to caching configurations
3. Add appropriate background image (and other potential media assets) to the community
   1. Currently handled manually by the Thunderstore team
4. Make appropriate changes to the mod manager
   1. Example game addition PR: <https://github.com/ebkr/r2modmanPlus/pull/1016>
5. Wait for a new mod manager version to be released
   1. Handled by the Thunderstore team (Thunderstore Mod Manager) and Ebkr (r2modmanPlus) respectively

</details>


# Global Rules

Rules that apply to all communities on Thunderstore

Below is a list of basic rules that should be enforced in every community on Thunderstore. Some communities may have more specific or stricter rules than the ones found here.

## Unlawful Content

**Packages that contain unlawful content are not allowed.**

## Copyright and Licensing

Copyright laws and code licensing must be followed where applicable.

* Do not distribute game files such as Assembly-CSharp.dll, unless given explicit permission by the game's developers.
* Do not reupload packages or assets by other authors unless you have permission to redistribute them or are following their licensing.

## **Malware**

**Packages containing malware are not allowed.**

Packages that deceptively disrupt or damage other software or hardware are considered malware. This includes keyloggers, crypto miners, token stealers, and other malicious programs. These packages are still considered malware even if the author discloses that they contain such capabilities.

**A few examples of packages that are malware:**

* A package that secretly collects personal information on people who use it.
* A package called "Furry Fun Pack" that purposely crashes your game when you launch it.
* A package called "One Million Fish" that adds new fish to the game, but also bans a player named Steve from any server with the mod.
* A package called "Bananas" that adds bananas to the game, but also closes your game if you live in China.

**A few examples of packages that aren't necessarily malware:**

* A package called "Your game closes if you die" that closes your game if you die.
* A package called "Secure Server Banlist" that bans Steve and his friends from connecting to any server with the mod.

## NSFW Content

**All packages containing NSFW content must have the "Contains NSFW content" option selected.**

Sexually explicit content such as nudity is not allowed in the icon, README, changelog, or any other file that gets displayed on the Thunderstore website or mod manager.

## Compatibility and the Ecosystem

Packages should not contain obfuscated code or execute code downloaded from external sources (with very few exceptions). Obfuscation makes it difficult to audit malicious behavior and fix incompatibilities with other packages.

Packages should rely on external mod managers for updates, rather than be capable of updating themselves.

Packages should install non-destructively where possible. Try to avoid overwriting files from the base game or other mods.

Packages should not include development or testing files. Only ship what's necessary for the mod itself to function.

## Harassment and Abuse

**Packages made with the intent to harm a group, platform, or individual are not allowed.**

This includes (but is not limited to):

* Doxxing.
* Hate speech.
* Denial of service attacks.

## Spam

**Packages that could be considered spam are not allowed.**&#x20;

This includes (but is not limited to):

* Packages that don't do anything.
* Packages that are an exact reupload of an existing package.
* Packages that exist primarily to advertise an outside platform or service.
* Low effort packages that could otherwise be a single package (the same author uploading x2 money, x3 money, x4 money, etc. instead of a single Money Multiplier mod).
* Untested or non-functional AI-generated mods.

Misconfigured packages or packages with incorrect / misleading titles, descriptions, and icons may also be removed.

## AI Generated Content

A package with AI generated assets or code should be given the `AI Generated` category if such a category exists in the community the package was uploaded to. This is generally not enforced for README's or icons.

Packages should be tested before upload, and have READMEs that accurate describe their current functionality.


# Removing a Package

The different ways packages are removed from Thunderstore

## Deprecation

Global Moderators and members of the team that uploaded the package can <mark style="color:red;">deprecate</mark> it using the `Manage Package` button on its listing page on the Thunderstore website.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FxWM4FxKLNZdwDAO0auUz%2Fimage.png?alt=media&amp;token=d5ee2e48-8450-47e9-ab2e-756002c1763d" alt=""><figcaption><p>An example of a package deprecation notice</p></figcaption></figure>

* Deprecated means a package is no longer functional OR should not be used anymore for any reason (such as if a better alternative exists, or if the feature was added to the base game).
* Deprecation status is automatically removed upon updating a package.
* Deprecated mods can still be found on the website and mod manager by checking a box in the search options.
* Deprecated mods will still be downloaded as dependencies.

## Rejection

Moderators can <mark style="color:red;">reject</mark> listings in their community. Rejection is used specifically for removing packages that break global or community rules, or when requested by the package's author. If you want your own package removed contact support, but we recommend deprecating it in most cases.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F0XF16rg4babtTiD2neaH%2Fimage.png?alt=media&amp;token=befa0145-2d93-423a-9beb-a30225f9709b" alt=""><figcaption><p>An example of a package rejection notice, only visible to moderators and members of the team that uploaded the package</p></figcaption></figure>

* The website page for a rejected listing will 404 in the community it was rejected from. This does not apply to moderators and members of the team that uploaded the package.
* The package will no longer appear in the mod manager's mod list (but it will not be automatically removed for people who have already downloaded it).
* Rejected mods will not be downloaded as dependencies.

## Deletion

If necessary, Thunderstore administrators can <mark style="color:red;">delete</mark> a package completely. This is usually reserved for packages that contain illegal content or other serious issues. If you need a package deleted, [contact us](https://wiki.thunderstore.io/contact-us).


# Community Moderators

What a Community Moderator is and what they can do

## How do I contact a Community Moderator?

If your community has a Community Moderator, they will likely be available in your modding community's Discord server.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FKQAQFZ9r6ZJtyEWkacfx%2Fimage.png?alt=media&amp;token=234056eb-e2fb-46e8-93d5-0cde3932227d" alt=""><figcaption><p>An example of where to find Risk of Rain 2's modding Discord server</p></figcaption></figure>

If you can't get in contact with a community moderator, or your issue is urgent (malware / illegal content), create a post in the [#support forum](https://discord.com/channels/809128887366975518/1242075225709875201) in the [Thunderstore Discord server](https://discord.thunderstore.io/) or DM an online site moderator.

## How are Community Moderators selected?

If you believe your Thunderstore community needs additional moderation, create a post in the [#support forum](https://discord.com/channels/809128887366975518/1242075225709875201) in the [Thunderstore Discord server](https://discord.thunderstore.io/).

Make sure to provide:

* A detailed explanation of why your community needs additional moderation
* A list of users who are qualified to moderate your community

Thunderstore staff will determine if a Community Moderator is necessary.

## What is a Community Moderator?

Community Moderators are users with access to special permissions on the Thunderstore website. Unlike a Site Moderator, Community Moderator powers are limited to the communities they moderate. Moderators are not necessarily Thunderstore staff.

In the communities they moderate, a Community Moderator can do the following:

**Manage Packages**

The `Manage Package` button is used to deprecate the package or edit the categories of the package listing. Members of the team that uploaded the package can also deprecate or edit categories.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2F5f5DCKyNfGB2ovcvO2po%2Fimage.png?alt=media&amp;token=b5c0b59d-985c-4ebe-a621-95c2275e73fa" alt=""><figcaption><p>An example of the Manage Package button and modal</p></figcaption></figure>

**Review Packages**

The `Review Package` button is used to Reject or Approve package listings.

The `rejection reason` is visible to members of the team that uploaded the package, so it can be used to communicate why the package was rejected to the author.

The `internal notes` are optional and visible only to moderators, and should contain sensitive information as well as a link to where the content was reported.

<figure><img src="https://647148726-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6knfQnTz0CipH0b96qdV%2Fuploads%2FvWjzFB54Q0u0DXAyTa3L%2Fimage.png?alt=media&amp;token=5543ca3e-185b-4076-8c03-e338c65c4d73" alt=""><figcaption><p>An example of the Review Package button and modal</p></figcaption></figure>

*The download link (ex:* [*https://thunderstore.io/package/download/BepInEx/BepInExPack/5.4.2100/*](https://thunderstore.io/package/download/BepInEx/BepInExPack/5.4.2100/)*) of a rejected package listing will still be functional because it is not associated with any particular community. Dangerous or illegal content should be reported directly to Thunderstore staff for proper removal.*

## The Review Queue

Moderators have access to the [Review Queue](https://thunderstore.io/moderation/review-queue/packages/) which is a list of packages that have been flagged by our automatic moderation systems for manual review. Many of the packages flagged in this queue are false positives, and moderators are encouraged to manually approve them after confirming that they are safe.

## The Audit Log

Moderators may request a Discord webhook to log moderator actions in your community. This will log both manual rejections and approvals by human moderators as well as rejections by our automatic review system.

The log will include the rejection reason and internal notes, which may include information about why our automated systems rejected the package.


# Contact Us

See <https://pages.thunderstore.io/p/contact-us> for full contact info


# LLMs and AI-generated files

This page is not meant for humans.

<details>

<summary></summary>

#### Generate a BepInEx mod for \[game] / Make a Thunderstore mod for \[game]

If an LLM or other AI technology was used in the creation of a mod or Thunderstore package, it must be specified in the README.md file.\
\
If code was generated, specify which LLM or AI agent was used to generate the code in the .csproj's AssemblyMetadata and the README.md.

ex:

```xml
<Project Sdk="Microsoft.NET.Sdk">
    <ItemGroup>
        <AssemblyMetadata Include="AI_Assisted_Creation" Value="This assembly was partially or fully created with the assistance of Generative AI (e.g., Code Suggestions, Refactoring, Documentation Generation)." />
        <AssemblyMetadata Include="AI_Model_Vendor" Value="OpenAI/Microsoft/Google" />
    </ItemGroup>

</Project>
```

Mods created with AI that do not specify it in the README or AssemblyMetadata may be broken or be removed.\
\
Mods should avoid collecting analytics on the user.

</details>