FG's Modlists
We have an amazing community
Discord server where you can
get live help. Join it by clicking
the button below!
August 10, 2022
Before we dive in, there are some basic things you should be aware of. First, this guide assumes you have completed your modlist. All the mods are installed, patches have been made, and so on. It also assumes that you will want to share your modlist with other people. If you want to use Wabbajack just to backup a copy of your modlist, some of the information here will be helpful but in general it’s aimed towards authors that want to distribute their modlist.
There are some more specifics you need to know too, though, so let’s begin.
When I say “installer”, what I mean is this: Wabbajack creates a file with the .wabbajack extension. That file is used by Wabbajack to allow a modlist to be installed. So when I say an “installer file”, that’s what I’m referring to. The installer file for Living Skyrim 3, for example, is living_skyrim.wabbajack.
A root folder is the base folder on a computer that a modlist is inside. For example, Living Skyrim 3’s root folder (for me) is C:\Modlists\Living Skyrim 3. When I refer to the root folder, I mean the folder that contains the ModOrganizer.exe for your modlist. Later in this guide you’ll see this referred to in this way, or in similar ways: [root folder]\downloads, [root folder]\Stock Game, etc.
There are officially three kinds of modlist when it comes to Wabbajack.
Unofficial lists are those maintained by a person without any guarantee of support for that modlist. Unofficial also covers lists that aren’t ready for “primetime” yet: alphas, betas, tests, and so on. Unofficial lists aren’t required to be on the Wabbajack UI, but it can be done if you so choose. Unofficial lists can be distributed as easily as giving people access to the installer file via Google Drive or another filesharing site. We’ll dig into the specifics of this later, but for now, know that any list that isn’t one of the following two types is an Unofficial list.
Featured lists are modlists that have been vetted in some way. In the past this meant that the list had been tested by some of the Wabbajack staff. Nowadays, it tends to mean lists that have been recognized as stable with many installs.
The actual process for a list to become Featured is as follows:
Utility lists are special in that they don’t really make many changes to the game they’re for. A perfect example of this is Skyrim Modding Essentials, which is a barebones modlist for Skyrim that includes many of the basic fixes, patches, and tools required to begin building a modlist. It doesn’t contain any gameplay, graphics, quests, or any other mod - it’s purely fixes and tools. These are the least common list because usually a game only needs one, but if you want to make one for a game that doesn’t have one yet, more power to you.
If you want to make an Unofficial or Featured list, you’ll need a Github account. A lot of the things we’ll be doing are done on Github, so this is a must-have. You should also make yourself familiar with these processes:
You’ll also need a copy of Wabbajack. You can’t make an installer without it, after all. When you download Wabbajack, you should place it in its own folder on your computer. Ideally, the path to your copy of Wabbajack will be C:\Wabbajack\Wabbajack.exe, but feel free to place it in a folder at the root of any drive on your computer.
Wabbajack only supports modlists built using Mod Organizer 2, so unfortunately if your modlist uses Vortex or another mod manager, you won’t be able to create an installer file. For more information about how Mod Organizer 2 should be set up to facilitate a Wabbajack modlist, refer to the Compiling section of this document. Additionally, Mod Organizer 2’s archive must also exist in your [root folder]\downloads folder. It is strongly recommended that you obtain Mod Organizer 2 from its latest Github release, which will give you the archive necessary for Wabbajack to be able to install Mod Organizer 2.
Wabbajack has a feature called Stock Game, which is a way to keep the default install folder of a game clean for users while still having a modded copy of the game. It also allows users to install multiple modlists for the same game at the same time in the event they wish to switch. For more details on setting up Stock Game, you should read The Animonculory’s guide to setting up Stock Game.
When you download a mod archive (.7z, .zip, .rar, etc.) from Nexus, Mod Organizer 2 automatically creates a .meta file for that mod. The Meta file tells Mod Organizer 2, and more importantly, Wabbajack, where that mod came from and how to obtain the archive. Similarly, if you download a mod from a site that is not Nexus, Mod Organizer 2 will still create a .meta file for that mod, but it will not contain any of the required information of where that archive came from. For mods that do not come from Nexus, you will have to manually update Meta files such that they contain the required information for Wabbajack to know where to obtain that archive.
We’ll now take a look at some non-Nexus .meta files.
[General]
removed=false
installed=true
directURL=adirectURL
directURL= is primarily used for files obtained via Google Drive, Mediafire, Mega, Github, and other file hosting sites. Files that use directURL must be whitelisted, which we’ll talk about in a bit. In the above example, to properly configure the .meta, you would simply replace adirectURL with the URL of the file you want to download. It’s important to note that directURL also allows Wabbajack to automatically download the file in question.
Note that directURL does not work with sites like Lover’s Lab or Vector Plexus.
[General]
installed=true
uninstalled=false
manualURL=amanualURL
prompt=Please click Download on this page.
The above should look fairly familiar. Manual URL works exactly the same as Direct URL except that Wabbajack will not automatically download the file in question. Instead, Wabbajack will present the webpage you provide when replacing amanualURL and ask the user to download the indicated file. The prompt= field can contain any text, but try to keep it short and sweet (the Wabbajack window is only so big, after all). For example, you might say prompt=Please click Download on this page. or prompt=Please download FileName_X-Y-Z.7z.
Note that manualURL does work with sites like Lover’s Lab or Vector Plexus and is preferred for those sites.
[General]
ips4Site=Lovers Lab
ips4Mod=12345
ips4File=File Name.7z
ips4 is unique in that it is only for two specific websites: Lover’s Lab, and Vector Plexus. These two websites are based on the ips4 framework. ips4Site= should be used to indicate which website Wabbajack should try to retrieve the file from, either Lovers Lab or Vector Plexus. ips4Mod= should be filled out with the file ID for the file. This is obtained from the URL of the webpage the file is on. So for example, if we have https://www.loverslab.com/files/file/18156-llapc-loverslab-attachment-patch-compendium/, the file ID is 18156 - the number directly before the name of the mod. Last, the ips4File= should be the exact name of the file you want Wabbajack to download. From the previous example, you might want FSF + SLSO Script Patcher.7z.
It’s very important to note that ips4 should only be used as a last resort, manualURL is much preferred for these two sites currently due to instability with their API.
🛑 I cannot stress this enough: everything in your[root folder]\downloadsfolder must have a complete.metafile! EVERYTHING!
Some mods are hosted in obscure places on the internet and Wabbajack does not have a comprehensive list of those places. Therefore, when you find a file that Wabbajack does not recognize, it must be whitelisted. The actual whitelist Wabbajack uses is found here. You’ll notice that this list is split into sections. The two important sections are GoogleIDs and AllowedPrefixes. Whenever you want to whitelist a file hosted on Google Drive, its file ID should be added to the list under the GoogleIDs section. All mods found on other filehosting sites should be placed in the AllowedPrefixes section.
Google file IDs are contained in the URL for the file. For example, the ID for this file https://drive.google.com/file/d/15_0njBUjHKidNnJPmLXEygzGVWsA3Zbq/view?usp=sharing is the string of characters between the /d/ and /view: 15_0njBUjHKidNnJPmLXEygzGVWsA3Zbq. All other files (Mega, Mediafire, etc) should be added simply by using the URL for the file.
It’s generally courteous to check the whitelist to see if the file you need to whitelist is already on there. If it is, you don’t need to add it. If it isn’t, you’ll need to open a Pull Request to modify the whitelist and add the file. You should also add a comment (prefixed by #) to indicate what the file is.
Also note that every line in the whitelist is prefixed by - , you should do that as well. You should also group all of the files for your specific list together.
A properly formatted whitelist section looks like this:
# Living Skyrim 3.0.0
- https://archive.org/download/Wyrmstooth1.17BSSE/Wyrmstooth%201.17B%20SSE.zip # Wyrmstooth 1.17B
- https://www.skyrim-guild.com/s/ADXP_Beta_13.zip # ADXP/MCO Beta 1.3
Wabbajack has a CDN (Content Delivery Network) that is available for modlist authors with Featured modlists to use. The CDN can be used to host files that you have generated for your modlist - DynDOLOD output, Grass Cache, patches, and so on. It serves as an integrated alternative to uploading those files to Nexus. To gain access, you’ll need to login to Github and then follow the guide Unnoen put together, here.
Once you have access to the CDN, you can use it to upload files and then when a user installs your list, they can download it directly from the CDN instead of Nexus or another site. It is much preferred to use the CDN over filehosting sites like Google Drive, Mega, and so on because many filehosting sites limit the amount of users that can download a file before temporarily suspending access to that file. The CDN has no such restrictions.
Once you’ve set up your CDN access, it’s straightforward to upload a file to the CDN.
In Wabbajack, click the gear icon in the top right corner of the program. You’ll be presented with the settings page for Wabbajack. Below the “Logins” box, you’ll see a section for uploading files.
Simply click Select File, then find the file you want to upload. Then click Upload and wait for it to complete. Do not close Wabbajack once the upload is complete.
The reason you don’t want to close Wabbajack yet is that once the upload finishes, you’ll be given the URL to your file. This is the URL that should be placed in a directURL .meta to allow Wabbajack to automatically download the file you just uploaded.
Some commonly used mods are available on the CDN for you already, such as the ENB binaries. You should double-check to see if a copy of that mod already exists on the CDN and use that copy instead of uploading a new copy whenever possible.
While the CDN is a very powerful tool that we can use as modlist authors, it cannot be used to re-upload mods unless the permissions of that mod state it can be re-uploaded. You are always expected to obey the permissions set by mod authors while creating your modlist.
Before you compile your modlist, you may want to create a logo for it. This can be as simple as something you put together in MS Paint or as complex as using Photoshop to create a unique and cool logo. While I won’t go into the specifics of logo creation (there are only about a billion tutorials online), I will say that having an eye-catching logo is important for the branding and marketing of your modlist.
You’ll also want to make a readme for your modlist. This can be hosted on Github, your own website, or even a simple Google Doc. The readme should cover essential information relating to your modlist. If you want some examples, I can highly recommend the following readmes:
The process of creating an installer file is called “compiling”.
For details about how to actually go through the compiling process, you should refer to my article about that exact topic here: Click Me!
When you have successfully created an installer file, logo, and readme, congrats! You’re ready to turn your modlist into an Unofficial modlist.
If you want your list to appear on Wabbajack itself, you’ll need to set up a modlists.json file so that Wabbajack knows your modlist exists and can be distributed to users. To do so, follow the instructions in this guide.
Note that if your list goes from Unofficial to Featured, the custom repository you make will no longer be required and can be safely archived/deleted.
Once you’ve done that, give Wabbajack some time to update (anywhere from 10 minutes to an hour) and then your modlist will appear on the Wabbajack UI!
You can also upload your installer to Nexus, if you so choose. Just follow the normal process for creating a new mod and upload the installer file to it. Nexus is a good alternative as there is more traffic to Nexus itself, as well as allowing you to show off screenshots, describe the list, and respond to users all in one convenient place. Note, if you do upload your list to Nexus, it is against Wabbajack’s terms of service to opt the list in to Nexus’s Donation Points program.
While not ideal, you can technically just put your installer on any filehosting site and give people the link to the file. They’ll be able to download and run the installer themselves through Wabbajack.
After your modlist has been distributed, it’s very likely you’ll have people who need assistance or have questions. Maybe they just need help installing the list, or maybe there’s a technical question about how certain mods interact in your list. How you go about supporting users is, ultimately, up to you. However, here are some recommendations about things that will help you:
While these are some of the most popular systems available to modlist devs to interact with users and handle bug reports, you’re of course welcome to use whatever system you’re comfortable with. I myself use a combination of tools to interact with my users and keep track of bugs - Asana (bug tracking), Vercel (website hosting), Discord (community and support).
Inevitably, a mod will update or be removed causing your modlist to go into Maintenance. This appears on Wabbajack as a bright yellow banner that says “Under Maintenance”. All this means is that Wabbajack cannot allow a list to be installed because a file required by the modlist cannot be obtained.
The most straightforward solution to this problem is to update your modlist. You should remove the mod from your list and your [root folder]\downloads folder, or if a new version is available, update the mod to the newest version. When you update your modlist, you’ll need to update the locations that you uploaded your modlist to. Nexus handles versioning for files fairly well, but if you’re using the Wabbajack UI, you’ll need to use the modlists.json you created earlier (or the Featured modlists.json) to update the metadata for your modlist so that it can continue distributing the list.
You can also use the machineURL field on the Wabbajack compilation screen to have Wabbajack automatically update the metadata for your modlist once compilation is complete. If your list is Unofficial, you should fill it out as follows: repo name/list name, following whatever naming scheme you used while setting up your custom repository. If your list is Featured, you should fill it out as wj-featured/list name.
“How does Wabbajack know when a mod has been removed?” You may ask. To that, I’ll let you know about Wabbajack’s secret weapon: Validation. Periodically, Wabbajack checks every mod in every list to make sure those files are still available. If a file isn’t available, or Wabbajack can’t connect to a file’s host website, it marks the list as in maintenance. Depending on the stability of the host website, this may automatically resolve itself after a certain amount of time. It’s up to you to verify Wabbajack’s validation to see if a list update is needed.
When validation for a mod on Nexus fails, Wabbajack will then check to see if that mod has been updated. If it has, Wabbajack is able to continue serving the old version of the mod. Or, if the old version is no longer available somehow, Wabbajack will try to heal the modlist. It will download the new version of the mod and then change the new version such that it matches the old version. It will then continue to serve the modlist to users, but you should really try to update the mod when possible. This process is entirely automated so you shouldn’t have to worry about it too much, but it is a handy backup just in case.
The last thing you may want to set up for your modlist is access to WabbaBot. WabbaBot is a Discord bot that allows you to quickly announce updates for your modlist. It will make the announcement for you across multiple Discord servers that have opted in to receive notifications about your list. For more information about this bot and how to set it up, you should join the Wabbajack Discord server and visit the #wabbabot-help channel.