(Last updated: February 22, 2019)
Borderlands 2 + TPS UCP Logos

Some time ago, I became aware of the Borderlands 2 Unofficial Community Patch (UCP) and the Borderlands The Pre-Sequel Unofficial Community Patch (UCP), some fan-produced mods/patches to Borderlands 2 and TPS, and the rather lively modding community which produced them. Check out the BLCM Project on github, or its more easily-browsable wiki for a rather overwhelming amount of mods to sort through.

At the time, getting mods set up on Linux (and Mac) was a little more involved than on the Windows side, since the automated tools to enable mods in BL2/TPS which worked on Windows didn't work on Linux systems, and the alternatives required some manual effort (and data collation, which is why I'd originally put this page up).

BLCMM: Enable, Manage, and Create Mods

As of July 10, though, the Borderlands Community Mod Manager (BLCMM) was released, which features new methods of enabling mods on Linux and Mac, and works a treat! So, that is now the recommended way of enabling mods on Linux and Mac. There's still some "gotchas" when using BL2/TPS mods on Linux, but since the original creation of this page, the modding project's wiki has been updated quite a bit, including a page on Linux and Mac Setup Gotchas, which details most of what this page used to.

So, honestly, at the moment those are your best resources! Install BLCMM to get mods running (and manage your mods), and take a look at that "Gotchas" page to make sure you're aware of some of the other things. (Disclaimer: I've been helping out with BLCMM development for awhile now, so obviously I'm biased. It's pretty great, though.)

Issues to Keep In Mind

These are mostly all mentioned in the Linux and Mac Setup Gotchas page of the BLCMods project, but I'm keeping them here as well for reference, since they're already written and why not?

Case-Sensitive Filenames

When you try to execute patches in Borderlands 2/TPS on Linux, the filename that it tries to execute will automatically be converted to all-lowercase before it looks for the file. So if you have a file named Patch.txt (with an uppercase "P") and try to exec Patch.txt (also with an uppercase "P") , you'll get a confusing error message saying that it couldn't execute Patch.txt, even though the file clearly exists.

So, make sure that your file is all-lowercase. If you want to keep the original case of the distributed UCP files, you can always set up symlinks like so:

lrwxrwxrwx 1 pez pez        9 Jan 20 23:01 patch.txt -> Patch.txt
-rw-r--r-- 1 pez pez  2209697 Jan 20 19:27 Patch.txt

or:

lrwxrwxrwx 1 pez pez      12 Mar  1 15:18 patch -> PatchTPS.txt
-rw-r--r-- 1 pez pez 5211039 Jul  9 01:00 PatchTPS.txt

Execute Mods From the "Press Any Key" Screen

Windows users are able to execute mods right from the main menu (where your character is seen shifting weight occasionally), but that doesn't work on Linux or Mac. Instead, we've got to execute the patch from the "Press any key" screen, though you've got to first hop into the main menu to ensure that all the DLC is loaded. So, to run patches, this is the sequence:

  1. Start the game, click any key to get to the main menu
  2. At the main menu, hit escape and say Yes to get back to the loading screen.
  3. Bring down the console, run: exec patch.txt (Or whatever filename you used)

Note that Linux/Mac doesn't have a handy autoexec method like Windows has. That's one area where we're still lagging behind.

Disable "Sanity Checks"

When Borderlands loads a savegame, it runs all the weapons and items in the savegame through a "sanity check" to make sure that the items are valid. If an item/weapon is discovered which fails the check, it is silently removed from your inventory. If you don't notice at the time and the game saves over your game, you'll have lost that item. (Hitting Alt-F4 to force-quit the game would prevent overwriting your save, if you notice in time.)

Some Borderlands mods will create items which would otherwise run afoul of this sanity check. So long as you remember to execute the patch/mod before continuing the game from the main menu, the sanity check won't touch your modded weapons, but it's easy to occasionally forget to execute the mod before actually loading the game, which could lead to lost items. So, the solution is to disable these checks!

c0dycode has a Borderlands Mac and Linux Stuff page with information on hex-editing to disable this check, along with a little Python script to automate it for you. (c0dycode also created a Hex Multitool project for Windows which does this and other tweaks, but that only works on Windows binaries.) For reference here, these are the values you'd need to tweak if you wanted to hex edit yourself:

  Change From   Change To
Borderlands 2 (item check): E8 A9 24 17 00 90 90 90 90 90
Borderlands 2 (weapon check): E8 F7 23 17 00 90 90 90 90 90
The Pre-Sequel (item check): E8 CF 94 17 00 90 90 90 90 90
The Pre-Sequel (weapon check): E8 0D 94 17 00 90 90 90 90 90

Mod Directory Sorting Issues

NOTE: OSX's historical filesystem, HFS+, does not have this problem but starting with 10.13/High Sierra, APFS is starting to be used, and that does appear to have the same problem that Linux users have. If anybody has experience setting up alternate mountpoints in macOS, let us know (or edit this page) to let us know how to address it on those platforms.

This is a rather strange situation which occurs because of some cross-platform differences between Windows and Linux, and because of some behaviors of the Borderlands engine.

Basically, when looking for DLC on your hard drive, Borderlands looks inside the steamassets/dlc directory and loads the mods in the order they're given by the kernel. On Windows, the filesystem driver will return the directories in alphabetical order by default. On Linux, the order of the directories is effectively random. (When looking at a directory listing via ls on Linux, the ls command does the sorting for you. If you want to see the "native" order in which the directory entries are given, you can run "ls -U" or "ls --sort=none".)

As the engine loads these DLC, some of the property names get dynamically-assigned number suffixes, and the numbers depend on what order the DLC is loaded. Mods which try to edit these values need to hardcode a number to use -- any mod written/tested on Windows is going to be using the numbers you get by sorting the directories alphabetically. For instance, the internal part list collection for one class mod from the Dragon Keep DLC has this property name:

GD_Aster_ItemGrades.ClassMods.BalDef_ClassMod_Aster_Assassin:ItemPartListCollectionDefinition_28

However, on my main Linux desktop system, the property was showing up as:

GD_Aster_ItemGrades.ClassMods.BalDef_ClassMod_Aster_Assassin:ItemPartListCollectionDefinition_42

And on my laptop it was a different number entirely. This doesn't have a super wide impact, since there aren't that many mods which actually touch these variables, but UCP does contain a few statements which do, and you'll risk not getting the full effect of some mods.

So, how do I fix this?

Unfortunately, the only real fix for this is to mount your Borderlands DLC directory under a separate filesystem which supports sorting directories alphabetically. No native Linux filesystem does this. It's possible to disable some features on an ext4 filesystem, so that directory entries will be given in the order in which they were created. So theoretically you could create an ext4 partition, use the following tune2fs command on it:

# tune2fs -O ^dir_index /dev/foo

... and then carefully copy the DLC directories into that filesystem, one at a time, in alphabetical order. That method seems quite fragile to me, though, and I wouldn't recommend that even though you'd still be using a native Linux FS.

What I've done on my own system is to just resign myself to using NTFS. The Borderlands 2 DLC dir contains a little over 6GB of data, so I created a new 10GB LVM LV, used "mkfs.ntfs /dev/vg/bl2dlc" (obviously substitute the proper device name there), copied over all the DLC data into that new filesystem, and then added the following to my /etc/fstab -

# Borderlands 2 DLC Modding Nonsense
/dev/mapper/vg-bl2dlc  /usr/local/games/Steam/SteamApps/common/Borderlands\0402/steamassets/dlc   ntfs    uid=1000,gid=1000,umask=022   1 2

Note the special string "\040" in the pathname, required because there's a space in the directory name. Adjust the device name, path, UID/GID/unmask, etc, to suit your circumstances. Make sure that the dir is mounted properly and that the DLC data is in there, and you should be good to go. You can use "ls -U" in the DLC directory to verify that they're showing up in alphabetical order now.

So... yeah. That is quite weird, and I suspect not a lot of folks are going to be willing to do something like that to their system, just to support some game mods. Still, if you're looking for 100% mod compatibility inside Linux, this is a step you'll have to deal with.

Legacy Information

If you'd still like to take a look at all the older info about replacing engine.upk files (no longer necessary), and other fiddly bits like that, take a look at the legacy page.

Conclusion

So, that's it! Aside from the directory ordering thing, things are pretty straightforward now that BLCMM's been released. If there's anything in here which is wrong, incomplete, needs streamlining, or just if there's something else which would be useful to have on this page, feel free to contact me!

Changelog

February 22, 2019
  • Added note about APFS on macOS.
July 10, 2018
  • Updated to reflect the release of BLCMM
  • Moved now-unnecessary info to a "Legacy" page
May 18, 2018
  • Be more explicit about getting rid of the uncompressed_size file
  • Linked to BLCMods wiki Linux+Mac Setup Page
  • Added Sanity Check info
February 28, 2018
  • Include link to pre-patched TPS engine.upk file
  • Notes on mod directory filename ordering
January 20, 2018
  • Initial post