Modding:Modder Guide/APIs/Update checks
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.
Enable update checks
"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.)
Here are the supported mod sites:
|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: |
"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. |
SMAPI will get the version from the release tag. Note that with the way GitHub release tags work, they do not support "monorepos", when multiple mods are on the same repository with different version numbers.
"UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ]
|ModDrop||Make sure the mod page has a semantic version, then specify the mod ID (the number in the mod page URL). |
SMAPI will get the version from files under 'Main Versions'.
"UpdateKeys": [ "ModDrop:123338" ]
|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. |
SMAPI will get the version from the mod, 'main files' downloads, or 'optional files' downloads (whichever is higher).
"UpdateKeys": [ "Nexus:541" ]
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
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:
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
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:[email protected]" ]
When SMAPI fetches available versions from the page, it will only consider files that have @GeodeCrusher (including @) somewhere in the title or description.
- 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 CurseForge API.
- For mods on GitHub, subkeys don't really do anything since only the latest release is fetched.
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.
Update check algorithm
Here's how SMAPI decides which update alerts to show in the SMAPI console for a mod:
- Collect update keys:
- Get the possible updates:
- Collect versions from every matched update key (see valid sites for which versions are used).
- Filter the list of versions to...
- the main mod version;
- the optional prerelease version if the player has a beta version of SMAPI, or they have an older prerelease mod version installed, or the installed version failed to load;
- the unofficial version from the mod compatibility list;
- and the unofficial version for the beta, if using a prerelease version of SMAPI.
- Recommend the highest version from the filtered list (if newer than the installed version).
If multiple mod pages have the recommended update, SMAPI links to the first match in this order:
- pages listed in the mod manifest's update keys (in the order listed);
- the default update key from SMAPI's smapi-internal/metadata.json;
- update keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);
- update key overrides from the mod compatibility list.