Registry - MSUTeam/MSU GitHub Wiki

The Registry system keeps track of all MSU mods, managing the instantiation and versioning of said mods. For the modder, currently the system provides a way to easily notify your players of updates to your mod, link them to your mod pages, and simplify the downloading of new updates.

From MSU 1.2.0 on, you can easily connect your mod to a GitHub repository to notify users of new updates to your mod. Unfortunately, while we allow linking to NexusMods (and we may be able to allow using it as an update source in the future), it is currently not possible to check for updates from it as its API is closed. Thus, Github is currently the only built-in mod source that can be checked for mod updates.

Setting up update-checking is trivial and is done in 2-3 lines. Before you do that, your Git tags must use Semantic Versioning with all the same requirements as MSU mod versions. The Registry system reads the latest full release on your GitHub repository, and compares its tag to the version in the mod on the users machine, assuming they match, nothing happens. If they are different, the user will receive a pop-up upon launching their game, informing them of the update and linking them to your GitHub repository (and optionally your NexusMods page too). It will also notify the user if you are using a non-semver version for your Git tags and let them know the update checker isn't working.

Technically, the system can be expanded with new update sources, although there has never been a great need to do so. The crafty developer that wants to host their mods on their own forge must delve into the code.

A ModSource is a place your mod can be downloaded from. Available ModSources are defined in the ::MSU.System.Registry.ModSourceDomain Enum.
These are the three mod sources MSU currently provides:

Links to a Github repository. As Github has an API for requesting repository info, this can also be an update source. By default, the user will directly download the .zip file of the release if they click on the github icon. If you want to disable this behaviour, pass {DirectDownload = false} while initialising the mod source: addModSource(::MSU.System.Registry.ModSourceDomain.GitHub, "https://github.com/MSUTeam/MSU", {DirectDownload = false});

Links to a Github repository. There are two advantages over a Github modsource:

• You only need to create and publish a tag to denote a new version, instead of a full release on Github
• You can use a monorepo for your projects, and have one common base repo link. You will need to prefix your tags. To use a monorepo, pass a Prefix parameter within the _opts pseudo-kwargs-table. See the example

Links to a Nexusmods page. Mostly just used to allow people to quickly navigate to the nexus page.

<Mod>.Registry.addModSource( _domain, _url )
// _domain is an entry in the Enum ::MSU.System.Registry.ModSourceDomain
// _url is a string

_url Must be the _url for your mod in the _domain, this requires the correct format depending on the ModSource, eg "https://www.nexusmods.com/battlebrothers/mods/479" for NexusMods and "https://github.com/MSUTeam/MSU" for GitHub. This is validated with a regex

Adds a new potential ModSource to your mod.

<Mod>.Registry.hasModSouce( _domain )
// _domain is a value in the Enum ::MSU.System.Registry.ModSourceDomain

Returns true if addModSource was successfully called on this mod with this ModSourceDomain, false otherwise.

<Mod>.Registry.getModSouce( _domain )
// _domain is a value in the Enum ::MSU.System.Registry.ModSourceDomain

Returns the URL passed with addModSource

<Mod>.Registry.setUpdateSource( _modSource )
// _modSource is a value in the Enum ::MSU.System.Registry.ModSourceDomain

Sets a particular ModSource you added with addModSource to be used to compare the version of the local version of the player's mod against. Currently the only acceptable value here is ::MSU.System.Registry.ModSourceDomain.GitHub

<Mod>.Registry.hasUpdateSource()

Returns true if setUpdateSource was successfully called on this Mod, false otherwise.

<Mod>.Registry.getUpdateSource()

Returns the ModUpdateSourceDomain this Mod was set to, null if it was never set.

// create your mod
local yourmod = ::MSU.Class.Mod("yourmod", "1.0.0");

// add GitHub mod source
yourmod.Registry.addModSource(::MSU.System.Registry.ModSourceDomain.GitHub, "https://github.com/MSUTeam/MSU");
// this will currently do nothing on its own(though in the future we may add a way to list all MSU mods with links), to affect a players game, we have to set GitHub as our UpdateSource
yourmod.Registry.setUpdateSource(::MSU.System.Registry.ModSourceDomain.GitHub)
// now if you've set up your git tags and releases properly, the mod user will be notified if there's an available release with a version greater than 1.0.0

// add NexusMods mod source (for an easy link)
yourmod.Registry.addModSource(::MSU.System.Registry.ModSourceDomain.NexusMods, "https://www.nexusmods.com/battlebrothers/mods/479");

// add GithubTags mod source with prefix
local prefix = "mymod-"
yourmod.Registry.addModSource(::MSU.System.Registry.ModSourceDomain.GitHubTags, "https://github.com/MSUTeam/MSU", {Prefix = prefix});
yourmod.Registry.setUpdateSource(::MSU.System.Registry.ModSourceDomain.GitHubTags);