(Last updated: February 28, 2018)
Borderlands 2 + TPS UCP Logos

I recently 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 which attempt to balance and change aspects of the games that some folks had felt were lacking. Many of the changes relate to providing buffs to weapons seen as underperforming, for instance.

(Additionally, it turns out that there's a very lively modding scene for BL2 and TPS in general, which was news to me, though clearly I'm late to the game here. Check out the BLCM Project on github, or its more easily-browsable wiki.)

Folks running Windows have it easy: there are a few apps linked on the UCP pages which basically just take care of everything for you and let you get right to the action, but on Linux there's more fiddling to do. In particular, finding out how to enable these for The Pre-Sequel required quite a bit of Googling around to figure out. So, I figured I'd collect all the necessary information on one page. This may help out Mac users as well, though this page is only written with Linux in mind.

Sources

I feel I should point out that I didn't discover any of these techniques myself. This page is just an aggregation of a variety of sources online, to hopefully save future Linux BL2/TPS patchers a bit of trouble.

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!

The Short Version

This page is pretty wordy and probably doesn't need to be. Here's a barebones version of what you'll want to do. The overly-verbose stuff will follow, if you want more details!

  1. Edit your ~/.local/share/aspyr-media/<game>/willowgame/config/willowinput.ini to include a keybinding like ConsoleKey=Tilde
  2. Patch the game's steamassets/willowgame/cookedpcconsole/engine.upk in one of two ways:

    1. Download a pre-patched engine.upk:

    2. Hex-edit the engine.upk yourself:

      1. Decompress the game's steamassets/willowgame/cookedpcconsole/engine.upk using Unreal Package Decompressor (using Wine)
      2. Hex-edit the decompressed file, replacing these hex strings (there will be two instances in the file which need replacing):
        • Borderlands 2: 1B E9 471B A5 14
        • Pre-Sequel: 1B 0A 491B A2 14
  3. Replace engine.upk with your patched version, rename/move engine.upk.uncompressed_size out of the way
  4. Place the UCP patch inside the game's steamassets/binaries directory, with an all-lowercase filename
  5. Load the patch every time you start the game, using the following technique:
    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)
  6. To use FilterTool to manage the patch file, if you want (this is entirely optional), launch it with: java -XX:MaxHeapFreeRatio=50 -jar FilterTool.jar
  7. If you want full mod/patch compatibility, you will then need to ensure that the game's steamassets/dlc directory natively sorts itself in alphabetical order, which would almost certainly require setting up a custom mountpoint just for DLC data. See below for details. Note that the vast majority of mods/patches are unlikely to require this, though some UCP statements will fail without.

As promised, the much wordier version follows:

Step 1: Configure a Console Hotkey

This is the easiest of the steps. Simply open up your willowinput.ini file, which will be found here:

~/.local/share/aspyr-media/borderlands 2/willowgame/config/willowinput.ini
~/.local/share/aspyr-media/borderlands the pre-sequel/willowgame/config/willowinput.ini

Then locate the [Engine.Console] section and set the following line:

ConsoleKey=Tilde

You could also use F6 or some other key, though for console access in FPSes, using the tilde/backtick key is customary.

At this point, you'll be able to bring up the console, but the actually-useful console commands won't be active: the game will pretend you wanted to "say" that command in the ingame chat and just send it out there, rather than actually running anything. So the next step is to get rid of that behavior.

Step 2A: Enable the Fully-Featured Console (by Downloading a Pre-Patched File)

In online directions for Windows users, you'll see instructions to use a hex editor on Borderlands2.exe or the like, but the hex strings they specify don't actually exist in the Linux binaries for the game (which isn't really surprising).

Instead, you've got to patch the file engine.upk, which will be found in this location:

SteamApps/common/Borderlands 2/steamassets/willowgame/cookedpcconsole/engine.upk
SteamApps/common/BorderlandsPreSequel/steamassets/willowgame/cookedpcconsole/engine.upk

The quickest way to accomplish this will be to simply download a pre-patched file online, assuming you trust these sources. As of February 2018, I can confirm that both of these are valid and patch the file properly.

Step 2B: Enable the Fully-Featured Console (by Hex-Editing Yourself)

Alternatively, it's not difficult to hex-edit that engine.upk file yourself:

The game's packaged engine.upk is compressed, and you have to hex-edit the uncompressed version of the file. At the moment, I only know of one way to do this: using the "Unreal Package Decompressor" found at http://www.gildor.org/downloads. That's a Windows program which must be run via Wine, but it works quite well.

So, download decompress.zip, unzip it to get decompress.exe, and then run it against engine.upk like so:

$ wine decompress.exe engine.upk

That will create a new directory named unpacked, and inside that directory will be the uncompressed engine.upk.

Now edit the uncompressed engine.upk inside a hex editor. I personally just use the bare-bones console hex editor named hexedit, which I assume is available on most distros. The value you want to change depends on whether you're editing the file for Borderlands 2 or The Pre-Sequel, though in either case there are two locations in the file where you need to change it:

  Change From   Change To
Borderlands 2: 1B E9 47 1B A5 14
The Pre-Sequel: 1B 0A 49 1B A2 14

Again, remember that there will be two locations in the file which require that change.

Now that you have a patched engine.upk, rename/move the original engine.upk out of the way, replace it with your edited engine.upk, and also rename/move the accompanying file, engine.upk.uncompressed_size. You won't replace engine.upk.uncompressed_size with anything, because the replacement engine.upk is already uncompressed.

Note: One of the Reddit posts I linked to also talks about hex-editing willowgame.upk. This is not actually necessary for the UCP, or for other mods found online. The edits to willowgame.upk just enable some special development commands like changing levels, setting player level/money, etc.

At this point, you should be able to launch BL2/TPS and find out if the patching worked. Pull down the console and type some nonsense like "foo". Without the patching, the game will just put "foo" into the ingame chat. If the patching was successful, you'll get a notice in the console saying "Command not recognized: foo".

Step 3: Install and run the patch!

Okay, we're through the tricky bits! All you've got to do at this point is put the patch file (using an all-lowercase filename) inside the game's binaries directory, which will be at:

SteamApps/common/Borderlands 2/steamassets/binaries
SteamApps/common/BorderlandsPreSequel/steamassets/binaries

Then, from the game's console, on the main loading screen, you can send it the following command, substituting the filename for whatever you used:

exec patch.txt

If it worked, there should be a brief pause while the game executes all the commands saved in the patch file. If you get about four errors on the console about "No objects found using command (foo)", you're running up against a crossplatform issue which is annoying to fix -- check Step 5, below, for ways around that. Note that the majority of the patch will continue to work just fine even with those errors, so you'll generally be all right without fixing it.

There are two gotchas which you'll want to keep in mind:

  1. The Linux version of B2/TPS requires that the filename be in all-lowercase. When you use the console to specify the filename, it'll silently convert what you typed into lowercase when trying to load, even if you type it in uppercase. (This will result in a confusing error message, since the error message will retain your uppercase characters.)
  2. The patches will only actually work if you load them from the main "loading" screen, which just has the big ol' Borderlands logo on it with "Press any Key" at the bottom, not from the main menu. You'll also want to only load the patch after the game has discovered all your DLC, so the whole loading procedure should be:

    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. Then load the patch.
    If you load the patch file from the main menu, there'll be no indication that anything failed, but the patch won't actually have taken effect. (The easiest way to verify is to observe that Eridium/Moonstone doesn't automatically get picked up like money.)

Note that you'll have to run the "exec patch.txt" command once every time you launch B2/TPS. I think I saw something about a technique to have it auto-execute, but I didn't look into it and don't currently care enough to dig around more.

Step 4: Using UCP's FilterTool (optional)

One of the neat utilities provided by the BLCM project is a utility called UCP Filter Tool. On Windows, this utility handles all the necessary patching and configuration shown above, which doesn't work on Linux, of course. But it also provides a great method for enabling/disabling parts of the UCP patch on a case-by-case basis (in case you want some functionality but not others), and also aggregating other mods into one big patch file, so you only have to "exec patch.txt" for a single filename. That stuff works fine on Linux, so it's worth setting up.

Running FilterTool is entirely optional, though. If you want to run UCP as-is without tweaking any of it, there's no need to run it. Even if you do want to tweak anything in there, the patch files are just text files and you can edit them in any text editor. Just use a hash sign (#) to comment out any commands you don't want to run.

Regardless, to run FilterTool, download the zipfile from the Dropbox link in FilterTool's documentation, unzip it, and, for convenience, copy FilterTool.jar into your game's binaries directory (the same place you put the patch file):

SteamApps/common/Borderlands 2/steamassets/binaries
SteamApps/common/BorderlandsPreSequel/steamassets/binaries

FilterTool is a Java app, so you need a Java runtime installed. OpenJDK, the default for many distributions, should be fine. On Linux (and Mac, as it turns out), you do need to specify one strange commandline option when launching, or the utility will exit almost immediately with no error messages or warnings whatsoever. From the same directory as the patch file and FilterTool.jar, you'd run:

$ java -XX:MaxHeapFreeRatio=50 -jar FilterTool.jar

FilterTool expects that the filename you're working on will be "Patch.txt", with a captial "P", which is at odds with the case requirements of actually running the patch inside Borderlands itself. The utility does let you open/save arbitrary filenames, but personally I just bowed to convenience and set up a symlink 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

So FilterTool is operating on the "real" file, while the symlink is there to provide Borderlands with a lowercase version of the file to load. It's a bit hokey, but it's convenient.

Step 5: Mod Directory Sorting Fixes (Optional, but you won't have full compatibility without it)

This is a rather strange step which is required 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.

Conclusion

So, that's it! Not a trivial amount of work to get going, really, though in the end it's pretty straightforward. The main hurdle that I had was that all the information to get this going on Linux was spread out over a number of different places online, and it took awhile to aggregate all the info and figure out what needed doing. Hopefully this page ends up helping someone else get to those answers a little more quickly!

As I said above, 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 28, 2018
  • Include link to pre-patched TPS engine.upk file
  • Notes on mod directory filename ordering
January 20, 2018
  • Initial post