payday 2 how to install mods

Doyle Criall97 · Thursday, November 11, 2021

Setting up Payday mods: From A to Z

Intro :

So chances are, if you're reading this thread, you are relatively new to Payday mods. There are various guides and snippets of information on how to set everything up, but there is a distinct lack of organization not to mention mass confusion. Instead of directing users to 10 different threads in search of this information, I've decided to make a fool-proof guide that even the most computer-illiterate people are able to use.

So you want to mod Payday, huh?:

Well before we get started, you're going to need a few things:

The Lua Hook (Download Here) - These files are the fundamental base for modding Payday. IPHLPAPI.dll injects the code that you specify in the PD2Hook.yml (but we'll get to that later).

Notepad++ (Optional, but highly recommended) (Download Here) - Notepad++ is like Windows Notepad, but on steroids. It shows syntax highlighting and is very helpful for ensuring that you formatted the code correctly.

Okay, I've got the everything. Now what? :

Once you download the Lua Hook, extract the .zip file so you can access the contents. The next step is simple enough: Copy and paste these files into your Payday directory.

Unless you selected a custom install location, your Payday 2 directory will be located at:

Code:

C:\Program Files (x86)\Steam\SteamApps\common\PAYDAY 2

For Payday: The Heist:

Code:

C:\Program Files (x86)\Steam\SteamApps\common\PAYDAY The Heist

Now, before you go off and try to start Payday, there are a few more steps that you'll need to complete before you're begin your modding journey.

I looked inside PD2Hook.yml and it's like a foreign language... :

I'm aware the contents look quite intimidating at first, but once you get the hang of things, configuring it is like second nature.

I'm going to break this section down into sub sections to discuss each of the 4 parts of the PD2Hook. Before I begin, I'd like to mention it is imperative that you maintain the correct spacing in this file (this is where Notepad++ comes in handy) as failure to do so will result in failing to hook the Payday 2 files.

~Config: - The only thing you'll possibly want to change in this section is the Output number. Below describes what each value (0-7) represent. The default setting is 1, which logs the console output to Debug.log. You'll likely either want 1 or 3 to begin with, and 7 if you decide to get much more in-depth in PD2 modding.

Code:

0 = No output 1 = Prints the log to a text File 2 = Shows the log in a Console window 3 (1+2) = Prints the log in a text File & Shows the log in a Popup console (4 = turns on the interactive interpreter) 6 (2+4) = Use the interactive interpreter in the Popup console 7 (1+2+4) = Use the interactive interpreter in the Popup console & Print the log in a text file

~Keybindings: - This section contains the scripts that you wish to run (or toggle) on each press of the selected key. I've included some example KeyBindings to show you the correct formatting.

VK_F1 stands for the Virtual Key F1. Virtual Keys represent the physical location of each Key (in this case, a US-English keyboard). These Virtual Keys can be represented by constants or hexadecimal values.

For example, F1 is represented by the constant VK_F1 or the hexadecimal equivalent 0x70. You can use constant and hexadecimal values interchangeably for the Keybindings:

Code:

            - [VK_F1, scripts\script1.lua]   is the equivalent of:   - [0x70, scripts\script1.lua]

You can edit this to your preference using the compilation of Virtual Key Codes found here.

scripts\script1.lua is defining the location of the script you wish to bind to the before-mentioned Virtual Key. In the Lua Hook files, I've included an empty directory for you to place your scripts in (so your Payday directory won't be so cluttered (like mine..)).

So, if I placed a script in my scripts folder named Waypoints.lua and bound it to the Caps Lock key it would look like this:

Code:

KeyBindings:  - [VK_CAPITAL, scripts\Waypoints.lua]

Make sure to remove all lines that do not actually link to a file (delete - [VK_F2, scripts\script2.lua] etc etc)

~PersistentScripts: - Persistent scripts are the second easiest to get working, as long as you format the actual scripts correctly.

TestVar1 is the Test Variable that is defined in the script. We will get into this more when we talk about using scripts, for now just ignore it.

scripts\script3.lua is the same as above.

There is one essential script that you will need to avoid tons of errors. The functions compiled in this script are what are known as Globals. Basically, many scripts run a check to see if you are in game, in chat, etc but unless you have a Globals script they won't know how to run this check. Users can paste the section of required global functions in the script to resolve this issue, but it's much better to have these functions in a globals script instead of having to reiterate them every time you write a script. These global functions are a necessity when using persistent scripts, because they define when the scripts are able to run. The "if inGame() and isPlaying() then" check ensures that the only time the script will run is when you're actually playing. They are key to saving you processing power and thus improve the performance of your game.

@B1313 made a rather nice write-up on Globals in this thread. Coincidentally, I will use this as an example on how to add Persistent Scripts (assuming you named the script globals.lua and placed it in the scripts folder):

Code:

            PersistScripts:            - [GlobalScriptInitialized, scripts\globals.lua]

Make sure to remove all lines that do not actually link to a file (delete - [TestVar1, scripts\script3.lua] etc etc)

~PostRequireScripts: - Post Require Scripts are by far the best way to run a script. Unfortunately, these are the least user-friendly form. The way a Post Require script works is when a specific file is called in the game, the script overrides the functions that the file contains.

As an example...

Code:

PostRequireScripts:  - [lib/managers/menumanager, MyScriptsFolder\MyFirstScript.lua]

This will call the MyFirstScript script whenever the internal game file "menumanager" is required (something that is done internally). Often times script developers will specify what paths to use.

Another excellent point is that since about hook version 2.2.0, we can do wildcard post requires. This is especially useful if you have a variety of functions you desire to override and contain all in a single file or just a few but would be silly to make separate files for such short overrides. Prime example being that of "Inspect Player" by @B1313.

As an example...

Code:

PostRequireScripts:  - ["*", MyScripts\MassiveOverride.lua]

MassiveOverride:

Code:

if RequiredScript == "lib/managers/menumanager" then     -- do stuff here elseif RequiredScript == "lib/tweak_data/tweakdata" then     -- do different stuff here end

RequiredScript is a pre made global variable by the hook that will take the form of the current required script at any given time. So in the above case, the script is executed on all requires, but nothing happens until the RequiredScript variable matches it's equality counterpart (ie the string it's being compared too [ie the "lib/tweak_data/tweakdata" string, for example]).

Wildcards are especially useful if you have 10+ functions that need overriding but only when a specific script is required internally. If you have less, say something around 2 or 3, then it still works, but the long method is just as good too.

Long method being...

Code:

PostRequireScripts:  - [lib/managers/menumanager, MyScripts\MassiveOverride.lua]  - [lib/tweak_data/tweakdata, MyScripts\MassiveOverride.lua]

In this case only when the RequiredScript variable matches the paths specified will the script be loaded, this has the same effectiveness as using a wildcard, but may have a slight better RAM conservation ratio as you're not checking the variable 4 times on each require (only 2 times)...but that's of little consequence as once it is indeed correct, it will recheck it for the if/else statement (do keep in mind, you can use if then end, if then end, ... statements instead of 1 massive if elseif statement and it actually may require that in some situations).

Wildcards can be a very effective solution if you want to make a single hook entry or have a single script be responsible for several overrides for different internal files and conserve YAML hooking space.

To recap, most of the time, if a script is meant to be run as a post require the author of the script will tell you what path you should use. Otherwise, I would highly recommend that you refrain from attempting anything on your own.

Make sure to remove all lines that do not actually link to a file (delete - [path/to/game/file, scripts\script5.lua] etc etc) or fix them so they indeed point to a legitimate internal file path and an existing file in the working directory.

Finally, you've made it to the fun part! :

I'm sure by this point you're overly bored from reading all of that (Yeah, I know you just scrolled down to this part instead of reading...) but it's important that you know how to edit your PD2Hook. Otherwise, your scripts will not work (and your game will likely crash).

There are so many options when it comes to scripts. You can head on over to our Lua Snippets sticky for a great collection of the best scripts or if you're feeling more picky you can use the search function and find exactly what you're looking for.

When you finally decide on a script that you would like, make note of how the author said to run the file. Copy the script and paste it into notepad. Save the file to your scripts folder as <scriptname>.lua MAKING SURE that you use the correct file extensions (examples of incorrect file naming: script.lua.txt or script.lua.lua). Using Notepad++ should minimize this mistake.

~If the script is meant to be run as a Keybind, follow the directions in the KeyBinding section of the PD2Hook breakdown.

~If the script is meant to be run as a Persistent Script, use the TestVar that the scripts author defined in the thread. If you use the wrong TestVar, the script will run multiple times a second which eats CPU power for breakfast, lunch, and dinner. If the thread author didn't specify the correct TestVar to use, you can decipher the TestVar from the beginning of the script. It should look something like this:

Code:

            if not            BagModifications            then            BagModifications =              true            *****Script functions here*****            end

In the above example, the TestVar is BagModifications.

~If the script is meant to be run as a Post Require Script, use the file directory that was provided in the author's thread.

And that's it! If you followed everything correctly, you shouldn't run into issues (at least until a bit further in your modding career )

What do people mean when they say "commented out"?

Often times coders will insert tid-bits of "invisible" information to make the code more readable and instruct the user on how to configure it properly. In Lua, putting two dashes (i.e --) will comment out the rest of the code on that line. For example:

Code:

            function            example()            example.code.here =            true            -- Change this to false if you prefer to not run example.code.here            end

or:

Code:

            function            example()            --This function does whatever I defined the function to do            example.code.here            end

In the first example, the script author is advising a user on how to change the code to produce the desired effect. In the second example, the script author is describing what the function does. Lua is not picky about the location of the comment. It can come at the beginning of the line or halfway through.

You can also comment out entire blocks of code by putting brackets around it. This is called nesting:

Code:

            function            example1()            example1.code.here            end            --[[function example2()    example2.code.here end function example3()    example3.code.here end]]            function            example4()            example4.code.here            end

In the above code, only the function of example1 would be run. While the code for example2 and example3 are still present, commenting them out makes them appear as if they weren't there. Nesting is a great way to block/comment and control large sections of code where using -- would be impractical. (i.e you want to comment out 200 lines of code in a script).
To begin the comment nesting syntax, you would use: --[[
To end the comment nesting, you would use ]] at the end of what you wanted to comment out.

In your PD2Hook.yml file, you will see lines commented out with the pound symbol (#). To my knowledge, you cannot comment out blocks of code in .yml files. The comment is only in effect for the line that it was placed on. For example, to comment out multiple lines in our PD2Hook:

Code:

                          PostRequireScripts:                          - [lib/managers/weaponfactorymanager, scripts\postrequire_attach.lua]                                                      #- [lib/managers/playermanager, scripts\playermanager.lua]  #- [lib/managers/moneymanager, scripts\moneymanager.lua]

This would effectively remove the payermanager and moneymanger script without having to physically remove the code. I've got 99 problems and Lua Modding is 1 :

This section is dedicated to troubleshooting. By far the most common issue that users encounter is because they did something wrong. The first thing you should do is re-read this tutorial and see where you went wrong.

There are 4 files that describe the conditions of why the game crashed:

The MDMP file that appears in your Payday directory after a crash.
The game's crash log (located at C:\Users\%username%\AppData\local\PAYDAY 2\crash.txt). I've included a shortcut to this file in the Lua Hook files you downloaded earlier, called crashdump.
The Hook log located in your Payday directory (called Debug.log). This will help if you're experiencing issues with scripts not running properly.
The .ICRASHED file which appears in your Payday directory. This file only appears when you have incorrectly edited your PD2Hook.yml file (usually when you try to bind a Virtual Key incorrectly).

If you cannot figure out what in the world you are doing wrong, then read this thread on how to correctly post your crash reports instead of saying "halp me plz my game crash every time i start" so that we can actually help you.

Thanks to B1313 for critiquing the tutorial and providing pointers

Note from the author: If I've failed to mention anything or explained something incorrectly, please notify me and I will fix it!