Version Checker - Revision history

ChampionAsh5357: Update to 1.19

2022-06-11T16:48:38Z

Update to 1.19

SciWhiz12: replace 'update checker' to 'version checker'

2021-01-07T12:20:46Z

replace 'update checker' to 'version checker'

SciWhiz12: SciWhiz12 moved page Update Checker to Version Checker: rename to be closer to the actual class name

2021-01-07T12:13:52Z

SciWhiz12 moved page Version Checker to Version Checker: rename to be closer to the actual class name

SciWhiz12: rewrite the page, adding more information

2021-01-07T11:58:37Z

rewrite the page, adding more information

SciWhiz12: SciWhiz12 moved page Using the Forge Update Checker to Update Checker without leaving a redirect: Shorten page title, as the old one was too large and unnecessary

2020-10-24T23:12:01Z

SciWhiz12 moved page Using the Forge Update Checker to Version Checker without leaving a redirect: Shorten page title, as the old one was too large and unnecessary

Unbekannt: Inital Import from dokuwiki

2020-10-24T12:50:47Z

Inital Import from dokuwiki

New page

= Forge Update Checker =

Forge provides a very lightweight opt-in update-checking framework. All it does is check for updates, then show a flashing icon on the Mods button of the main menu and mod list if any mods have an available update, along with the respective changelogs. It does not download updates automatically.

== Getting Started ==

The first thing you want to do is specify the <code><nowiki>updateJSONURL</nowiki></code> parameter in your <code><nowiki>mods.toml</nowiki></code> file. The value of this parameter should be a valid URL pointing to an update JSON file. This file can be hosted on your own web server, or on GitHub, or wherever you want, as long as it can be reliably reached by all users of your mod.

== Update JSON format ==

The JSON itself has a relatively simple format, given as follows:

<syntaxhighlight lang="json">
{
"homepage": "<homepage/download page for your mod>",
"<mcversion>": {
"<modversion>": "<changelog for this version>",
'' List all versions of your mod for the given Minecraft version, along with their changelogs
...
},
...
"promos": {
"<mcversion>-latest": "<modversion>",
'' Declare the latest "bleeding-edge" version of your mod for the given Minecraft version
"<mcversion>-recommended": "<modversion>",
'' Declare the latest "stable" version of your mod for the given Minecraft version
...
}
}
</syntaxhighlight>

This is fairly self-explanatory, but some notes:

* The link under <code><nowiki>homepage</nowiki></code> is the link the user will be shown when the mod is outdated.
* Forge uses an internal algorithm to determine whether one version String of your mod is “newer” than another. Most versioning schemes should be compatible, but see the <code><nowiki>ComparableVersion</nowiki></code> class if you are concerned about whether your scheme is supported. Adherence to [[Semantic Versioning]] is highly recommended.
* The changelog string can be separated into lines using <code><nowiki>\n</nowiki></code>. Some prefer to include a abbreviated changelog, then link to an external site that provides a full listing of changes.
* Manually inputting data can be chore. You can configure your <code><nowiki>build.gradle</nowiki></code> to automatically update this file when building a release, as Groovy has native JSON parsing support. Doing this is left as an exercise to the reader.
* Some examples can be found here for [https://cadiboo.github.io/projects/nocubes/update.json nocubes], [https://github.com/Corail31/tombstone_lite/blob/master/update.json Corail Tombstone] and [https://github.com/Aeltumn/Chisels-and-Bits-2/blob/master/update.json Chisels & Bits 2].

== Retrieving Update Check Results ==

You can retrieve the results of the Forge Update Checker using <code><nowiki>VersionChecker.getResult(ModInfo)</nowiki></code>. The returned object has a field <code><nowiki>status</nowiki></code> which indicates the status of the version check. Example values: <code><nowiki>FAILED</nowiki></code> (the version checker couldn’t connect to the URL provided), <code><nowiki>UP_TO_DATE</nowiki></code> (the current version is equal to or newer than the latest stable version), <code><nowiki>OUTDATED</nowiki></code> (there is a new stable version), <code><nowiki>BETA_OUTDATED</nowiki></code> (there is a new unstable version), or <code><nowiki>BETA</nowiki></code> (the current version is equal to or newer than the latest unstable version). The status will be <code><nowiki>PENDING</nowiki></code> if the result requested has not finished yet; in that case, you should try again in a little bit. Otherwise, the returned object will also have the target version and any changelog lines, as specified in <code><nowiki>update.json</nowiki></code>. You can obtain your own <code><nowiki>ModContainer</nowiki></code> to get the <code><nowiki>ModInfo</nowiki></code> of (with <code><nowiki>ModContainer#getModInfo()</nowiki></code>) to pass to this method using <code><nowiki>ModLoadingContext.get().getActiveContainer()</nowiki></code> inside your constructor, <code><nowiki>ModList.get().getModContainerById(<your modId>)</nowiki></code> or <code><nowiki>ModList.get().getModContainerByObject(<your mod instance>)</nowiki></code>; or any other mod’s <code><nowiki>ModContainer</nowiki></code> using <code><nowiki>ModList.get().getModContainerById(<modId>)</nowiki></code>.

@@ Line 30: / Line 30: @@
 * <code>BETA_OUTDATED</code> - There is no recommended version, and the currently installed version is behind the latest version for the MC version.
-== <tt>CheckResult</tt> ==
+==<tt>CheckResult</tt>==
 The version checker result for a mod can be retrieving using the <code>VersionChecker.getResult(IModInfo)</code> static method which returns a <code>CheckResult</code>. (<code>IModInfo</code> is the information for a specific mod; see <code>ModList#getModContainerById(String)</code> and <code>ModContainer#getModInfo()</code>).
-The <code>CheckResult</code> contains four unmodifiable fields:
+The <code>CheckResult</code> contains four methods:
 * <code>status</code>, the version checker status as a <code>VersionChecker.Status</code> enum value.
 * <code>target</code>, the version which caused the <code>OUTDATED</code>, <code>BETA</code> or <code>BETA_OUTDATED</code>

@@ Line 1: / Line 1: @@
-The '''Update Checker''' is a Forge-provided utility for mods to check for new versions based on an online update JSON file. It is lightweight, toggleable, asynchoronous to the main mod loading, and integrates cleanly with the mods list menu.
+The '''Version Checker''' is a Forge-provided utility for mods to check for new versions based on an online update JSON file. It is lightweight, toggleable, asynchoronous to the main mod loading, and integrates cleanly with the mods list menu.
-If there are outdated mods according to the update checker, a flashing emerald indicator will be shown on the Mods button on the main menu. The entries for the outdated mods in the mods list screen have the flashing emerald indicator. The information screen for outdated mods will have an <code>Update available:</code> line with the <code>homepage</code> URL from the update JSON file, and a list of mod versions and corresponding text after the mod description, for the mod versions between the most up-to-date and the currently installed version.
+If there are outdated mods according to the version checker, a flashing emerald indicator will be shown on the Mods button on the main menu. The entries for the outdated mods in the mods list screen have the flashing emerald indicator. The information screen for outdated mods will have an <code>Update available:</code> line with the <code>homepage</code> URL from the update JSON file, and a list of mod versions and corresponding text after the mod description, for the mod versions between the most up-to-date and the currently installed version.
 <!-- TODO: add images of these -->
-The update checker can be configured through the <code>versionCheck</code> option in the FML config (<tt>config/fml.toml</tt>). This option controls the version checking for all mods, including Forge.
+The version checker can be configured through the <code>versionCheck</code> option in the FML config (<tt>config/fml.toml</tt>). This option controls the version checking for all mods, including Forge.
 == Update JSON format ==
-The update checker checks the update JSON, specified by the <code>updateJSONURL</code> for the [[Proper Mod Structuring#Mod Properties|mod in the <tt>mods.toml</tt>]]. An example of a JSON file is the [https://files.minecraftforge.net/maven/net/minecraftforge/forge/promotions_slim.json update JSON for Minecraft Forge]. The JSON file must be in the following format:
+The version checker checks the update JSON, specified by the <code>updateJSONURL</code> for the [[Proper Mod Structuring#Mod Properties|mod in the <tt>mods.toml</tt>]]. An example of a JSON file is the [https://files.minecraftforge.net/maven/net/minecraftforge/forge/promotions_slim.json update JSON for Minecraft Forge]. The JSON file must be in the following format:
 {{Tree list}}
 * '''Root object'''
@@ Line 21: / Line 21: @@
 == Update status ==
-There are 7 possible update checker statuses, according to the <code>VersionChecker.Status</code> enum:
+There are 7 possible version checker statuses, according to the <code>VersionChecker.Status</code> enum:
-* <code>PENDING</code> - The update checker has not or is currently retrieving the version from the update JSON. This is temporary, and will change into one of the other statuses.
+* <code>PENDING</code> - The version checker has not or is currently retrieving the version from the update JSON. This is temporary, and will change into one of the other statuses.
-* <code>FAILED</code> - The update checker failed, either to retrieve the update JSON or some other error (such as failure to parse broken JSON).
+* <code>FAILED</code> - The version checker failed, either to retrieve the update JSON or some other error (such as failure to parse broken JSON).
 * <code>UP_TO_CODE</code> - The currently installed version is the same as the recommended version for the current Minecraft version.
 * <code>OUTDATED</code> - The currently installed version is either behind the recommended version for the MC version, or ahead of the recommended version, but behind the latest version for the MC version.
@@ Line 31: / Line 31: @@
 == <tt>CheckResult</tt> ==
-The update checker result for a mod can be retrieving using the <code>VersionChecker.getResult(IModInfo)</code> static method which returns a <code>CheckResult</code>. (<code>IModInfo</code> is the information for a specific mod; see <code>ModList#getModContainerById(String)</code> and <code>ModContainer#getModInfo()</code>).
+The version checker result for a mod can be retrieving using the <code>VersionChecker.getResult(IModInfo)</code> static method which returns a <code>CheckResult</code>. (<code>IModInfo</code> is the information for a specific mod; see <code>ModList#getModContainerById(String)</code> and <code>ModContainer#getModInfo()</code>).
 The <code>CheckResult</code> contains four unmodifiable fields:

@@ Line 1: / Line 1: @@
-= Forge Update Checker =
+The '''Update Checker''' is a Forge-provided utility for mods to check for new versions based on an online update JSON file. It is lightweight, toggleable, asynchoronous to the main mod loading, and integrates cleanly with the mods list menu.
-Forge provides a very lightweight opt-in update-checking framework. All it does is check for updates, then show a flashing icon on the Mods button of the main menu and mod list if any mods have an available update, along with the respective changelogs. It does not download updates automatically.
+If there are outdated mods according to the update checker, a flashing emerald indicator will be shown on the Mods button on the main menu. The entries for the outdated mods in the mods list screen have the flashing emerald indicator. The information screen for outdated mods will have an <code>Update available:</code> line with the <code>homepage</code> URL from the update JSON file, and a list of mod versions and corresponding text after the mod description, for the mod versions between the most up-to-date and the currently installed version.
-== Getting Started ==
+The update checker can be configured through the <code>versionCheck</code> option in the FML config (<tt>config/fml.toml</tt>). This option controls the version checking for all mods, including Forge.
 == Update JSON format ==
-The JSON itself has a relatively simple format, given as follows:
+== Update status ==
+There are 7 possible update checker statuses, according to the <code>VersionChecker.Status</code> enum:
-<syntaxhighlight lang="json">
+* <code>PENDING</code> - The update checker has not or is currently retrieving the version from the update JSON. This is temporary, and will change into one of the other statuses.
+* <code>FAILED</code> - The update checker failed, either to retrieve the update JSON or some other error (such as failure to parse broken JSON).
-  "homepage": "<homepage/download page for your mod>",
+* <code>UP_TO_CODE</code> - The currently installed version is the same as the recommended version for the current Minecraft version.
-  "<mcversion>": {
+* <code>OUTDATED</code> - The currently installed version is either behind the recommended version for the MC version, or ahead of the recommended version, but behind the latest version for the MC version.
-    "<modversion>": "<changelog for this version>",
+* <code>AHEAD</code> - The currently installed version is ahead of the recommended version for the MC version, and there is no more up-to-date latest version for the MC version. <!-- might reword the second part -->
-    '' List all versions of your mod for the given Minecraft version, along with their changelogs
+* <code>BETA</code> - There is no recommended version, and either the currently installed version is up-to-date or ahead of the latest version, or there is no latest version for the MC version.
-    ...
+* <code>BETA_OUTDATED</code> - There is no recommended version, and the currently installed version is behind the latest version for the MC version.
-== Retrieving Update Check Results ==
+== <tt>CheckResult</tt> ==
-You can retrieve the results of the Forge Update Checker using <code><nowiki>VersionChecker.getResult(ModInfo)</nowiki></code>. The returned object has a field <code><nowiki>status</nowiki></code> which indicates the status of the version check. Example values: <code><nowiki>FAILED</nowiki></code> (the version checker couldn’t connect to the URL provided), <code><nowiki>UP_TO_DATE</nowiki></code> (the current version is equal to or newer than the latest stable version), <code><nowiki>OUTDATED</nowiki></code> (there is a new stable version), <code><nowiki>BETA_OUTDATED</nowiki></code> (there is a new unstable version), or <code><nowiki>BETA</nowiki></code> (the current version is equal to or newer than the latest unstable version). The status will be <code><nowiki>PENDING</nowiki></code> if the result requested has not finished yet; in that case, you should try again in a little bit. Otherwise, the returned object will also have the target version and any changelog lines, as specified in <code><nowiki>update.json</nowiki></code>. You can obtain your own <code><nowiki>ModContainer</nowiki></code> to get the <code><nowiki>ModInfo</nowiki></code> of (with <code><nowiki>ModContainer#getModInfo()</nowiki></code>) to pass to this method using <code><nowiki>ModLoadingContext.get().getActiveContainer()</nowiki></code> inside your constructor, <code><nowiki>ModList.get().getModContainerById(<your modId>)</nowiki></code> or <code><nowiki>ModList.get().getModContainerByObject(<your mod instance>)</nowiki></code>; or any other mod’s <code><nowiki>ModContainer</nowiki></code> using <code><nowiki>ModList.get().getModContainerById(<modId>)</nowiki></code>.
+The <code>CheckResult</code> contains four unmodifiable fields:

← Older revision	Revision as of 12:13, 7 January 2021
(No difference)

← Older revision	Revision as of 23:12, 24 October 2020
(No difference)