Contributing to BL3 ModCabinet - BLCM/bl3mods GitHub Wiki

← Go Back

Contributing to the ModCabinet wiki is quite easy if you've already checked in your mod to the Github. Here's how!

Adding Your Mod to ModCabinet

In order to have your mods listed in the ModCabinet, they have to be uploaded to the main bl3mods Github repostiory, and they need to have an extension of .bl3hotfix. There are instructions for doing so at the BLCMods Wiki.

The cabinet now also supports indexing pakfile-only mods on here, though we are still working out what kind of limitations we might have for that kind of mod. To have a pakfile-only mod indexed here on the cabinet, use a .bl3pakinfo extension instead, and make sure to include the @pakfile tag to specify your pakfile. That way, the cabinet will list your pakfile properly without having any references to hotfix modding.

Once you know how to do that, getting your mod in this wiki is easy: you just need to make sure that your mod file has the required .bl3hotfix file extension, and the appropriate comments up at the top of the file. Once the comments specify the name of your mod, and the categories it should be put into, the BL3 ModCabinet wiki should get updated within ten minutes to include your mod.

Basically, your mod needs to have a "header" at the top of the file, before any of the hotfix statements (and before any free-form docs/notes you might want to put in the file). We now use apple1417's BLIMP Tagging by default, which lets a variety of mods share a similar format. (The "original" style of BL3 mod metadata is still supported for the time being, but new mods are encouraged to use the new format.) For example, a mod header might look like this:

@title Free Respec
@version 1.0.0
@author Apocalyptech
@contact https://apocalyptech.com/contact.php
@categories cheat, economy

@license Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
@license-url https://creativecommons.org/licenses/by-sa/4.0/

###
### No cost to respec skills
###
### Generated by gen_free_respec.py
###

The mod header could alternatively continue to use hash marks in front of the tags, if you prefer. For example:

###
### @title Free Respec
### @version 1.0.0
### @author Apocalyptech
### @contact https://apocalyptech.com/contact.php
### @categories cheat, economy
###
### @license Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
### @license-url https://creativecommons.org/licenses/by-sa/4.0/
###

###
### No cost to respec skills
###
### Generated by gen_free_respec.py
###

It's specifically the @title, @author, and @categories lines up there which let the mod get sorted into the ModCabinet wiki. Without both those, your mod won't show up. We also pretty much require that a @license exists on all uploaded mods, as well (with, optionally, a @license-url to point to the full text of the license). The other lines such as @version and @contact` are optional, though.

The example there uses three hash marks for comments (###) but that's just so that it's a bit more visible -- you only need to use one (#).

Mod Name, Version, and Author

The @title attribute defines the name of the mod, as it will show up in the BL3 ModCabinet. @version is entirely optional, but is a nice way for users to know if they're using the most recent version of a mod or not. @author is mostly for the user's sake, so they can know who wrote the mod by just looking at their files. Note that the BL3 ModCabinet process will actually report the username of the directory your mod lives in as the main author, rather than your text here. The info from the @author statement will still be included on the ModCabinet page, though.

Contact Info

Mod files can optionally include contact information, if you want people to be able to find you to ask questions about the mod. Be sure to only put information in here which you're comfortable having publicly available! There are three options available: @contact, @contact-email, or @contact-discord. The "email" variant will alter the display for the wiki slightly (to use "at" instead of @, and "dot" instead of .), but the others all just show the text exactly as-written in the mod file, so feel free to format them however you like.

Assigning Categories

The current valid categories that you can use in your mod file are listed on the Mod Categories page. You can see in the example above that I've assigned the mod to both the cheat and economy categories, so it'll show up on both pages. You need to have at least one valid category for the mod to be included on the wiki, and you can put in as many as you feel are appropriate. If you have more than one, be sure to have a comma inbetween each one. You can also put a space inbetween them, as I've done in the example, but you don't have to. Alternatively, you can specify multiple lines for each category:

@categories cheat
@categories economy

Licensing

Licensing of your mod files is required for inclusion on the ModCabinet wiki. Historically there have been questions about people including mods in modpacks, or uploading them to other modding sites (like Nexus), and if you attach a license to your mod, any ambiguity as to what people can do with it will disappear. If you don't specify a license, the safest assumption people can make is that they're only allowed to use the mod for personal use, but it'll be in a state of ambiguity.

The most "open" license possible is "Public Domain," which says that you're allowed to do whatever the heck you want with the mod. All of Apocalyptech's BL2/TPS mods are licensed this way, for instance.

Slightly more restrictive than that are the various Creative Commons licenses. At their most permissive, they just tend to say that you can use the mod however you like so long as you keep an attribution about who wrote it originally. Apocalyptech's been using CC BY-SA 4.0 for his BL3 mods, which says that you can share and modify the mods all you want, so long as you attribute Apocalyptech for the original mod, and allow others to do the same with your modifications.

Obviously licensing is a very personal choice, and you're welcome to use whatever you like here, but having some explicit license for your mods can prevent confusion and mis-communication in the future. Even if you just say that "redistribution or use in mod packs is not allowed without explicit permission," that's better than saying nothing.

Screenshots, Videos, Nexus Mods Links, and other URLs

To link to external resources like screenshots, or to provide an alternate download to Nexus Mods, you can specify a number of other attributes in your header. For instance:

@homepage https://your-awesome-mod.biz/
@screenshot https://i.imgur.com/ClUttYw.gif
@screenshot https://i.imgur.com/W5BHeOB.jpg
@video https://www.youtube.com/watch?v=JiEu23G4onM
@nexus https://www.nexusmods.com/borderlands3/mods/128
@url https://borderlands.com/en-US/news/2020-09-10-borderlands-3-patch-hotfixes-sept-10/

@homepage can only be specified once, and defines a main homepage for the mod, if you happen to have one. @screenshot, @video, and @url can be specified multiple times. Screenshots will be embedded on the wiki page, whereas Videos and URLs will just be linked. @nexus can only appear once in the file, and can point to an alternate download location for the mod on Nexus.

Pakfiles

Some modders have started playing around with pakfile modding, where a new pakfile is added to the game's Paks directory. This allows for more flexibility and power than the hotfix-based modding we usually do, though it's still in a nascent state and requires a completely different modding pipeline.

The ModCabinet currently supports both pure Pakfile mods and "hybrid" Pakfile mods (which use both hotfixes and new Pakfiles). For pure mods, make sure that your mod-description filename has a .bl3pakinfo extension rather than .bl3hotfix, but the file otherwise has the same syntax as "regular" hotfix mods. To link to the pakfile properly, use a @pakfile tag to link to a pakfile, which will then be linked to from the mod's page. This tag is required for .bl3pakinfo description files:

@pakfile ModName_999999_P.pak

If given just a filename like that, the cabinet will assume it lives in the same github directory as the hotfix mod itself. You can instead provide a URL to the pakfile, if it's hosted elsewhere:

@pakfile https://geocities.com/my_cool_page/Mod_Name_999999_P.pak

As a note for pakfile mod authors: pakfile filenames should end with something like _999999_P.pak. The exact number to use is up to you, but you'll probably want it to be at least 30. A large, obvious number like 999999 seems like a reasonable choice, though. Pakfiles should get installed into an OakGame\Content\Paks\~mods directory, and subdirectories or file renames can be used underneath that to enforce load ordering (they will load in alphanumeric order by directory name).

Update Frequency / Error Reporting

The process which updates the BL3 ModCabinet wiki checks for new/changed files every ten minutes. You can see when the wiki was last updated by visiting the Wiki Status page. That page will also show you any errors which happened during the last update. If you had a typo in one of your category names, or something, it will show up on that page.

Formatting your README for Maximum Results

BL3 ModCabinet will automatically include information from your README files if it's able to understand how it's laid out. You'll have best luck if you format your README files with Markdown (so name them README.md, for instance), but it will also understand plain-text README files.

In a directory with only a single mod, make sure that the main part of your mod description is in a section with a heading of Description, or that it's at the top of the README file (or in the very first section, if there's nothing right at the beginning). That will be imported into the BL3 ModCabinet wiki. If you have a section named Changelog, that will be imported into the ModCabinet page as well. For an example of a ModCabinet page which has pulled in all these elements, see Apocalyptech's BL3 Better Loot, which was generated using this README.

In a directory with multiple mods, ModCabinet needs to have a clearly-marked section of the README file which has the same name as the mod. Sections in the modfile can be marked with any of the usual Markdown-style section headings such as hashes (#) or underlines (--- or ===), even if it's not Markdown. You can also use Markdown-style list syntax, where the line containing the mod name is prefixed by a dash (-). For instance, see this README from Akathris, from the BL2 ModCabinet wiki.

That's it!

Just make sure that your mod has the necessary info at the top of the mod file, and it'll get picked up the next time it's run. If you have problems, feel free to stop by the community Discords and ask for help. (Apocalyptech is the maintainer of this code at the moment, if you wanted to @ him specifically.)