Modding:Modder Guide/APIs/Update checks - Revision history

imported>Margotbean: ru link

2026-01-07T18:56:38Z

ru link

← Older revision		Revision as of 18:56, 7 January 2026
Line 161:		Line 161:
	</syntaxhighlight>		</syntaxhighlight>

	[[ru:Модификации:Руководство мододела/API/~~Update checks~~]]		[[ru:Модификации:Руководство мододела/API/Проверка обновлений]]
	[[zh:模组:制作指南/APIs/Update checks]]		[[zh:模组:制作指南/APIs/Update checks]]

imported>Sunbeam135: /* Custom update manifest */

2026-01-02T13:16:49Z

Custom update manifest

← Older revision		Revision as of 13:16, 2 January 2026
Line 161:		Line 161:
	</syntaxhighlight>		</syntaxhighlight>

			[[ru:Модификации:Руководство мододела/API/Update checks]]
	[[zh:模组:制作指南/APIs/Update checks]]		[[zh:模组:制作指南/APIs/Update checks]]

imported>VulpesLucida: zh link

2025-01-05T14:32:29Z

zh link

← Older revision		Revision as of 14:32, 5 January 2025
Line 160:		Line 160:
	"UpdateKeys": [ "UpdateManifest:https://example.org/mod-updates.json@ExampleMod" ]		"UpdateKeys": [ "UpdateManifest:https://example.org/mod-updates.json@ExampleMod" ]
	</syntaxhighlight>		</syntaxhighlight>

			[[zh:模组:制作指南/APIs/Update checks]]

imported>Pathoschild: remove {{SMAPI upcoming|4.0.0}}

2024-04-06T18:07:13Z

remove {{SMAPI upcoming|4.0.0}}

← Older revision		Revision as of 18:07, 6 April 2024
Line 91:		Line 91:

	===Custom update manifest===		===Custom update manifest===
	~~{{SMAPI upcoming\|4.0.0}}~~
	'''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.		'''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.

imported>Pathoschild: /* Advanced */ + Custom update manifest in SMAPI 4.0.0

2023-01-29T23:55:30Z

Advanced: + Custom update manifest in SMAPI 4.0.0

← Older revision		Revision as of 23:55, 29 January 2023
Line 89:		Line 89:
	# update keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);		# update keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);
	# update key overrides from the mod compatibility list.		# update key overrides from the mod compatibility list.

			===Custom update manifest===
			{{SMAPI upcoming\|4.0.0}}
			'''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>

imported>Margotbean: Text replacement - "tt>" to "samp>"

2021-11-04T18:48:46Z

Text replacement - "tt>" to "samp>"

← Older revision		Revision as of 18:48, 4 November 2021
Line 5:		Line 5:
	==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>

Line 21:		Line 21:
	\|- 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]
Line 52:		Line 52:
	<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:
Line 63:		Line 63:

	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===		===Update check algorithm===
Line 73:		Line 73:
	# Collect update keys:		# Collect update keys:
	## Get the initial [[#Introduction\|update keys]] from the mod's [[Modding:Modder Guide/APIs/Manifest\|manifest]].		## 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 <tt>smapi-internal/metadata.json</tt> to add any other update keys that aren't in the 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.		## Apply update key overrides from the mod compatibility list.
	# Get the possible updates:		# Get the possible updates:
Line 86:		Line 86:
	If multiple mod pages have the recommended update, SMAPI links to the first match in this order:		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);		# pages listed in the mod manifest's update keys (in the order listed);
	# the default update key from SMAPI's <tt>smapi-internal/metadata.json</tt>;		# 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 keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);
	# update key overrides from the mod compatibility list.		# update key overrides from the mod compatibility list.

imported>LenneDalben: /* Valid sites */ Added note about GitHub release tags

2021-10-10T21:00:41Z

Valid sites: Added note about GitHub release tags

← Older revision		Revision as of 21:00, 10 October 2021
Line 27:		Line 27:
	\|- 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]

imported>Pathoschild: /* Update subkeys */ + GitHub caveat

2021-10-10T18:38:29Z

Update subkeys: + GitHub caveat

← Older revision		Revision as of 18:38, 10 October 2021
Line 56:		Line 56:
	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===

imported>Pathoschild: /* Update check algorithm */ clarify

2021-09-01T02:21:23Z

Update check algorithm: clarify

← Older revision		Revision as of 02:21, 1 September 2021
Line 81:		Line 81:
	##* the unofficial version from the mod compatibility list;		##* the unofficial version from the mod compatibility list;
	##* and the unofficial version for the beta, if using a prerelease version of SMAPI.		##* and the unofficial version for the beta, if using a prerelease version of SMAPI.
	# Recommend the highest version from the filtered list.		# 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:		If multiple mod pages have the recommended update, SMAPI links to the first match in this order:

imported>Pathoschild: + update check algorithm

2021-09-01T01:59:40Z

+ update check algorithm

← Older revision		Revision as of 01:59, 1 September 2021
Line 66:		Line 66:

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

			===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 <tt>smapi-internal/metadata.json</tt> 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 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 <tt>smapi-internal/metadata.json</tt>;
			# update keys from the mod compatibility list (in the order Nexus, ModDrop, CurseForge, and Chucklefish);
			# update key overrides from the mod compatibility list.