Hosting SuperBLT Mod Updates on GitHub

Published 2019-08-16. Last updated 2019-12-04.

This GitHub webage and its associated repository serve as an example of how automatic updates can be hosted for SuperBLT.

Contents:

  1. SuperBLT Automatic Update Specifications
    2.
  2. Setting Up a GitHub Repository for Updates
    3.
  3. Setting Up Updates for mod_overrides
    4.

1. SuperBLT Automatic Update Specifications

Updates Tag

As specified in the automatic updates documentation of SuperBLT, an updates tag should be added to the mod.txt. The example below is taken from the documentation.

"updates" : [
	{
		"identifier" : "anythingyouwant",
		"host" : {
			"meta" : "https://example.com/my_meta.json",
			"download" : "https://example.com/download.zip",
			"patchnotes" : "https://example.com/patchnotes.html"
		}
	}
]

identifier is a unique identifier for the mod and can be anything as long as it is unique. The identifier is difficult to change later so choose it carefully.

meta links to a JSON file which contains some information about the latest version of the mod. This can be hosted on GitHub. The meta file link is difficult to change later so choose where you want to host it carefully. This is discussed further in Section 2.

I recommend that you omit download and patchnotes from the mod.txt. This is because the download link and patch notes can also be provided in the meta file and these values take precedence over the values in the mod.txt. This way, even if the download link changes between updates, the meta file can always direct the user to the correct link.

Meta File

The format of an example meta file taken from the documentation is given below.

[
    {
        "ident" : "anythingyouwant",
        "hash" : "43e7cd36567c755be88e60bde45ba418527c692af982d45fbedb8b5a8c792772",
        "patchnotes_url" : "https://example.com/other-patchnotes.html",
        "download_url" : "https://example.com/other-download.zip"
    }
]

ident must match the identifier in the mod.txt.

hash is the folder hash value of the latest version of the mod as defined by the hashing system used in SuperBLT. It is NOT the hash of the .ZIP archive specified in the download link. Details on how the hash is calculated and a tool for calculating hashes can be found at the repository for my Python SuperBLT Hash Calculator.

patchnotes_url links to the patch notes of the latest version of the mod. This can be hosted on GitHub Pages.

download_url links to the .ZIP archive of the latest version of the mod. This can be hosted on GitHub.

Update Process

The following is a high-level description of the update process of SuperBLT.

To check for updates, the currently installed version of the mod is hashed and is compared with the server hash value (the hash value in the meta file). If these values do not match, it is assumed that the current version of the mod is outdated. Note that this means making any changes to the currently installed mod will cause it to be detected as outdated.

When an update is initiated, the new version of the mod is downloaded from the download_url and the contents of the .ZIP archive are extracted. The hash of the extracted contents is then calculated and verified against the server hash value. If the hash of the extracted contents does not match the server hash, the update will fail. If the verification is successful, the old installation files are removed and replaced by the extracted files.

2. Setting Up a GitHub Repository for Updates

The repository of this webpage is an example of how GitHub can be used to host SuperBLT updates. The repository can be viewed here.

Folders

To keep things organized, I recommend making a new folder for each mod you want to host updates for. In this example, the mod is called "Dummy Mod" and the folder in the repository is named Dummy Mod as well. You could also use the mod identifier as the folder name; in fact, you can choose anything as long as you can keep track of which mod the folder corresponds to.

Patch Notes

In this example, all of the patch notes are placed in a subfolder called patchnotes. I recommend that you make a new patch notes document for each update to keep things organized.

Patch notes in HTML format can be hosted via GitHub Pages. To enable GitHub Pages, go into the repository settings, scroll down to the GitHub Pages section, and change the source to "master branch". The patch notes for Dummy Mod v2.0 can now be viewed at:

https://fragtrane.github.io/SuperBLT-Update-Demo/Dummy%20Mod/patchnotes/v2.0.html

The layout of the HTML documents was copied from the patch notes used by PaydayMods. I also re-uploaded their stylesheet to this repository to make it easy to change things later and in case something happens to the PaydayMods site. Note that in order to use an uploaded style sheet, you need to reference its GitHub Pages URL. In this example, the full URL is:

https://fragtrane.github.io/SuperBLT-Update-Demo/style.css

Download Link

The download for the latest version of the mod should be a .ZIP archive. The archive should contain the folder that needs to be placed inside the BLT mods folder. You can host this archive wherever you like, but it is probably easiest just to host it on GitHub.

In this example, the archive is hosted in the Dummy Mod folder of the repository. The latest version of the mod is v2.0 and the archive is named Dummy_Mod_v2.0.zip. To get the download link, just replace blob with raw in the URL:

https://github.com/fragtrane/SuperBLT-Update-Demo/blob/master/Dummy%20Mod/Dummy_Mod_v2.0.zip
https://github.com/fragtrane/SuperBLT-Update-Demo/raw/master/Dummy%20Mod/Dummy_Mod_v2.0.zip

The archive for v1.0 can also be found in the Dummy Mod folder and is named Dummy_Mod_v1.0.zip. You can download this older version if you want to see the update process in action.

Meta File

Once you decide where to host the meta file, you should not change the location anymore. This way, all versions of the mod will point to the same meta file which will always direct the user to the latest version of the mod. So even if users miss several updates, they will still be able to update their mod.

In this example, the meta file is placed in the Dummy Mod folder and is named latest.json. For the mod.txt, you need to use the raw URL of the meta file. Simply replace blob with raw in the URL:

https://github.com/fragtrane/SuperBLT-Update-Demo/blob/master/Dummy%20Mod/latest.json
https://github.com/fragtrane/SuperBLT-Update-Demo/raw/master/Dummy%20Mod/latest.json

As mentioned before, there are four values in the meta file:

Pushing a New Update

The repository is now ready. The following steps need to be taken when pushing a new update:

  1. Calculate the hash of the new version of your mod.
  2. Upload a .ZIP archive of the new version of your mod.
  3. Upload the patch notes for the new version of your mod.
  4. Update the values in the meta file to match the new version of your mod.
  5. (Optional) If you have uploaded your mod to other websites (e.g. Mod Workshop), update the download link to the latest version of your mod.
  6. (Optional) Remove the .ZIP archive of the older version of your mod from the repository. Old patch notes can be kept for archiving purposes or removed as well.

3. Setting Up Updates for mod_overrides

Updates Tag

It is also possible to use a BLT mod to update a mod_overrides mod. In order to do so, the updates tag in the mod.txt needs to be extended as seen in the example below.

"updates" : [
	{
		"identifier" : "anythingyouwant",
		"install_dir" : "assets/mod_overrides/",
		"install_folder" : "Folder That Contains the Mod",
		"display_name" : "Name to Display in Update Manager",
		"host" : {
			"meta" : "https://example.com/my_meta.json"
		}
	}
]

install_dir is the path where the mod is installed i.e. the mod_overrides folder.

install_folder is the folder that contains the mod (i.e. the folder that you put inside the mod_overrides folder). If this folder does not exist, updates cannot be checked. But if you create an empty folder with this name, updates will work and the newest version of the mod will be downloaded.

display_name is the name that will be displayed in the update manager.

mod_overrides Update Example

In this example, automatic updates will be set up for a mod_overrides mod named "Dummy Override". The corresponding folder in the GitHub respository is also named Dummy Override. The patch notes and meta file are set up in the same manner as described in Section 2. The mod has the identifier "DummyOverride".

There are two Dummy Override .ZIP archives on the repository: Dummy_Override_v2.0.zip and Dummy_Override_v1.0.zip. v2.0 is the latest version; v1.0 is an older version that you can download if you want to see the update process in action. The .ZIP archive contains a folder named Dummy Override which needs to be extracted to the mod_overrides folder.

A BLT mod called "Dummy Override Updater" is used for updates and can be found in Dummy_Override_Updater.zip. Dummy Override Updater only contains a mod.txt with an updates tag which has the following values:

Dummy Override Updater can be installed to the BLT mods folder. Dummy Override can now be updated like a normal BLT mod. When the game is started, Dummy Override Updater will check the mod_overrides folder to see if Dummy Override is up-to-date by hashing the folder and comparing it with the hash in the meta file. If the hashes do not match, it will be added to the update manager.