Home

VersionChecker Wiki

This wiki is intended for use by Subnautica and Subnautica: Below Zero mod developers for the purpose of making their mods compatible with VersionChecker.

If you are not a modder, simply install VersionChecker and have fun!

Making Your Mod Compatible

To work with VersionChecker your mod needs two things:

• You must use Assembly Versioning (also required by QModManager) for your mod's version number - both in the mod.json and on Nexus Mods
• A simple edit to your mod.json to link your mod to your Nexus Mods page

And that's it!

Please consider adding VersionChecker to your Requirements on Nexus Mods (with a note mentioning that it's optional).

Not only does this increase awareness of VersionChecker which leads to more players keeping their mods up-to-date - which is good for everybody - it also helps us to keep track of which mods are making use of VersionChecker, enabling us to focus on making sure everything is working correctly - which is good for you!

NOTE: Don't add VersionChecker as a reference to your project! You don't need to do this, and in fact doing so means that your mod won't load unless the user has it installed, which is not the intended use case for VersionChecker!

Editing Your mod.json for VersionChecker

You just need to add a simple NexusId property to your mod.json to link it to your mod's Nexus page. Here's the mod.json we use for VersionChecker on Subnautica, as an example:

{
    "Id": "VersionChecker",
    "DisplayName": "VersionChecker",
    "Author": "Tobey Blaber",
    "Version": "1.2",
    "AssemblyName": "Straitjacket.Utility.VersionChecker.dll",
    "Enable": true,
    "Game": "Subnautica",
    "VersionDependencies": {
        "SMLHelper": "2.9"
    },
    "NexusId": {
        "Subnautica": "467"
    }
}

The "Subnautica": "467" entry corresponds to the game and Nexus Mod ID for the mod. To find your mod's Nexus Mod ID, simply visit your mod's Nexus Mods page, and it is the number that appears after /mods/ in the URL, for example for VersionChecker the URL is: https://www.nexusmods.com/subnautica/mods/467 which gives us a mod ID of 467.

Note that for VersionChecker we ship a different a mod.json file for both the Subnautica and Below Zero versions of the mod. If however you ship a single mod.json with both, and have a Nexus mods page for each game, then your mod.json might look more like this:

{
    "Id": "VersionChecker",
    "DisplayName": "VersionChecker",
    "Author": "Tobey Blaber",
    "Version": "1.2",
    "AssemblyName": "Straitjacket.Utility.VersionChecker.dll",
    "Enable": true,
    "Game": "Both",
    "VersionDependencies": {
        "SMLHelper": "2.9"
    },
    "NexusId": {
        "Subnautica": "467",
        "BelowZero": "57"
    }
}

During development, you might notice that you'll put an update on Nexus Mods and find that you're not getting notified instantly in-game with an outdated version of your mod. This is normal, for the following reasons:

1. By default, VersionChecker does not check for updates every time you launch the game, and limits to hourly checks. You can change it to always check on game launch if you'd like via the in-game mod options menu, but I actually recommend deleting the LastChecked property from VersionChecker's config.json instead. This will force VersionChecker to check for updates the next time the game is launched.
2. When interacting with the Nexus Mods API, we make use of a 120 minute cache to store the data. This is to prevent rate-limiting, enforced by Nexus Mods. The end result is that it can take up to 120 minutes before VersionChecker will detect an update, but this also depends on the previous point. So, wait approx. 120 minutes and delete the LastChecked property from VersionChecker's config.json before verifying that VersionChecker has detected your update.

Legacy Support

Prior to VersionChecker 1.2, we also used the VersionChecker property in your mod.json to point to an online version of your mod.json, which would always reflect the latest version number of your mod.

Since VersionChecker 1.2, the NexusId property takes precedence over the VersionChecker property, but we fallback to it in the event the NexusId property is not set or there was an error retrieving the version number from Nexus Mods API.

For reference, the rest of the legacy documentation follows.

Putting Your mod.json Online

Really, it's up to you how you achieve this. But the easiest and recommended method is simply to make your mod's GitHub repo public, and grab the link to the raw mod.json from there.

Note: We need the raw link, not the blob. For example, for VersionChecker, the correct link is: "https://github.com/tobeyStraitjacket/VersionChecker/raw/master/VersionChecker/mod.json".

Editing Your mod.json for VersionChecker

You just need to add a simple VersionChecker property to your mod.json containing information about where to find your latest mod.json version. Here's the mod.json we use for VersionChecker, as an example:

{
    "Id": "VersionChecker",
    "DisplayName": "VersionChecker",
    "Author": "Tobey Blaber",
    "Version": "1.1.2.1",
    "AssemblyName": "Straitjacket.Utility.VersionChecker.dll",
    "Enable": true,
    "Game": "Both",
    "VersionDependencies": {
        "SMLHelper": "2.8"
    },
    "VersionChecker": {
        "LatestVersionURL": "https://github.com/tobeyStraitjacket/VersionChecker/raw/master/VersionChecker/mod.json"
    }
}

Note that VersionChecker property. It's a dictionary, with the property LatestVersionURL. On load, VersionChecker looks through a user's installed QMods, reads their mod.json files, and looks for any that contain the VersionChecker property. It then grabs the LatestVersionURL property from within it. That's really all there is to it!

Why didn't you just add LatestVersionURL without making it part of the VersionChecker dictionary/property?

Simply put, I plan to extend the developer-focused features of VersionChecker, and to do so I'll be using more properties in mod.json. Wrapping them all in a VersionChecker dictionary avoids polluting the mod.json namespace more than we need to.

Bypassing the Nexus Mods API Cache

Please be aware that the following information is for impatient developers only and presents a security risk so use this information at your own risk!

As noted above, when interacting with the Nexus Mods API, VersionChecker makes use of a cache for storing data, which can slow down the rate at which you receive updates. If you wish to bypass this, you can make use of the apikey command in-game to provide your own Nexus Mods API key to VersionChecker, and it will use the API key provided whenever it checks for updates and no longer rely on a cache - however: you will be responsible for your own rate-limiting! It is highly recommended to only use this feature for testing in development, as storing your API key via a mod which could be interecepted by another mod is an obvious security risk!

Make sure to use apikey unset which deletes any reference to your API key that VersionChecker held, and reset your API key via Nexus Mods when you are finished testing to ensure anyone who had intercepted it can no longer make use of it.