translators
8,404
edits
Changes
remove {{SMAPI upcoming|4.0.0}}
==Introduction==
==Introduction==
===Enable update checks===
===Enable update checks===
You can add ''update keys'' to [[../Manifest|your <tt>manifest.json</tt>]] to enable update checks. An update key tells SMAPI where the mod page is. For example, <code>Nexus:2400</code> means {{Nexus mod|2400|mod ID 2400 on Nexus}}:
You can add ''update keys'' to [[../Manifest|your <samp>manifest.json</samp>]] to enable update checks. An update key tells SMAPI where the mod page is. For example, <code>Nexus:2400</code> means {{Nexus mod|2400|mod ID 2400 on Nexus}}:
<syntaxhighlight lang="json">"UpdateKeys": [ "Nexus:2400" ]</syntaxhighlight>
<syntaxhighlight lang="json">"UpdateKeys": [ "Nexus:2400" ]</syntaxhighlight>
|- valign="top"
|- valign="top"
| [https://community.playstarbound.com/resources/categories/stardew-valley.22/ Chucklefish]
| [https://community.playstarbound.com/resources/categories/stardew-valley.22/ Chucklefish]
| '''(Deprecated)''' Make sure you have a mod release page (with a URL containing <tt>/resources/</tt> instead of <tt>/thread/</tt>) and it has a [http://semver.org/ semantic version], then specify the mod ID (the number in the mod page URL). <syntaxhighlight lang="javascript">"UpdateKeys": [ "Chucklefish:4250" ]</syntaxhighlight>
| '''(Deprecated)''' Make sure you have a mod release page (with a URL containing <samp>/resources/</samp> instead of <samp>/thread/</samp>) and it has a [http://semver.org/ semantic version], then specify the mod ID (the number in the mod page URL). <syntaxhighlight lang="javascript">"UpdateKeys": [ "Chucklefish:4250" ]</syntaxhighlight>
|- valign="top"
|- valign="top"
| [https://www.curseforge.com/stardewvalley CurseForge]
| [https://www.curseforge.com/stardewvalley CurseForge]
|- valign="top"
|- valign="top"
| [https://github.com/ GitHub]
| [https://github.com/ GitHub]
| Make sure your [https://help.github.com/articles/creating-releases/ GitHub project has at least one release] and the latest release's tag is a [http://semver.org/ semantic version], then specify your GitHub username and project name. <syntaxhighlight lang="javascript">"UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ]</syntaxhighlight> SMAPI will get the version from the release tag.
| Make sure your [https://help.github.com/articles/creating-releases/ GitHub project has at least one release] and the latest release's tag is a [http://semver.org/ semantic version], then specify your GitHub username and project name. <syntaxhighlight lang="javascript">"UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ]</syntaxhighlight> 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.
|- valign="top"
|- valign="top"
| [https://www.moddrop.com/stardew-valley/ ModDrop]
| [https://www.moddrop.com/stardew-valley/ ModDrop]
<syntaxhighlight lang="json">"UpdateKeys": [ "Nexus:2400@GeodeCrusher" ]</syntaxhighlight>
<syntaxhighlight lang="json">"UpdateKeys": [ "Nexus:2400@GeodeCrusher" ]</syntaxhighlight>
When SMAPI fetches available versions from the page, it will only consider files that have <tt>@GeodeCrusher</tt> ('''including <tt>@</tt>''') somewhere in the title or description.
When SMAPI fetches available versions from the page, it will only consider files that have <samp>@GeodeCrusher</samp> ('''including <samp>@</samp>''') somewhere in the title or description.
Caveats:
Caveats:
* If no files match the subkey, SMAPI will ignore the subkey and perform a normal update check.
* 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.
* 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===
===Disable update checks locally===
To disable update checks...
To disable update checks...
* For SMAPI and all mods: edit the <tt>smapi-internal/config.json</tt> file and set <tt>CheckForUpdates</tt> to false. You'll no longer be notified about newer versions of SMAPI or installed mods, so this is not recommended.
* For SMAPI and all mods: edit the <samp>smapi-internal/config.json</samp> file and set <samp>CheckForUpdates</samp> 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 <tt>smapi-internal/config.json</tt> file and add the mod ID to the <tt>SuppressUpdateChecks</tt> field.
* For a specific mod: edit the <samp>smapi-internal/config.json</samp> file and add the mod ID to the <samp>SuppressUpdateChecks</samp> field.
Note that edits to <tt>smapi-internal/config.json</tt> will be lost when you update SMAPI. See the instructions at the top of that file to create a permanent config file.
Note that edits to <samp>smapi-internal/config.json</samp> 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 initial [[#Introduction|update keys]] from the mod's [[Modding:Modder Guide/APIs/Manifest|manifest]].
## Match the mod ID with the [[Modding:Mod compatibility|mod compatibility list]] and <samp>smapi-internal/metadata.json</samp> to add any other update keys that aren't in the manifest.
## Apply update key overrides from the mod compatibility list.
# Get the possible updates:
## Collect versions from every matched update key (see [[#Valid sites|''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 <samp>smapi-internal/metadata.json</samp>;
# update keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);
# update key overrides from the mod compatibility list.
===Custom update manifest===
'''This is highly specialized''' and supports specific edge cases (like mods which only exist in a shared GitHub repository or custom website). Most mods should use normal update keys instead.
An ''update manifest'' is a JSON file hosted on a website, which the SMAPI servers can download to get info about mods which aren't available on a more usual site like Nexus. For example, this manifest shows info about a mod which is only hosted on a custom website:
<syntaxhighlight lang="js">
{
"Format": "4.0.0",
"Mods": {
"ExampleMod": {
"Name": "Example Mod",
"ModPageUrl": "https://example.org/mods/example-mod",
"Versions": [
{ "Version": "1.0.0" }
]
}
}
}
</syntaxhighlight>
Here are the expected fields (all required unless noted otherwise):
{| class="wikitable"
|-
! field
! usage
|-
| <samp>Format</samp>
| The version of the manifest format (currently <samp>4.0.0</samp>). This is used to parse older manifests correctly if later versions of SMAPI change the format.
|-
| <samp>Mods</samp>
| The mods for which info is provided. Any number of mods can be listed.
This consists of a string → model lookup, where...
* The key is the update subkey (see details below the table).
* The value is a model with the fields listed below.
Each mod has these fields:
{| class="wikitable"
|-
! field
! usage
|-
| <samp>Name</samp>
| The human-readable display name for the mod.
|-
| <samp>ModPageUrl</samp>
| The URL of the page from which the player can download updates.
|-
| <samp>Versions</samp>
| The versions available to download. Any number of versions can be listed, and they'll be compared to the player's installed version using the [[#Update check algorithm|usual update check algorithm]].
This consists of a list of models with these fields:
{| class="wikitable"
|-
! field
! usage
|-
| <samp>Version</samp>
| The semantic version number.
|-
| <samp>ModPageUrl</samp>
| ''(Optional)'' The URL of the page from which the player can download this update, if different from the <samp>ModPageUrl</samp> for the mod itself.
|}
|}
|}
To use the manifest, a mod must add an [[#Enable update checks|update key]] in the form <samp>UpdateManifest:{{t|full URL to json file}}@{{t|mod key}}</samp>. If the example above was hosted at <samp><nowiki>https://example.org/mod-updates.json</nowiki></samp>, then its update key would look like this:
<syntaxhighlight lang="js">
"UpdateKeys": [ "UpdateManifest:https://example.org/mod-updates.json@ExampleMod" ]
</syntaxhighlight>