Beardlib Editor Tutorials
Guides and information on creating custom heists using BeardLib Editor.
- Getting Started
- Units - Building Your Level
- Elements - Scripting Your Level
- Continents And Scripts
- Sequence And Sequence Triggers
- Asset Management - Database, Packages, and Local Files
- Player Spawns And Team-AI Idling
- Whisper State - Stealth and Loud
- Security Cameras
- Environmental Damage - KillZone Element
- Building Navigation
- Manipulating Navigation Mid-Game
- Guard / Civilian Patrols
- Assault Waves
- Harassers and Snipers (+ Hiding Cloakers) [wip]
- Captain Winters
- Custom Content
- (Old pages, still useful for reference)
The place to begin your mapping journey.
BeardLib Editor, or BLE for short, is a mod for PAYDAY 2 that adds a fully functional level editor to the game. With it players are able to create their own fully custom missions and levels. Installation is very simple and you can be ready to go in minutes with just a few steps:
Before installing BLE, make sure you have all the requirements installed:
- Download and install SuperBLT by following the instructions on the website.
- Download BeardLib, preferably the Github version, and extract it into
C:\Program Files (x86)\Steam\steamapps\common\PAYDAY 2\mods.
- Additionally some parts of the editor require .NET 5.0 or higher. Download the Microsoft provided exe and run it.
- Now you can download BeardLib Editor from Github and install it by extracting it into
.../PAYDAY 2/modsas well.
Launching the game will pop up a message asking you to download the Editor Data, press yes and wait for the download to finish.
The data contains important files the editor needs to function properly. You only need to download it once when first installing the editor, or when a major game update releases.
You can now access the editor by pressing the gear button with the cube, or load back into your last edited level by pressing the button next to it.
Alternatively you can access it by going into Options and BeardLibEditor Menu.
Keep in mind that with BLE installed, you will not be able to play with other people because the physics fix required to make the editor work can cause issues in multiplayer. To play with others, either uninstall the editor or press the Disable Physics Fix button in the editor options. Remember to enable it again when you want to use the editor.
You also need some external software in order to create or edit files for your map:
- Image editors like Photoshop or GIMP to create and edit textures.
- Text editors like Notepad++ or VS Code to edit XML or Lua files.
- Audio editors like Audacity to record or edit voice lines and sound effects.
- Diesel bundle Viewer to open and extract files from PAYDAY 2 directly.
- Not really external software, but the ReLua mod can be really useful to quickly reload your mods without having to restart.
Advanced users may also need:
- 3D Software like Blender or Maya to create custom models.
- Diesel Model Tool to convert your models into the right format.
Additional Debugging Tools:
The QA Panel is a very useful tool for mapping. It shows you the current FPS and how much memory your level is using.
To enable it, right click on PAYDAY 2 in the steam library, go to properties... and type
-qa into the text box.
This is a basic rundown of the functions and capabilities of BeardLib Editor. Everything here is simplified with a basic explanation.
More in-depth guides are available on other pages.
BeardLib Editor Menu
The BeardLib Editor Menu is where you manage your projects, open levels to edit, convert and debug files as well as change settings for the editor.
In the Projects tab you can open and edit your projects, and create new ones. Opening a project lets you edit the individual modules inside it, such as narrative or level. You can add new modules by pressing the “plus” button. The Module Properties lets you tweak your module’s settings.
Anything here can also be edited by opening your project’s main.xml with a text editor.
The Levels tab lists all available levels in the game. You can toggle vanilla and custom levels, as well as toggle if the list shows narratives or individual levels.
Before entering your level, you can toggle various options, such as difficulty, mission filter or one down, which can also be changed on the fly in-editor.
Debug options include:
Safemode: Disables most of the editor functions and basically only lets you manage loaded assets.
Check Load Time: Pops up a window after opening the level, telling you how long it took to load.
Log Spawned Units: Lists all units spawned in your level in the console and the log files found in
To open and edit a level, simply click on it in the list and confirm.
ScriptData lets you convert files between various formats, most notably custom_xml and binary. It’s mostly used for converting custom sequence managers as the game requires them to be in binary, but can also be used for other files like .continent or .mission.
Use the file browser on the left side to navigate to the folder of the file you want to convert. Click on your file on the right side of the screen, choose the formats and convert.
With Check File you can open files from a unit and see what other files it’s linking to and whether or not they are currently loaded.
As of writing this, the Check File feature is not functioning properly.
Options lets you change general settings, for example how levels are being saved or showing tips or the toolbar, as well as customize keybinds and the visuals of the UI.
The BeardLib Editor Menu can be accessed at any time while in the game’s main menu or in-editor through the options, though some changes may not instantly apply and require a reload of the level.
The Toolbar gives you quick access to various commonly used settings, without having to navigate through menus.
- Grid size - Left click grid-icon to reset, right click for preset values, or type in your own value.
- Rotation Snap Angle - Left click angle-icon to reset, right click for preset values, or type in your own value.
- Toggle Move Widget
- Toggle Rotation Widget
- Draw Editor Units
- Show Elements
- Ignore First Raycast
- Local/Global Transform Orientation
- Teleport Camera
- Teleport Player to Camera
- General Options (BeardLib Editor Menu Options)
The Main tab lets you load assets either from Database or from Packages. Asset loading is largely handled automatically so these options are not needed most of the time. Only in some rare cases you might be required to load assets using these.
Managers include the Asset Manager, which lets you see and manage the currently loaded assets and packages in your level, and the Objectives Manager, which lets you create and manage custom objectives.
-> Asset Management
Continents lets you create and manage continents and scripts. You can create new continents by pressing the “Plus” button in the top, and edit existing ones by pressing the gear icon.
The “Plus” icon on a continent will create a new script.
Current Continent and Current Script refer to the continent and script you’re currently editing. Spawning new units and elements will automatically place them in there.
->Continents And Scripts
Camera Bookmarks lets you save the current position and rotation of the camera. You can then teleport the camera to the bookmark at a later point, and even define a new default position when loading into the level.
In the Environment tab, you can choose a specific environment file to change the global lighting in your level.
You can generate cubemaps and light projections and spawn effects, and environment areas. Keep in mind that for cubemaps and light projections, you first need to spawn in cubemap_gizmo and omni_shadow_projection units.
Sky Rotation will affect the position of the sun and direction of the shadows in your level.
Dome Occlusion lets you generate a sort of global ambient occlusion layer.
The Wind settings affect a small number of effects like fog, smoke or fire.
Sound lets you create sound emitters and change sound settings like acoustics, ambience and occasional sounds.
Environment: Changes the acoustics of your levels, how much echo sounds have, etc.
Ambience: Select an ambience sound that plays in your level.
Occasional: Select a background sound that gets played randomly between 6 and 10 seconds.
Emitters will play a selected sound on loop from the position of the emitter.
Sound Environments are used to apply different sound settings for different areas.
Portals lets you set up portaling in your level to improve performance.
Press the “Plus” icon to create a new portal. Create a new shape for the portal by selecting it and pressing the “Plus” icon in the “Shapes” header.
After placing your shapes where you want them, you can press the button to automatically add all units inside the shapes to the portal, or manually add units by selecting them by pressing the “Add to current portal” button.
Further down you can select all units in your current portal, hide them, toggle the red highlight or open a list with the linked units.
The AI tab is for movement and navigation of the AI. You can place nav_surfaces to generate the nav-mesh, calculate all segments, or just individual ones.
There’s debug options showing you, for example, what navigation segments are connected.
Patrol paths for escorts can be created here as well as Cover Points. Press the "Plus" icon to create a new patrol path, and the "Plus" icon in the path to create the individual points. Your path can then later be selected in a SpecialObjective Element.
Click the button to spawn a new Cover Point. Place it in your level with LMB, move your mouse to change it's direction and click LMB again to confirm.
Group State should always be kept at "Besiege" as it is an unfinished feature and crashes the game if it’s changed.
Brush opens the Mass Units editor. It allows you to place mass units in your level for more detail, by simply drawing them like a brush.
On the top are various settings to tweak the behavior of your brush, Clear the entire level of mass units, remove only selected or fix floating units.
After selecting something, this menu opens automatically and you get a wide range of options and settings to tweak, depending on what your selection is.
The Main section, which can also have a different name in some cases, usually includes general information about your selection, like the name, path, continent or script, or if it’s enabled or not.
Quick Actions will always be present, though the available buttons can differ.
Deselect and Delete Selection can be used on pretty much everything.
Create Prefab will take your current selection and turn it into a prefab.
Unit exclusive quick actions:
Add to current Portal and Remove from current Portal do exactly what the name suggests, add and remove the unit to the currently selected portal.
Simulate Physics temporarily turns the selected unit into a dynamic object which is affected by physics. It can help set it into a more natural position. Keep in mind that it might not work correctly, or at all on some units.
Element exclusive quick actions:
Execute to trigger an element manually.
Test available on some elements to test effects, animations etc. without executing the element.
Stop Testing to stop the test.
Instance exclusive quick actions:
Preview instance opens vanilla instances as a level in editor.
Clone Instance will create an exact copy of a vanilla instance as a custom instance.
Edit Instance only for custom instances, opens the instance as a level for editing.
Transform will also be present with all selections, and refers to its position and rotation in the level.
You can change those with the move and rotate widgets, or by typing in a value manually.
Ignore Raycast Once will temporarily prevent your selection from being selected again, clicking it will instead select the object right behind it. This is handy when a unit has too big of a hitbox, preventing the selection of other units inside it.
Grab will grab the selection and temporarily snap it to your cursor.
Round X,Y,Z Values will round the decimal values. If you have a selection with the position of
1.123, 0.1, 0.85, it will round it to
1.0, 0.0, 1.0.
Copy will copy the current value into your clipboard.
Paste will paste the values from your clipboard. Keep in mind that you can’t paste Position values into Rotation and vice versa.
Shapes, such as for portals, environments etc. as well as the Shape and AreaTrigger Elements can have additional Width, Height and Depth options in the transform section.
You can use the search bar to look for something specific and even search for multiple keywords by separating them with a “comma”.
The Unit tab also has some additional filters:
Short unit paths will try to shorten the unit path shown in the list by hiding the first few folder names.
Show Loaded Units Only will hide the units that are not loaded.
Load with Package will open a list with all packages that contain the unit you’re trying to spawn. Normally you don't need to do this, as everything is loaded via database automatically.
When you find what you need, simply click on the item in the list to spawn it. You can now hover in your level and press LMB to place it or RMB to cancel the spawning.
Units will be automatically loaded as soon as you click on them in the list, even if you cancel the spawning. Make sure to unload every unused unit before releasing your map.
You can also pin frequently used items to the top of the list by right clicking them and clicking “Add To Favorites”.
You can use the search bar to look for something specific and even search for multiple keywords by separating them with a “comma”.
When you find what you need, simply click on it in the list to select it. Hold CTRL to select multiple items.
or every item from every page.
Additionally you can filter out continents for units and scripts for elements.
Tools houses many useful features to help you playtest and debug your map, as well as the Effect and Environment editors.
In the General Tab you find the Effect Editor, settings for playtesting, buttons to log your camera position, open the level in windows explorer and toggle the headlight, as well as a breakdown of all the units, elements and instances spawned in your level.
The Environment tab lets you edit and create your own Environment files.
To create your own Environment, use the menus and sliders until you’re happy with it, then press “Include Current” at the top. Give it a name and it will be available to use in the Environment tab in the World menu.
To edit your custom Environment, click on it in the “Include Environments” list to select it. Make your changes and press the “Save” button in the Quick Actions to apply the changes.
Debug gives you various visualization options for AI and information about the current assault phase, area triggers and element executions.
Unit Duality lets you check for any possible duplicated units with the same position and rotation. For example if you accidentally spawned the same unit twice or copy-pasted it to the same position without noticing.
Element Loops checks for any elements that are in an endless loop of executing each other, which could crash the game. Editor Unit Sorter will help you move editor units to a specific continent automatically. Pick a target continent, check which type of editor unit to move and press the button.
World Cameras lets you set up cinematic cameras. With these you can, in theory, create cutscenes for your level, or have consistent camera flights for trailers and the like.
World Cameras can cause various issues in multiplayer so it is not recommended using them in actual heists.
To create a camera, press the “Plus” button in the “Cameras” section. With your camera selected you can now create points the camera moves between, by positioning your view and pressing RMB.
You can change the behavior of the camera in the settings and use the “Play” and “Stop” buttons to test your camera.
Keys lets you define points in the camera’s timeline to transition between settings, you can have your camera roll around between keys or change the FOV.
Sequences lets you can chain up multiple cameras.
Many of these options either have keybinds or can be found in the toolbar at the top, so you most likely won’t need to enter this menu that often.
Creating A New Project
In the BeardLib Editor menu, navigate to the “Projects” tab and click the “New…” button on the right side of the screen.
In the dropdown you can choose between “Map”, “Cloned Map”, and “Empty Map Project”.
Map: Will automatically generate a narrative and a level module in your project. You’re basically ready to go with everything you need to start a new project.
Cloned Map: Lets you make a copy of any vanilla map. Useful for when you want to make map edits or base your level on a vanilla map.
Empty Map Project: Creates a completely blank project with only a localization module.
Make sure to give everything a unique name so it doesn’t clash with other custom heists.
Creating a new project will generate all the files you need in
After creating your project it automatically opens it in the Project Editor. You can access this at any time by clicking on “Edit” and choosing your project. The Project Manager lets you add, edit and tweak most of the modules inside your project.
You can also edit them manually by opening the main.xml in your map folder with a text editor.
After creating the project, navigate to the Levels tab and click on your new level to enter the editor. If it doesn’t show up, restart your game or use the ReLua mod.
After loading you’re gonna see an almost empty level with just a small mockup plane, a player spawner and a startup element, and you can now start placing units to build your level.
The basics of building and scripting a level.
After loading into your level, you can move the camera with W,A,S,D and go up and down with E and Q. Hold SHIFT while moving the mouse to look around. Scrolling your mouse-wheel while holding SHIFT changes your camera speed.
Select something with LMB, add or remove something from the current selection with RMB.
You can box-select by holding CTRL and RMB while moving your cursor and box-remove from the selection with ALT+RMB.
Copy and paste your current selection with CTRL+C and CTRL+V, or delete it with DELETE. Deselect with CTRL+D.
Move or rotate your current selection using the widgets shown on screen. Toggle between them using R and T. Holding ALT while moving a selection will create an exact copy of it.
Grab your current selection with MMB and move it around with your cursor, place it by pressing LMB or cancel the grab with RMB.
Enabling the “Surface Move” option with CTRL-G will snap your selection to the grid while grabbing. The grid size can be changed by pressing PAGE-UP and PAGE-DOWN, or by manually typing it in the toolbar or editor options.
Save your level with CTRL+S or with the Save button in the editor panel. Toggle between Playtest and Editing mode using F10. To completely reset the level and reload the editor, simply press ESC and Restart Game.
These are the default keybinds for BLE.
All those keybinds can be viewed and customized in the “Input” section in the BeardLib Editor Menu Options.
|Toggle Move Widget||T|
|Toggle Rotation Widget||R|
|Toggle Transform Orientation||CTRL+T|
|Toggle Editor Units||F3|
|Toggle Surface Move||CTRL+G|
|Increase Camera Speed||]||SHIFT+MOUSEWHEEL UP|
|Decrease Camera Speed||[||SHIFT+MOUSEWHEEL DOWN|
|Increase Grid Size||PAGE UP|
|Decrease Grid Size||PAGE DOWN|
|Increase Grid Altitute||SHIFT+PAGE UP|
|Decrease Grid Altitute||SHIFT+PAGE DOWN|
|Teleport to Selection||CTRL+F|
|Link to Element Managed List||SPACE|
|Open Element Managed List||M|
|Open Element On Executed List||B|
|Hide Selected Units||V|
|Reset Rotation||NUM ENTER|
|Rotate Spawn Dummy Yaw||J|
|Rotate Spawn Dummy Pitch||G|
|Rotate Spawn Dummy Roll||H|
|Spawn Instance||(not defined)|
|Spawn Prefab||(not defined)|
|Select Instance||(not defined)|
|Select Group||(not defined)|
These keybinds are not listed ingame and cannot be changed.
|Move Camera||W, A, S, D|
|Up, Down||Q, E|
|RMB||Add to current selection|
|SHIFT (Hold)||Look around|
|ALT (Hold while moving selection)||Create duplicate|
|CTRL (Hold while moving selection)||Snap Grid to 1|
|CTRL+RMB (Drag)||Box Select|
|ALT+RMB (Drag)||Box Deselect|
|CTRL+LMB (Hold, Only Elements)||Add to On Executed list|
|CTRL+RMB||Add to current Group|
||Unhides all hidden units|
||Hides all not selected units|
|RMB (Hold)+Move Mouse left/right||Only in number boxes, increase or decrease the value|
Units - Building Your Level
You build your level using what’s called “Units”. Basically everything in this game is a unit. From the level architecture to props, equipment, loot, even characters.
If you don’t know what exactly you’re looking for, you can always open other levels in the editor and see what units have been used elsewhere.
Clicking on a unit in the spawn list and spawning it will automatically load it into your level. Except for some rare cases you don’t have to manually load anything.
Now you can just place it into your level and move or rotate it however you like.
After placing units in your level, there are various settings for them:
Name: Lets you give the unit a custom nickname, so you can find it more easily when searching for it.
Unit: This is the path to the unit file, you can change it by pressing on the “Browse Unit” button next to it. Selecting a new unit path will actually change the unit, however a reload might be required to properly apply the change.
Continent: lets you change what continent the unit belongs to.
Enabled: Lets you enable and disable the unit. It will hide the unit and disable all collisions it may have. This does not save between restarts and units are always enabled when loading into a level, but can always be toggled with EnableUnit and DisableUnit Elements for the duration of the heist. For randomizations for example, just disable all unneeded units with a DisableUnit element when starting the heist.
Hide On Projection Light: Generating light projections will completely ignore any unit that has this option enabled.
Disable Shadows: Will disable any shadows the unit is casting.
Disable Collisions: Will disable all collisions of the unit. It cannot collide with any player or dynamic physics object anymore and won’t be affected by physics simulations. Additionally you will not be able to select it by clicking on it and must be selected via the Select Menu.
Disable On AI Graph: Generating your nav-mesh will ignore any units that have this option enabled. This can be useful when your Unit’s collision is too big and blocks too much of the navigation from generating.
Delay Loading: Units with this option enabled will not actually spawn in the level when playing and must be loaded in with a LoadDelayed Element. This is not very reliable and should be used with caution.
Units that have a Sequence Manager will have an additional Mesh Variation option, in which you can choose a sequence the Unit runs by default.
Some Units have special properties and will have additional settings when selecting them. For example with omni_light units, you can tweak the light settings, or dev_ladder which lets you change height and width of the climbable surface.
Another good example would be the zipline, on which you can customize the end position, speed, as well as slack of the zipline wire, or if it can carry loot or players.
Editor Units are only visible in editor and with the Draw Editor Units setting enabled. There are different types of editor units, most commonly Navigation Splitter and blockers, omni lights and collisions.
Don’t confuse editor units with the Editor_Only continent. Despite being called editor Units, most of them have to be loaded in the level to work, with the exception of Navigation Splitters, blockers and cover points, which are only used to generate the nav-mesh and should be moved into an editor only continent.
Some examples of Editor Units: Left to right:
- Vehicle Only Collision
- Player Collision
- Bag Collision
- Nav Blocker
- Nav Splitter
- Door Blocker
- Attention Object
- Cover Point
- Dev Ladder
- Omni Light
- Vis Blocker
- Target Hitbox
Elements - Scripting Your Level
To make your level actually work, you place what’s called “Elements”. They are what most of the level logic consists of. You can compare it to programming, but very much simplified, or visual scripting in other game engines, just directly inside the level itself.
To script your level, you connect Elements together. Triggering the script with a Trigger element will then execute their task and execute the next Element in the chain. [Example: AreaTrigger triggers when cops enter its area, executes a chain of elements adding 1 to the counter]
There are a lot of different Elements, each with their own functionality and tasks. Most of the names already give you a good summary of what they can do, but you can always click the little question mark icon on the top to open the Wiki page with more detailed information.
You can move and rotate them how you like to keep them organized.
Selecting an element gives you the following options:
Editor Name Lets you give the element a custom nickname, so you can find it more easily when searching for it.
Editor Color Lets you give the element icon a custom color. This can help in organizing your script or visually highlight certain elements. Default colors for elements can also be defined in the BeardLib Editor Menu Options.
Script Lets you change what script the element belongs to.
Trigger Times Determines how many times the element can be executed. 0 means it can be executed an infinite amount of times. 1 means it will execute once and then disable itself.
Base Delay Adds a specified amount of time in seconds to the execute list and Random Delay adds additional time, randomized between 0 and the amount you specified.
Enabled Lets you enable and disable the element. Disabled elements cannot be executed and will not execute other elements. This state is saved, as it is important for scripting your level.
Execute On Startup Will execute the element as soon as the host has finished loading the level and entered the Loadout screen.
Debug Will give the element the debug flag, for the debug options in the Tools menu.
Manage On Executed Opens a list with all elements that get executed from this element. You can manually search for elements to add here, or add elements by holding CTRL and left clicking elements to execute.
Each type of Element then has their own additional setting, depending on what it’s supposed to do.
Equipment for example will add a specified special equipment to the player’s inventory, PlaySound which plays a specified sound, or Toggle which can enable and disable other elements.
These are just examples, there are way too many elements so listing them here would blow this part out of proportion.
-> Mission Elements Wiki Page
Some Elements require you to link to other elements or units to perform their task on them, like the Toggle, AIGraph or Operator elements. Instead of adding the targeted element or unit to the On Executed list, you have to put it in their own list in the element specific settings by opening it, or holding SPACEBAR while clicking other elements.
To start your script when you play the level, at least one element needs to have “Execute On Startup” enabled to trigger the script. This is usually a MissionScript Element. This however should only be used to enable your player spawns, prepare some level layout and set the Whisper State if needed. Since startup triggers as soon as the host enters the loadout screen. This could cause issues with timers, delays and likely desyncs with clients. Your actual level logic should be triggered with an AreaTrigger so it only starts when all players are actually spawned in your level.
For organization purposes, your elements should be way above the play area of your level on black planes (
units/test/jocke/plane_black_temp). Editable_text units can be used to further label your elements. The planes and the text should also be editor only. This is completely optional, but it massively helps keeping your script organized and readable.
Continents And Scripts
Continents can be compared to layers or groups of units. Every Unit has to be part of a continent, but can be assigned to a different continent at any point. Be aware that the Unit's ID may change when doing this, which could cause issues with Elements it may be linked to. Just double check that your Elements are still linked to the correct unit.
By default every level has a continent called “world” and “editor_only” and more can be created to group up and organize Units however you like. You could for example make a new continent dedicated to only collisions.
Be aware, having more than 9 continents can cause issues with unit IDs and element links.
Continents with the “Editor Only” setting on will only show the Units in it when in the editor. Loading the level through Crime.net will not load them.
Create a new continent by pressing the “plus” icon on the header.
Toggle Visibility will hide and show every unit in the continent.
Add Mission Script will create a new script for elements.
Select All will select every unit from the continent.
In the Continent Settings you can rename it and toggle if it should only be loaded in the editor.
Delete All units will clear the continent of all units.
Remove Continent will delete the continent and all units in it, as well as every script and elements connected to it.
Scripts are similar to continents, but for Elements instead. Elements have to be part of a script and can be assigned to a different script at any point. Be aware that element IDs may change when doing this, which could cause issues with Elements or Units it may be linked to. Just double check that your Elements are still linked to the correct unit or Element.
They can only interact with other Elements that are in the same script, not with Elements from other scripts. The only exception is the ExecuteInOtherMission Element, which can execute every element no matter what script it belongs to.
By default, every map has a "Default" script, which belongs to the "World" continent, and you can create as many as you want, under any continent you like.
Scripts are part of continents, so you create new scripts by pressing the “plus” button on the continent you want to add the script to.
Select All will select all elements from the script.
Rename Script lets you give it a new name.
Delete All Elements will clear the script of all elements.
- Remove Script deletes the script and all elements from it.
Current Continent and Current Script refer to the continent and script you’re currently editing. Spawning new units and elements will automatically place them in there.
Sequence And Sequence Triggers
What are sequences
Many Units have what’s called a Sequence Manager. Sequences are pre-defined instructions on how a Unit can change appearance or behavior. They can simply hide and show parts of the model, change textures or enable their interactions, to playing animations, spawning effects and much more.
If you ever shot or hit a window and it broke, that is a sequence being run, that disables the glass plane of the model and spawns an effect. Lockpicking a door is also a sequence, detecting the interaction and playing an animation. Even a Keycard or Crowbar being picked up is a sequence being run.
Sequence Managers in most cases are custom made for the specific Unit.
You can see if a Unit has a Sequence Manager available by selecting it and looking for a “Mesh Variation” option. In there you can select one of the sequences which the unit should run on startup.
A UnitSequence Element can be linked to such a unit by opening the Trigger List either with the button or the M hotkey, or by holding SPACEBAR and clicking on the unit.
With the unit connected you can choose a sequence in the Trigger List.
Executing the Element will then run the selected sequences.
A UnitSequenceTrigger Element can link to those units similarly to a UnitSequence, however instead of running sequences on the unit, the selected sequence being run will trigger the Element which can be used to execute a chain of Elements. You could for example use it to play a voiceline when opening a door by detecting the sequence of the door opening and executing a Dialogue Element.
Asset Management - Database, Packages, and Local Files
BeardLib can load Assets for your level in different ways. Currently the standard is to load assets from database, also known as DB Loading. BeardLib handles this process automatically when spawning a unit and there is next to no other step required.
However you can also manually load assets with the Load From Database option.
The old method was Package loading. When spawning a Unit, you had to load a package containing said Unit. The downside is that a package also contains lots of other units, taking up memory. In some cases like sound effects or voice lines you may still need to load some, just remember to pick the smallest available packages.
You can load packages with the Load With Packages option.
Local Files / Extract
The third method is Local Files, or extract loading. This means the Unit’s files are actually present inside your Map’s assets folder.
It was used in combination with Package loading to reduce the memory usage of a heist. The downside is that since the files had to be extracted, the space the Map folder takes on your harddrive went up the more Units you load this way, resulting in longer download times. These days Local files are only really used for custom assets.
While extract loading has been removed from the editor entirely, and there isn't really a reason to have do it anymore, you can still include the files into your project with the following method:
Use the Load From Database option, but with the "With Options" toggle on.
After picking your asset in the list you now get the option to include the files in your project.
Some Units are dependent on other assets, like Effects, and those sometimes don’t get loaded properly. In this case you need to manually load them.
You can see the dependencies of a unit by extracting its .unit file using Diesel Bundle Viewer, opening the file in a text editor and checking for a
Those assets need to be loaded for the unit to work, otherwise the game might crash.
You can manage your loaded assets and packages from the Assets Manager in the Main-Tab. There you can see a list of every package and a list of every Asset currently loaded in your level.
You have several options on the right side of the screen:
Remove And Unload Unused Assets Will unload all assets that are loaded but not used anywhere. For example a unit that isn't actually spawned in the level.
This sometimes also unloads important assets such as dependencies for units, to prevent this from happening you can tag assets as Used.
They will show up in the list with a green background and will not be unloaded with the Unload Unused Assets button.
Package Report Will let you select any package from the game. When selecting it, all units from the package will be spawned into your level.
Scan Assets Directory Will scan through your project's assets folder and add all files to the add.xml.
Clean Add Xml will clean up your level's add.xml by removing duplicate entries.
Assets that are loaded but not used are marked in Yellow. While building your level those can stack up really fast, since just clicking on a unit in the spawn list will already load it. Before releasing your map you should make sure to unload all units that are not used and not needed to reduce memory usage.
Assets marked in Red are assets that are spawned in your level despite not being loaded.
Usually BeardLib automatically loads missing assets when opening your level and notifies you about them.
You can easily fix these with by either loading a package that's containing them, loading them directly from database ot just remove them from your level.
The add.xml tells BeardLib what assets are needed when loading into your level. It’s unique for every level and can be found in
*Your Project*/levels/*your level*/add.xml.
Assets loaded in-editor will be added here automatically, but you can always edit it manually using a text editor.
PAYDAY 2 has a theoretical limit of about 3.5GB (3500MB), but usually you’re gonna crash at around 3200-3300MB. To keep your used memory as low as possible, you should load as few packages as possible and unload unused assets. Additionally assets that are only used inside your level, such as voicelines, interactions or hooks, should only be loaded while in your level. You can see how much memory your level is using with the -qa launch property.
You enter playtest mode by pressing F10 on your keyboard. The loadout screen opens and elements set to Execute on Startup will be executed. You can buy assets, enter PrePlanning if set up, change weapons and music just as if you opened the level through Crime.net. Ready up to get spawned in the level.
You can run around, shoot and interact as usual and return to editor mode at any time by pressing F10 again, while the game continues to run in the background.
While building your level layout, it’s fine to save while a playtest is running. However it’s highly advised not to do so in later stages with navigation and logic set up, as it has a high chance of breaking.
Sometimes elements don't properly link to each other unless you reload the level. If you want to test a script you should save and reload the level before testing to make sure the elements are actually linked.
An Instance can be seen as a level inside your level. They are very useful if you need to build or script the same thing multiple times. A good example would be a door that can be opened by AI or a power box that can appear in random locations.
Since an Instance is basically it's own level, editing it will also affect each spawned-in instance of it, they are 100% identical.
In gameplay, you won’t notice any difference between Instance and regular Units in your level.
You can either use vanilla instances, or make your own custom ones, in both cases you can find them in the “Instance” tab in the Spawn Menu.
Create A Custom Instance
To create your own Instance, simply open your Map in the Project Manager, add a new module, select “Instance” and give it a unique name.
Alternatively you can also clone a vanilla instance and edit it.
You can now open your new Instance like any regular level and edit it, or open it from inside your level with the Edit Instance button.
While scripting your Instance, you can set up InstanceInput and InstanceOutput elements to send signals between the instance and your level.
After spawning the Instance in your level, you can send signals to it using the InstanceInputEvent Element in your level, and receive signals from the Instance with InstanceOutputEvent Element.
Keep the amount of elements below the Instance Index size, which is 250 by default. It can be increased if necessary, though it’s better to keep your instance size as small as possible.
The Index size is basically the amount of element IDs in your level's script that are reserved for the Instance.
While editing your Instance, you can build navigation and place PlayerSpawner Elements to playtest it. However, the generated navigation will not carry over to the main level, and all PlayerSpawner should be disabled when finished editing.
Additionally Instances can only have the default world continent and default script.
Instance Point Element
Instead of spawning an Instance multiple times, you can move one using the InstancePoint Element. This is especially handy for randomizations, as you won't have to deal with linking multiple Instances, you simply spawn it once and move it where it's needed.
InstancePoint Elements can only link to Instances that have the "Mission Placed" option toggled on.
Now you simply have to execute the element and the Instance will appear at the exact position and rotation of the element.
Mass Units (Brushes)
Mass Units, or brushes, allow you to add more detail to your level with relatively little impact on performance. They are set-up to automatically fade in and out at certain distances. There are lots of different Brushes you can use, from trash and debris, to leaves and grass, graffiti, rocks and so on.
Access the Brush editor by navigating to the World menu and to the "Brush" tab.
In the top part of the menu you can change how your brushes are placed in the world:
Random Roll: Rotates the unit by a random amount when placing, between 0 and the specified value.
Radius: Determines the size of the brush. Can also be changed by scrolling your mouse wheel.
Height: Controls the height of the brush.
Angle: Controls the rotation of your brush relative to the camera.
Offset: Determines the offset distance of the unit, relative to the surface you’re pointing at.
Density: How many units per square meter should be spawned.
Pressure: Determines how many units get spawned per frame.
Pressure Erase: When enabled, uses the Pressure value for erasing units.
Erase with Selected Unit: Enable to only erase the currently selected unit.
Override Surface Normal Rotation: When enabled, spawned units will ignore what direction the surface is facing, and spawns the unit in their default rotation.
Brush on Editor Bodies: When enabled, will place brushes on editor units, otherwise the cursor will just phase through them.
Visible: Toggles the brush cursor.
Now simply move your cursor around in your level and place the brushes by clicking LMB and remove them by pressing RMB.
Mass Units can not be enabled or disabled mid-heist, so it’s better to place them in areas that won’t change during gameplay.
Optimization - Improving Performance
There are lots of ways to Improve performance on your level. For a start you can try to not over-detail your level. Adding lots of detail to make your level look interesting is not a bad thing, but overdoing it, especially in areas it’s not necessary, can backfire on you with low FPS.
Additionally you should use low-quality assets for areas that are out of bounds. Those usually have
background in the name.
But most important are Occluders and Portals:
Occluders are invisible planes that, when looking at them, prevent Units behind it from being rendered. They are usually placed inside walls.
You find and place those like normal Units in the Spawn Menu and you can see them using the “Draw Editor Units” setting.
Portals are shapes in your level with Units assigned to them. Those Units will only be visible if the player is standing inside the shape, otherwise they will not be rendered.
You create Portals by navigating to the World Menu and the Portal-Tab. Create a new Portal by clicking on the "Plus" icon.
Select your portal and add shapes, those indicate the area the player has to stand inside to see the Units linked to this portal.
Now you can add individual Units to the portal by selecting them and clicking the “Add to current portal” button in the quick actions.
You can also use the button to automatically add all Units that are inside the shapes.
Focus on gameplay mechanics and logic
Player Spawns And Team-AI Idling
For players and Team-AI to spawn, you need to set up PlayerSpawner Elements. By default a new project already has a PlayerSpawner Element, however you should create at least 3 more so players and AI don't clip into each other when spawning.
To set up Player spawns, spawn at least 4 Player Spawner Elements at the positions you want the heist to start. To keep things organized, you can place a MissionScript Element and let that one execute those 4 player spawns. Player Spawner need to be executed on startup, or by the startup-element.
You can place as many spawns as you want. The game will automatically spawn players and Team-AI randomly at any executed PlayerSpawner element.
A common setup is to have multiple groups of PlayerSpawner elements, with separate MissionScripts executing them. Instead of the startup element executing all PlayerSpawner at once, it executes a Random Element, which randomly picks one of the spawner groups.
To add idle animations for AI-Teammates, place an AreaTrigger over the same location as a player spawner and set it the instigator to
ai_teammates. The area trigger then executes a SpecialObjective with the animation you want. Make sure to disable the area triggers after spawning, otherwise they may accidentally trigger again mid-heist if an AI-Teammate walks through them.
Whisper State - Stealth and Loud
Whisper State determines whether or not your level is in Stealth or Loud mode. It can be toggled using the WhisperState Element.
If Whisper state is enabled, your level is in stealth mode. The AI will be idle or do the via SpecialObjective assigned animations and not engage unless they get alerted by something or someone, in which case they sound the alarm and attack the player.
Setting the Whisper state to disabled, the level will switch to loud. Civilians and manually spawned enemies will try to reach a FleePoint Element to despawn, unless told otherwise. Additionally, the game will now loop through different assault phases.
To have working security cameras in your level, you first need to place the right camera props. The correct Unit you need is called
gen_equipment_security_camera. Next you spawn a SecurityCamera Element and connect it to the camera prop with the Camera unit button or by holding SPACE and clicking the unit. Below you can change what direction the camera prop is facing. AI Enabled will activate the camera and it will be able to spot players as well as loot bags or bodies. The position and rotation of the Element is not important. Execute the Element when you want the camera to be active.
To disable a camera, place another SecurityCamera Element, but with AI Enabled set to off. Executing it will disable the camera and it will no longer be able to spot anything. Breaking the camera prop will also automatically disable it.
To be able to see through a camera, you spawn an AccessCamera Element and again link it to the camera prop. The position for this element is not important, but the rotation is. The cone must face in roughly the same direction as the camera prop, otherwise you will look in the wrong direction when accessing the camera feed.
In the Element you can give your camera a custom name that shows up in the bottom left when accessing the camera feed, as well as limit how much you can turn the camera. You don’t need to execute the Element for it to work, but you do need specific Units to access the feed, like
Breaking the camera prop will automatically disable the camera for the feed and you will see white noise when accessing it, and you can also manually disable cameras using an AccessCameraOperator Element set to
Environmental Damage - KillZone Element
Environmental damage like fire or teargas that damage players, or even enemies in some cases, are easily set up using Area Trigger and Killzone elements.
Defining The Area
To define the area in which the damage should apply, place a Shape element and adjust the width, depth and height if needed. Multiple Shape elements can be used for more complex areas.
Set Up The Elements
Place a AreaTrigger element and link it to the Shape element. Either use the Manage Use Shape Element ID List button, or hold spacebar while clicking on the Shape element.
Using Shape elements for this is not actually required, however if more than one type of instigator (players, enemies, civilians, etc.) should be affected, multiple AreaTrigger elements are required since they can only use 1 type per trigger.
The area would need to be set up individually for each trigger element. Using Shape elements instead, the whole process only needs to be done once and any AreaTrigger element can just link to and use the Shapes.
Place a KillZone element, choose a damage type and have it get executed by the AreaTrigger.
Keep in mind that not every damage type is available to every instigator, more information on that can be found here.
Depending on who should get damaged, the AreaTrigger needs to be set up differently.
Player / Team AI
For players and team AI, set Trigger On to "both", Instigator to "player" or "ai_teammates" as well as Trigger Times to "0".
This will execute the KillZone every time someone enters the AreaTrigger, activating the damage effect. When leaving the AreaTrigger, the KillZone gets executed once again, deactivating the effect.
The Trigger Times set to "0" ensures that it can execute infinitely without disabling itself.
Enemies / Civilians
For enemies and civilians, it also depends on what damage type is set in the KillZone.
If the instigator should get affected instantly when entering, set the instigator to either "enemies" or "civilians". For Trigger On set it to "on_enter" and Trigger Times to "0".
If instead a random instigator should get picked with a delay in between, set Trigger On to "while_inside" and Trigger Times to "1".
Place a Toggle element and have it get executed by the KillZone element with a short delay, for example "2.0" seconds. Link the Toggle to the AreaTrigger and set the Set Trigger Times to "1".
Here are some extra steps to enhance your KillZone experience even further.
Effects And Sounds
The KillZone and AreaTrigger elements don't have any visualization that they deal damage when entering. Signal the player that the area is dangerous using PlayEffect elements playing, for example, teargas, fire or electric spark effects.
Additionally PlaySound elements can be used to add to the immersion. A list with sound IDs can be found here.
Simply execute the PlayEffect and PlaySound elements when the AreaTrigger gets enabled and tweak the timing if needed.
The AreaTrigger can be toggled on and off at any point during the heist to enable and disable getting damaged by it.
For example when cops fill a room on your level with teargas mid heist, or something gets lit on fire and later extinguished.
The AI moves through the level on what’s called a Nav-Mesh. NPCs (Cops, AI Teammates, Civs) move according to it. The Nav-Mesh is split into “rooms”, the AI then navigates through the level by moving from room to room, attempting to complete their current set goal. They may be following a predetermined patrol path, walking up to the player to arrest them or moving to a set position to do some action.
The rooms that make up the mesh must be defined manually. Each room must have what's called a Navigation Segment placed inside. They are used to generate the Nav-Mesh.
To place Navigation Segments, go to the World Menu and into the AI-tab. There you will find the "Spawn Navigation Segment" button.
Navigation Segments will only be visible when inside this menu.
Next, we need to further define the Nav-Mesh using Blockers and Splitters. Both of these unit types are editor-only, meaning you have to enable the “Draw Editor Units” option to see them.
Splitters separate the rooms for navmesh generation. Each and every navigation segment has to be completely isolated from all other nav segments, and splitters are what do the job. When generating, solid objects block navigation so there is no need for placing them inside walls. These are used prominently in doorways or big open areas that you want to divide into smaller sections.
A single Splitter should never connect more than 2 Navigation Segments, otherwise the mesh will bleed when generating and not connect properly between segments.
Blockers prevent the Nav-Mesh from generating wherever you place them. Sometimes, a unit may have a slope that the generation perceives as space that should be traversable for NPCs. You also have to make sure navigation doesn’t seep out of the intended area and continue to generate near-infinitely on the background geometry.
You can find both Splitters and Blockers by looking for them in the Spawn Menu. Some names may be inconsistent, but they are colored in a specific way. Splitters are green and blockers are always red.
Cover Points, as the name suggests, are manually defined points in your level where the AI should take cover. Around props like barrels, pallets or cars, next to doorways or corners of buildings, basically everywhere where you think it makes sense. Coverpoints also play a big role in the movement of the NPCs, as they navigate from coverpoint to Coverpoint. If no Coverpoint is present, they will just move from segment to segment.
After generating your Nav-Mesh, you can view the results using the debug options in the AI-Tab. The most important are:
Quads show the Nav-Mesh as blue rectangles. Those are the areas your AI can technically move on. It May sometimes appear warped weirdly, especially at sloped areas and stairs, but it should still work fine when playing.
Coarse Graph shows you which segments are connected. If segments are connected with a thick yellow line, AI can freely move between them. Ideally, segments should only be connected with their neighbouring segments.
Covers show the location of cover points and what way they’re facing, the green line indicating the front. If the cone above them is green, they can be used by AI. If the cone is red, AI will not use them as they most likely are not on the Nav-Mesh, or the part they are placed on is disabled.
If you find issues with your mesh, for example it didn’t generate in specific areas you need it in, generated too much, or isn’t connecting certain parts properly, simply tweak the position of your blockers and splitters, and generate again until you’re happy with it.
Note: Navigation needs roughly 1.5m of free space above the segment to generate.
You can even generate individual segments by selecting them and clicking the Calculate Selected button in the AI-Tab, however before releasing the map you should re-generate your entire navigation with Calculate All to make sure there aren’t any potential issues with it.
Manipulating Navigation Mid-Game
Using the AIGraph Element, you can enable or disable entire Navigation Segments. Link the Element to the Nav segment either by opening the Graph Unit list with the button or the M hotkey, or holding SPACEBAR and clicking on the segment.
With the Operation setting you can either allow or forbid access to the linked segments, and even forbid access only for certain AI types.
Door Blockers & NavObstacle Element
Another way to prevent the AI from reaching certain areas is with the use of Door Blockers. Instead of blocking the entire segment, door blockers block only the parts of the mesh they collide with.
They are most commonly used to block doors, hence the name, but they can be used in many other ways, for example vehicles that roll-in at a later point in the heist like SWAT trucks.
You can find door blockers by looking for them in the Spawn Menu, they are usually colored Pink. Door blockers have to be enabled and disabled using the NavObstacle Element. Link the Element to the Door Blocker either by opening the Obstacle list with the button or the M hotkey, or holding SPACEBAR and clicking on the Unit. In the Operation select “Add” to block the navigation and an additional NavObstacle Element with the “Remove” Operation to make the navigation accessible again.
Guard / Civilian Patrols
You can make NPCs walk around the level in stealth mode using SpecialObjective and SpecialObjectiveGroup Elements. Per NPC, you place several SO Elements. They act as check points the AI moves between.
A basic setup for your SOs is the following:
Set AI Group to whatever type of AI uses the patrol.
destination and Path Haste
Also make sure to add the AI type to the Access Flags.
Further down you can also set Action Duration Min and Action Duration Max to tweak how long the AI remains at this SO.
To easily randomize between the SO checkpoints, spawn a SpecialObjectiveGroup Element and add all SOs of your patrol to the followup Elements list. Set the mode to
Use Instigator and set the base chance to 1. Make sure each SO of the patrol has the SO Group Element in the Followup List as well.
Now all you have to do is place an EnemyDummyTrigger Element, link it to your enemy or civilian, set it to
spawn and make it execute the Special Objective Group.
Assault waves are largely handled by the game automatically. You only have to set up a few things.
First of all you should set up some spawns for the Cops:
Place some SpawnEnemyDummy elements around your map, preferably in areas the player can’t see. You can even set animations in the Spawn Actions for things like climbing up a ledge or repelling down from somewhere in case the spawn is in a visible area. The other settings don’t matter in this case.
To make your spawns more organized, should group up spawns with a SpawnEnemyGroup element. In there you can even toggle specific types of enemies for the spawn group and increase the interval if needed. For regular assault spawns you can enable everything except for
To activate spawn groups, you need a EnemyPreferedAdd Element. Select the spawn groups in there and execute it when you need them enabled. You can add more spawn groups like this at any point in the heist, for example if the player opens a new area. Additionally you can use EnemyPreferedRemove to disable spawns.
Next you need to set-up Difficulty Elements. Those determine the intensity of your assault phases. It has to be above 0 for enemies to spawn. You can increase or decrease the difficulty intensity any time.
Lastly, make sure the Whisper State is set to disabled, otherwise the game will not start any assault waves and remain in stealth mode. Simply execute a WhisperState Element with the Whisper State setting off.
You can use a GlobalEventTrigger Element with
police_called to execute the whisper state and set the difficulty to start the police assaults when a NPC calls the cops, but you can also choose different triggers or even execute the elements manually at any time.
Harassers and Snipers (+ Hiding Cloakers) [wip]
So called “Harassers” are enemies that are spawned separately from the assault wave, that are used to make specific parts of your level harder, or simply to annoy the players and keep them on their toes. Snipers and hiding cloakers are included here because they basically fulfill the same purpose.
Harassers are mostly placed in areas that are either out of bounds for the player, or hard to reach. For example on rooftops, containers, scaffolding and so on, but still close enough to easily kill them. Ultimately it’s up to you where you place them.
They can be any type of enemy ranging from normal SWAT units to Bulldozers or even Gangster and the amount of harassers is also up to preference.
Snipers are set up very similar to Harassers, running on a loop that respawns them after a while. Usually with a counter keeping track of the amount of snipers present on the map, so as to not spawn too many at once. Most of the time they are placed further away from the player, making them harder to hit. Even higher rooftops or helicopters that fly in. They use sniper units instead of regular cops.
Hiding cloakers require a little more set-up. With the use of Special Objective, you can set up hiding places around your level. There are various animations you can use for cloakers to hide around corners, below cars, behind doors and so on. You can also set at what distance the Cloaker jumps out of his hiding spot and attacks the player. Usually Cloakers spawn and hide at the end of or between assault waves.
Basic Setup (wip)
They usually run on some kind of loop that respawns them after a while. Very important is the use of SpecialObjectives with the force the spawned cops into position, otherwise they might just wander off and despawn, or don’t move away from their spawn dummy at all.
You can include Captain Winters in your level in just a few steps:
First you need to set up the spawn point. Place a SpawnEnemyDummy Element somewhere out of view from the player. Except for lowering the interval, you don’t have to change any setting on the spawner.
Next you place a SpawnEnemyGroup Element and link the previously set up spawn element to it. Disable every enemy type except for
Phalanx. Leave the other settings default.
Now you spawn an EnemyPreferedAdd Element and add the SpawnEnemyGroup element you just set up into its Spawn Group List.
To have Winters and his shields take position, place a SpecialObjective Element where you want him to move to. You can leave most of the settings in the SO default, however it is important to set the So Action to
AI_Phalanx and remove every NPC type from the Access Flag list.
Now you simply have to execute the SpecialObjective and the EnemyPreferedAdd elements whenever you want Winters to spawn. It takes about 5 to 10 minutes for the game to actually spawn him but from here on everything is handled automatically by the game.
Note, vehicles can instantly kill Winters and his shields, keep that in mind when placing your Phalanx SO. It’s best to place him in a dedicated area that can’t be reached by vehicles, as seen in the Goat Simulator heist.
Documentation for the editors found in the general tab of the Tools menu.
Material Config Editor
The Material Config Editor lets you easily create and edit material configs from within the game and even display changes in real time.
It's primary use is to speed up and simplify the creation of custom units for levels, however in theory it can also be used to edit stuff like characters or weapons.
Access The Editor
You can find it by navigating to the "Tools" menu and the "General" tab, it will be listed at the very top in the Editors section.
Alternatively you can select any unit and press the new "Edit Material Config" button in the Quick Actions section. This works with any unit and will automatically open up the correct material_config file of the unit.
New Material Config
Lets you create an entirely new material config.
Open From File
Opens up the file browser and lets you search for any .material_config file on your computer.
Open From Database
Lets you open any base-game material config by loading it from database.
Open From Selection
Opens up the material config form the currently selected unit.
Saves the currently opened material config. Only works with custom material_config files, saving a base-game config will instead save it as a completely new file and the original material config will not be affected.
Opens up the file browser and lets you save your material config as a new file, or override an already existing one.
Closes your currently opened material config. Any unsaved changes will be lost.
Exits the editor and closes all currently opened material configs. Any unsaved changes will be lost.
Lets you undo and redo actions. Pretty self explanatory.
Reload Material Config
Manually updates the unit in your level with the changes you made in the config. Usually not needed when using Real Time Feedback.
Real Time Feedback
Automatically updates the unit in your level when making changes in your config.
Show XML Output
Shows the raw XML of your config file.
The solution to all your problems.
Shows the name of the material config you're currently editing.
Use the 2 arrow buttons on the right to switch between other opened config files.
Managing your materials
Once a material config file has been opened, it will show you a list with every available material from the config.
You can add a new material to the list by typing it into the text box at the buttom and clicking "Add".