Modding:Modder Guide/APIs/Update checks

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

Every SMAPI mod or content pack can benefit from automatic update checks, so the player sees an alert when a new version is available. This helps ensures players always have the latest version of your mod, which improves their experience and reduces support requests.

Introduction

Enable update checks

You can add update keys to your manifest.json to enable update checks. An update key tells SMAPI where the mod page is. For example, Nexus:2400 means mod ID 2400 on Nexus:

"UpdateKeys": [ "Nexus:2400" ]

If you have multiple update keys, SMAPI will check them all and show an alert for the latest version it finds. (If multiple sites have the latest version, it will link to the earlier one in the list.)

"UpdateKeys": [ "Chucklefish:4250", "Nexus:541", "GitHub:Pathoschild/LookupAnything" ]

(SMAPI also fetches mod info from the mod compatibility list, so mods on that page may get update checks even without update keys. You should still add update keys to your manifest in case that changes, and to support mod managers and other tools.)

Valid sites

Here are the supported mod sites:

mod site	description
Chucklefish	(Deprecated) Make sure you have a mod release page (with a URL containing /resources/ instead of /thread/) and it has a semantic version, then specify the mod ID (the number in the mod page URL). "UpdateKeys": [ "Chucklefish:4250" ]
CurseForge	Make sure the latest file's display name contains a semantic version at the end, with a space before the version and optional file extension. For example, SMAPI will recognise the version in these display names: 1.3.0, Example Mod 1.10, Example Mod 1.10.0-prerelease.zip. "UpdateKeys": [ "CurseForge:309243" ]
GitHub	Make sure your GitHub project has at least one release and the latest release's tag is a semantic version, then specify your GitHub username and project name. "UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ] SMAPI will get the version from the release tag.
ModDrop	Make sure the mod page has a semantic version, then specify the mod ID (the number in the mod page URL). "UpdateKeys": [ "ModDrop:123338" ] SMAPI will get the version from files under 'Main Versions'.
Nexus Mods	Make sure the Nexus mod has a semantic version, then specify the mod ID (the number in the mod page URL). When creating a new mod on Nexus, the ID is added to the URL after the first step, before you need to upload the file. "UpdateKeys": [ "Nexus:541" ] SMAPI will get the version from the mod, 'main files' downloads, or 'optional files' downloads (whichever is higher).

Advanced

Beta versions

A prerelease version (often called an alpha or beta) has a prerelease tag in the version number. For example, 1.0.0-beta.5 is a prerelease version of an upcoming 1.0.0.

If you have both prerelease and non-prerelease versions, update checks depend on the player's installed mod version:

• Stable channel: players with a non-prerelease version installed only see update alerts for non-prerelease versions (unless the main mod version is prerelease).
• Beta channel: players with a prerelease version see update alerts for any newer version, whether prerelease or non-prerelease.

For example, let's say your mod has two current versions: 1.7.0 and 2.0.0-beta. A player who has 1.6.0 installed would see an update alert for 1.7.0, and a player with 1.6.1-beta would see an update alert for 2.0.0-beta.

Update subkeys

The following describes the upcoming SMAPI 3.6, and may change before release.

SMAPI assumes each mod page is about a single mod, so the highest file version is the latest one. That means having multiple mods on the same page can cause false update alerts. For example, let's say you have one Nexus page with two different mods in the downloads: Geode Crusher (version 1.0.5) and Diamond Crusher (version 2.1.0). If a player has the latest version of Geode Crusher installed, they would always get update alerts for version 2.1.0 even though that's a different mod.

You can add an update subkey at the end of your normal update key after @:

"UpdateKeys": [ "Nexus:2400@GeodeCrusher" ]

When SMAPI fetches available versions from the page, it will only consider files that have @GeodeCrusher somewhere in the title or description.

Caveats:

• If no files match the subkey, SMAPI will ignore the subkey and perform a normal update check.
• For mods on CurseForge, SMAPI won't see subkeys in the file description since that's not available through the API.

Disable update checks locally

SMAPI checks for updates in the background, so disabling update checks has zero effect on load times.

To disable update checks...

• For SMAPI and all mods: edit the smapi-internal/config.json file and set CheckForUpdates to false. You'll no longer be notified about newer versions of SMAPI or installed mods, so this is not recommended.
• For a specific mod: edit the smapi-internal/config.json file and add the mod ID to the SuppressUpdateChecks field.

Note that edits to smapi-internal/config.json will be lost when you update SMAPI. See the instructions at the top of that file to create a permanent config file.