Skip to content

Installing mods locally

Cade Ayres edited this page Sep 28, 2021 · 10 revisions

Users

As a user, you may want to install mods locally due to:

  • The mod not being on Thunderstore.
  • You can't connect to Thunderstore.

To install a mod locally, you have just need to select your profile and locate the "Install local mod" option in the settings as shown in the image below:

install

Developers

There are several ways that the manager can work out the necessary information for your import.

Please ensure that the author name is correct in all cases as these are used to resolve your import to any potential future TS uploads. If a release version is higher than the imported version, then all users will be prompted that an update is available.

Regarding how the manager installs the mods, please see: https://github.com/ebkr/r2modmanPlus/wiki/Structuring-your-Thunderstore-package

File names

The easiest option is to distribute your DLL or zip using a specific naming convention. This is either: Author-ModName-Version, ModName-Version, or ModName. The hyphens can be replaced with underscores if preferred: Author_ModName_Version, ModName_Version, or ModName.

This is great for a quick solution to get your mod imported, however lacks information such as dependencies, descriptions, and an icon.

Manifest V1 (Thunderstore)

Another alternative is to use a manifest.json in the root of your zip. The spec matches the current V1 implementation of Thunderstore's format. This allows you to include dependencies and a description.

See the latest specifications for the manifest here: https://thunderstore.io/package/create/

Note that there is no way to determine the author field, so the FILE NAMES section above applies partially here too.

Manifest V1 (Thunderstore) + author field

Improving upon the V1 specification, if you add an "author": "AuthorName" field to your manifest.json file, you can ignore the FILE NAMES naming conventions entirely as all information is stored within the manifest.

This is currently the recommended approach for distributing early access builds

Manifest V2 (r2modman only, deprecated, still working)

Similar to the manifest V1, this specification was originally intended to be Thunderstore's successor to manifest V1, however this was a long time ago and the required information has changed since it was first proposed. This has moved this import method into a deprecated state.

Here is an example for the manifest specification:

{
    "ManifestVersion": 2,
    "AuthorName": "Author",
    "Name": "Author-DisplayName",
    "DisplayName": "DisplayName",
    "Version": "1.0.0",
    "Licence": "",
    "WebsiteURL": "",
    "Description": "",
    "GameVersion": "N/A",
    "Dependencies": [],
    "OptionalDependencies": [],
    "Incompatibilities": [],
    "NetworkMode": "both",
    "PackageType": "mod",
    "InstallMode": "managed",
    "Loaders": [
        "bepinex"
    ],
    "ExtraData": {}
}

All fields are case sensitive and must match exactly. Incorrect/missing fields may break the manager on import.

Information within this example must be changed to match.

During development

Importing is a great option to test how the manager installs your mod. Unofrtunately it can be quite tedious to reimport each time. Fortunately there's a much better solution.

You can import your mod once as you would if you were distributing a build. Once that's complete, you can go to Settings -> Browse profile folder and locate your mod (usually /BepInEx/plugins/<Author-ModName>/). Simply replace any assets and DLLs within this folder with a symlink to your build output targets.