77
edits
Changes
From Forge Community Wiki
Inital Import from dokuwiki
= 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>.
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>.