MO2 downloads from ModPub (and anywhere else)

10 November 2023, 19:43  |  Posted by Eddoursul  |  96 views
Mod manager downloads is a two-way street: websites must supply download links in a special format, mod managers must understand and process them. Many of you enjoy the ability to download from Nexus Mods directly to your MO2/Vortex/NMM/etc. Unfortunately, the nxm:// protocol used by Nexus cannot be reused to implement mod manager downloads from other websites without significant changes.

To solve this, I am proposing a new download schema, modl://, allowing to set up MO2 downloads from any website. Potentially, any mod manager can be updated to support it. As of now, this schema is rolled out and enabled on ModPub. Here is how you can use it:

You are a mod user

  • Update your Mod Organizer 2 to version 2.5 or newer. MODL integration does not work with older versions of MO2.
  • Copy modlhandler.exe to MO2's directory.
  • Run modlhandler.exe and confirm creating a new association with modl:// links.

These steps enable modl:// support for all websites, adopting the new schema.

This protocol enables file downloads only. To add support for update checks, likes, and other site-specific functions, websites must publish APIs AND mod managers must support each specific API separately, because all of them would be different (no, Nexus API is not a one-shoe-fits-all). I plan to publish ModPub API some time in 2024, and this is going to be only half of the work.

You are a site administrator

The first iteration of the schema is intentionally simple: it accepts a direct download link, and starts download of the file in Mod Organizer 2. This allows use of the protocol by any websites, even the ones hosted on Github static pages. A download link should look like this (this is a working example): modl://falloutnv/?

modl:// - allows to send download links to programs on user's computer (in our case, modlhandler.exe).

falloutnv - a game ID, which you can find in MO2's source code.
Identifiers of Gamebryo-based games: morrowind, oblivion, fallout3, fallout4, falloutnv, skyrim, skyrimse, enderal, enderalse, starfield.
To determine other IDs, see game plugins from this directory and look for GameShortName.
This may be unintuitive, but supplied game ID does not open an intended MO2 instance right away. modlhandler checks if such instance exists, and then MO2 loads a last loaded instance; this applies to Nexus links, too.
Special value other just opens the last instance.

url - must contain a urlencoded direct download URL. modlhandler.exe decodes URLs using QUrl::fromPercentEncoding, you can get compatible strings using rawurlencode in PHP and encodeURIComponent in JavaScript.

If you would like to do some backend work, like count downloads or generate a temporary url, point your download link or button to your script as usual, run your routine, and then redirect user to a modl:// url.

Instruct your users to install You are free to rehost it on your website, but I strongly suggest to use my permalink, since it points to the latest build of modlhandler.exe I maintain. If any mod manager adds built-in support for modl://, I will update this post. Source code of modhandler.exe can be found on my Github.

You are a Discord server administrator
(coming soon)