Beardlib Editor Tutorials (2024)

Guides and information on creating custom heists using BeardLib Editor.

• Getting Started
• Installing BLE
• BLE Overview
• Creating A New Project
• Basics
• Controls
• Units - Building Your Level
• Elements - Scripting Your Level
• Continents And Scripts
• Sequence And Sequence Triggers
• Asset Management - Database, Packages, and Local Files
• Playtesting
• Level
• Instances
• Mass Units (Brushes)
• Optimization - Improving Performance
• Logic
• Player Spawns And Team-AI Idling
• Whisper State - Stealth and Loud
• Security Cameras
• Environmental Damage - KillZone Element
• AI
• Building Navigation
• Manipulating Navigation Mid-Game
• Guard / Civilian Patrols
• Assault Waves
• Harassers and Snipers (+ Hiding Cloakers) [wip]
• Captain Winters
• Editors
• Material Config Editor
• Custom Content
• Creating Custom Contractors
• Custom Subtitled Dialogue and Sound
• (Old pages, still useful for reference)
• Ai Escorts (and Special Objectives)
• Applying Custom Instances
• Cubemaps, Cubelights and Lighting your level
• Limitations and Issues with mapping in Diesel
• Making and adding Environments
• Navigation in diesel
• Optimisation: Occlusion and Portals

The place to begin your mapping journey.

Getting Started

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/mods as 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.

External Software

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:

QA Panel

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.

Getting Started

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.

Projects

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.

Levels

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 .../PAYDAY 2/mods/logs.

To open and edit a level, simply click on it in the list and confirm.

ScriptData

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.

Check File

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

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.

Buttons from left to right:

• 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
• Deselect
• General Options (BeardLib Editor Menu Options)

World

The World Menu lets you manage assets and tweak settings that are specific to your level. It is split into multiple tabs with different settings each.

Main

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
-> Objectives

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.

Environment

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

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.

Portal

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.

AI

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

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.

The bottom menu lets you choose which brush to place. Search for a specific keyword or scroll the list. Left click will select the brush and you can then place it in the level. Holding CTRL lets you select multiple brushes at once.

Selection

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.

Main

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

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

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.

Spawn Menu

The Spawn Menu is where you find Units, Elements and Instances as well as Prefabs to place in your level.
Each category has their own tabs.

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”.

Select Menu

The Select menu lists every Unit, Element or Instance currently in the level, as well as unit groups. Each category has their own tabs.

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.

The buttons in the Options header let you select the entire page you’re on,

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.

General

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.

Environment

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

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

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.

Options

The Options Menu lets you change settings that are more specific to the editor.
The Editor section contains general options like Grid size, camera speed or FOV. You can even change to Orthographic View from here.
Draw/Show lets you toggle certain things being rendered or highlighted. Highlight Units or Draw Bodies for example will show you the actual collision of units, instead of its boundary box.
Visualization modes can be changed from here as well.
Raycast/Selecting houses settings related to selecting and grabbing objects. Options like toggling Surface Move, Snappoints or the selection distance can be changed here.

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.

Getting Started

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 .../PAYDAY 2/Maps.

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.

-> Building Your Level
-> Scripting Your Level

The basics of building and scripting a level.

Basics

Moving

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.

Selecting

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.

Transform

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.

Misc

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.

Default Keybinds

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.

Unlisted Keybinds

These keybinds are not listed ingame and cannot be changed.

Basics

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.

Spawning

You start by navigating to the Spawn Menu and to the “Unit” tab. You can use the search bar to look for whatever units you need to build your level.

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.

Settings

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.

-> Sequence And Sequence Triggers

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

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
• Occluder
• Player Collision
• Bag Collision
• Nav Blocker
• Nav Splitter
• Door Blocker
• Attention Object
• Cover Point
• Dev Ladder
• Omni Light
• Vis Blocker
• Target Hitbox

Basics

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.

Spawning

You start by navigating to the Spawn Menu and to the “Element” tab. You can scroll down or use the search bar to look for the type of element you need and click on it to spawn it into your level.

You can move and rotate them how you like to keep them organized.

Settings

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. Be careful not to accidentally add an element to it's own "On Executed" list, as it will endlessly execute itself and likely cause a stack overflow crash. Use the "Element Loops" tool in the Debug tab of the Tools menu to check for element loops liek this.

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.

Startup

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.

Organization

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.

Mission elements on the Dragon Heist. Placed way above the level to be out of the way, organized and labeled to be readable.

Basics

Continents

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

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/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.

Basics

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.

UnitSequence Element

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.

UnitSequenceTrigger Element

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.

Basics

Loading Assets

Database

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.

Package

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.

Dependencies

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 <dependencies> tag.

Those assets need to be loaded for the unit to work, otherwise the game might crash.

Assets Manager

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.

Unused Assets

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.

Unloaded Assets

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.

add.xml

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.

Memory Usage

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.

Basics

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.

Level

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.

Spawning

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.

Level

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.

On the bottom part you can select which brush to use and even select multiple at once by holding CTRL when selecting.

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.

Level

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 backdrop, bdrop or background in the name.

But most important are Occluders and Portals:

Occluders

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

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.

Units that are linked to your current selected Portal have a red box around them.

Focus on gameplay mechanics and logic

Logic

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.

Logic

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.

Logic

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 gen_prop_security_console or gen_equipment_camera_hackingtool.
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 destroy.

Logic

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.

AreaTrigger Settings

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".

Extras

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.

Toggles

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.

AI

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.

Navigation Segments

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

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

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

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.

Generating

To generate the Nav-Mesh, we return to the AI-Tab in the world menu. The options are near self-explanatory, and to start the process just press Calculate All. You can view this process as it builds itself, but depending on the size of your map, it can take a while. When it’s done generating it will automatically reload the editor.

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.

AI

The Navigation can be manipulated in several ways while playing. You can set up Navigation Links to add more ways for the NPC to navigate through the level, block entire Navigation Segments or just parts of the mesh.

AIGraph Element

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.

Navigation Links

Navigation Links, or Navlinks for short, are Special Objective Elements with the “Navigation Link” setting enabled. They allow AI to move between 2 unconnected segments using animations. For example, make AI climb over fences, jump over gaps or through windows, or vault over objects.
To set up Navlinks, place down a regular Special Objective Element and enable the “Navigation Link” setting.
Choose an animation in the SO Action setting.
Increase the interval so the AI waits until the Navlink is free to use again without clipping into each other.
Make sure the type of NPC you want your Navlink to use is in the Access Flag list.
Lastly, the search position has to be roughly in the area the navlink connects to. There is a button to place at the end position of the currently selected animation, but it’s not 100% reliable and may require manual tweaking.

AI

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:
Enable Repeatable, and Use Instigator.
Set AI Group to whatever type of AI uses the patrol.
Path Style destination and Path Haste walk.
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 randomizer, enable 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.

AI

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 single_spooc and Phalanx.

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.

AI

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

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

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.

Cloakers

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.

AI

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.

Editors

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.

Navigation

File

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.

Save

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.

Save As

Opens up the file browser and lets you save your material config as a new file, or override an already existing one.

Close

Closes your currently opened material config. Any unsaved changes will be lost.

Exit

Exits the editor and closes all currently opened material configs. Any unsaved changes will be lost.

Edit

Lets you undo and redo actions. Pretty self explanatory.

Tools

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.

Help

Problem Solver

The solution to all your problems.

Material Configs

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.

Editing

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".

Use the arrow buttons to move the materials up or down in the list, this is purely for organization.
The "x" button deletes the material from the config.

To edit a material simply click on it in the list.
When selected you can rename it or copy/paste it to other materials.

Render Template

Change your render template by clicking the customize button on the right.

We as modders can not actually add any custom render templates so we have to rely on the already existing ones. Luckily there are a lot, pretty much for any situation there is a render template.

Start by choosing the shader you need in the dropdown.

From there you can either scroll the list of render templates, or search below for a specific shader define you need.
Click the dropdown below to open a list if every shader define.

At the top you can search for the exact define you need. (Keep in mind that the searchbar is case sensitive and requires you to type in all caps to work correctly.)

Now click on the define to select it and then "Add" to add it to your template.

It will now appear as a button below the Compilable Shader and can be clicked to be removed again.

As mentioned earlier, we have to use pre-defined render templates, the editor automatically filters and highlights the templates based on the defines you selected.

Repeat this process until you find the render template you need and click it to select it, it will automatically match the define buttons to the template.

When you're done, click "Apply" to apply the template to your material. You can then edit the parameters and values of the template.

From here on everything should be self explanatory, but if needed this will be extended.

Custom Content

Introduction

Hello! Ever wanted to make a custom contractor for your custom heist? Well, here's an easy-to-follow guide on how to make a (possibly good) custom contractor

DisclaimersThis is all mostly unavailable using the visual project editor.This also mainly applies to Windows, since I haven't used any other operating systems.

First of all, open your Steam folder!

Mac - ~/Library/Application Support/Steam/steamapps/common/PAYDAY 2

Linux - ~/.local/share/Steam/steamapps/common/PAYDAY 2

Windows 64bit - C:\Program Files (x86)\Steam\steamapps\common\PAYDAY 2

Windows 32bit - C:\Program Files)\Steam\steamapps\common\PAYDAY 2

This might be different depending on where you installed PAYDAY 2.Make sure you actually have BeardLib & BeardLib Editor

Making The Contractor Exist

Go into the 'Maps' folder, and into the heist you created previously. If you didn't create a heist, follow this tutorial. Part 1 of map editing: Creating your first heist

Then with a text editor such as 'Notepad++', 'Atom', or 'Sublime Text', right click the file labeled 'main.xml'.Add a string underneath the 'Localization' tag.

The string is this:

<contact assets_gui="guis/mission_briefing/preload_contact_bain" desc_id="contact_placeholder_desc" id="placeholder" name_id="contact_placeholder_name" package="packages/contact_bain"/>

I'll explain what each of these parameters mean.

assets_gui - I'm heavily certain this is the video used when displaying heists made by the contact, just use the one by Bain.

desc_id - This is the ID for the string in localization for the description of your contractor located in the Crime.net Codex.

id - This is the ID that your contractor uses, self-explanatory, make sure it's not equal to another contractor or you might mess stuff up.

name_id - This is the ID for the string in localization for your contractor's name, highly important if you don't want error text!

package - I honestly don't know what this is, it's probably important for 'assets_gui'.

Customize these properly, don't just leave them all as placeholder. With the exception of assets_gui and package.

Localizing Your Strings

After you're done making your contractor in 'main.xml' go to the 'loc' folder in your heist folder, and then open 'english.txt'.This can be opened with ANY editor, including Windows Notepad.

This is where information like your contractor name & description, heist name and briefing, and map name and briefing goes.Copy the following stuff into the file. Make sure you only have one set of the curly brackets.

{ "contact_placeholder_name" : "Placeholder" "contact_placeholder_desc" : "The placeholder description."}

You should absolutely edit all the information in here, if you set a different ID than contact_placeholder than change it to what you used in 'main.xml'. The right side text is what the text will look like in-game.

The Extra Polish

Without using hooks, you won't actually see the description of your contractor pop up.Using a specific hook you can make it appear in the Codex. This isn't necessary but it is a very nice touch.

Hooks:PostHook( GuiTweakData, "init", "maowcraftcontacttemplate", function(self) # Change maowcraftcontacttemplatelocal contact_data = {id = "placeholder", # Change placeholdername_id = "contact_placeholder_name", # Change contact_placeholder_name{desc_id = "contact_placeholder_desc", # Change contact_placeholder_descvideo = "dragon1", # Not necessary to be changedpost_event = nil}}table.insert(self.crime_net.codex[1], contact_data)end)

1. Copy this into a text editor, and save it as guitweakdata.lua.
2. Change all the parameters to the information you put in your contractor.
3. Create a new folder in your heist folder named 'Hooks'.
4. Go back to 'main.xml'.
5. Make a new tag at the top of 'main.xml'

<Hooks directory="Hooks"><hook file="guitweakdata.lua" source_file="lib/tweak_data/guitweakdata"/> </Hooks>

Make sure to test that everything works, if something goes wrong, check again, or send a message at the #help channel of the official ModWorkshop discord server. Link to modworkshop.net Discord Server - #help

Custom Content

If your heist or mod needs custom dialogue that includes subtitles follow the following steps.

1. Add your Sounds, for this example I will add sounds to a level for a custom map.

<sounds directory="assets"><sounds directory="sounds"><sound id="cus_rex_test_1" path="cus_rex_test_1.ogg" subtitle_id="cus_rex_test_1"/><sound id="cus_rex_test_2" path="cus_rex_test_2.ogg" subtitle_id="cus_rex_test_2"/></sounds></sounds>

2. Set up the Dialogue Script Data, this will add the dialogue to the dialogue element in editor.

   In the Main.xml file add this to your levels script data:

<script_data_mods directory="scriptdata"><mod replacement="new_dialogue.dialogue" replacement_type="custom_xml" target_ext="dialog" target_path="gamedata/dialogs/rex"><options merge_mode="add" mode="add"/></mod><mod replacement="index.dialog_index" replacement_type="custom_xml" target_ext="dialog_index" target_path="gamedata/dialogs/index"><options merge_mode="add" mode="add"/></mod></script_data_mods>

In your Scriptdata folder in the Project add 2 txt files: ('new_dialogue' can be renamed to anything you wish)

index.dialogue_index:

<table><include name="new_dialogue"/></table>

new_dialogue.dialogue:

<table><dialog id="cus_rex_test_1" priority="1" sound="cus_rex_test_1"/><dialog id="cus_rex_test_2" priority="1" sound="cus_rex_test_2"/></table>

3. From there your Dialogue should be added to the game!

Additional Notes!If you want your sound to play in 3D space (from a speaker or character) make sure its a mono-sound.If you instead want your sound to play as if in the players ears (like Bain dialogue) make sure its in stereo-sound.Make sure you localise your subtitles or players will see 'ERROR:text' ingame.

(Old pages, still useful for reference)

A test map is provided in the Attachments.

All Escort characters will stop moving when enemies block their path, different radiuses apply for different hostages.Escort unit data typically contains the following (using Matt as an example, This is not important unless you want to make a custom character act as an escort)

<!--Escort Animations--><anim_state_machine name="anims/units/escort_guy/escort_undercover_machine" /><!--Escort Extensions--><extensions><extension name="base" class="CivilianBase" ><var name="_tweak_table" value="escort_undercover" /><var name="_spawn_state" value="escort_undercover/spawn/loop" /></extension><!--Most important, makes the escort not die.--><extension name="character_damage" class="CivilianDamage"><var name="immortal" value="true" /><var name="_no_blood" value="true" /></extension></extensions>

Escorts in heists are fairly simple preset tracks for Escort civilians to follow.

First step is to choose your patrol path/s and add those positions to the level. Keep in mind you may need multiple patrol groups if you want your Ai to take different paths for different reasons.

Once you have a path for the Escort to take you need to add a SpecialObjective element for them to use that patrol group and use it like one.Not all of these settings are required, but most are not neccisary for what we are doing here.(Access Flags are not shown in the following image but use civ_male/civ_female to make it work for escorts.)

When spawning the Escort character you will want to include an EnemyDummyTrigger element to tell the escort to use the SpecialObjective we made.

Since were using a SpecialObjective element to make these escorts we can include triggers and branches to them.

• SpecialObjectiveTriggers set to Administered trigger type will execute once your escort has been told to follow the path, In the example level this is used to spawn an enemy that will block his path if you do not kill the enemy. A Complete trigger can be used for when your escort reaches the end of his pathing.
• SpecialObjectiveGroup With a follow up to take 2 different SpecialObjective escort paths can be used to start of connect branches together, in the example level its used to go left or right and it activated using the Followup Elements list in the 'escort_start' SpecialObjective (Use Instigator is required for this)

(Old pages, still useful for reference)

Note:Newer versions of Beardlib Editor includes dedicated custom instances, this workflow is largely unneccisary and outdated. Information on the page is still useful past the main.xml example.

Instance Example (In the Main.xml)

<instance id="level_id"><add file="levels/level_id/add.xml"/><include directory="levels/level_id"><file file="world.world" type="generic_xml"/><file file="world/world.continent" type="custom_xml"/><file file="world/world.mission" type="generic_xml"/><file file="editor_only/editor_only.continent" type="custom_xml"/><file file="editor_only/editor_only.mission" type="generic_xml"/></include><packages/></instance>

With this setup you can work on the instance as a level without needing to move any files around

CONTINENT

Example:table continent="world" folder="levels/instances/unique/hoxestatesecurityroom/world" indexsize="1000" name="hoxestatesecurityroom001" position="0 0 0" rotation="0 0 0 0" script="default" startindex="11000"

continent="world"

• The name of the continent file its in.

folder="levels/instances/unique/hox_estate_security_room/world"

• The path to the "world" folder containing the continent and mission_script files.

index_size="1000"

• How many units and/or elements it takes up in memory. beardlib sets all instances to 1000 by default even if it only uses 3, you can check official maps files for exact index counts but there doesnt seem to be any issues with it being set to 1000.

name="hox_estate_security_room_001"

• In level name and id, cannot be the same as any other instance or things get mixed up.

Position/Rotation

• The usual positional information.

script="default"

• Hard to explain but I think its like a sub-folder for element code, doesn't need to be anything but default for custom heists.

start_index="11000"

• If you have 3 instances each taking 1000 spaces for the index_size this decides where the elements are stored. starts at 0 each instances adds its index_size from the last instance

MISSION

Example:entry index="12" type="string" value="hoxestatesecurityroom001"

entry index="12"

• The order of instances, if this is the 5th instance on the map its 5.

type="string"

• Magic code stuff, don't touch it.

value="hox_estate_security_room_001"

• This is the name id mentioned previously in the continent.

.

(Old pages, still useful for reference)

A cubemap is a six-sided texture used for reflective surfaces to reflect stuff.Here's an example:

This looks wrong! Why are there buildings in the reflection even though we are indoors?

That's because diesel does not support realtime reflections, so map makers have to create cubemaps manually

To do so you will need to spawn a cubemap_gizmo from the editors spawn menu. Position it however you want.Then head over to the env manager and press "Build Cubemaps" (this will fail if you dont have python3 and PIL module installed)If successful, the editor will tell you the path to the cubemap relative to your map's directory. Remember this path!

Reload the map, click on the env tab in the upper menu and find your cubemap texture in the cubemap dialog box.Once selected, the global cubemap will change:

Eh, not too good looking, but it will do!

The game will keep track of changes to the cubemap texture so you won't have to reload the map each time you build cubemaps for the gizmo you're working with. Keep in mind that you will have to reload the map every time a new gizmo is added to the map!

This cubemap is global, how can i make certain areas have different cubemaps?

For that you'd need to create a separate env area, tick the cubemap option and include an environment file with a different cubemap texture. You'd need to do this for every area

Why are reflections unchanged for some units?

That's because these units override the global cubemap. To fix that you need to extract the unit, change the global_texture parameter to the path of your cubemap in the seq_manager and load it from extract. That way you can have per-unit local cubemaps!

Cubelights are a six-sided texture used for projecting static shadows from lightsources onto the environmentHere's an example:

You can do that too! All you have to do is to spawn a light_omni_shadow_projection in the spawnmenu.All lights with a shadow_projection prefix can build projection textures.Now just select the light, head over to the env manager and press "Build Projection Lights" (this will fail if you dont have python3 and PIL module installed)

Same as with cubemaps, the projection texture will only start working after a reload.Let's compare the two:Before:After:

Building projection lights can also fix light leaking through map geometry

Projection lights don't build for a specific light unit!

If your light unit does not have options such as shadow resolution or doesn't have any light settings at all you would need to extract it to build projection lights

(Old pages, still useful for reference)

Here is a list of potential issues you may have when working on custom maps.

Out of Memory Crash

Application has crashed: C++ exceptionCould not load texture because IDirect3D9::CreateTexture call failed.Direct3D could not allocate sufficient memory to complete the call.

This issue only happens on maps that have too many assets loaded, through overbloated packages or high file size assets.Temporary workaround to this issue is to lower texture settings to Medium or lower, however in most cases this can be avoided by loading assets that only exist in larger packages from Extract.

If you use more than 2000MB of memory in editor you will likely crash due to team Ai using a very large amount of memory, even more likely players will crash when using mods in the heist also.The White House heist uses ~1600MB.The Safehouse uses ~1600MB.

You can figure out how close you are to 'OOM' (Out of memory) crashing by using the -qa steam launch option.

Ingame it will look like this.

Loading units

TLDR: two of the solutions are near perfection but both have some drawbacks, adding them from extract cannot load some units and packages cause slow loading times and unstable maps.

Loading units for maps was an issue I tried solving for a long time.

Loading from extracted files

Phase 1:

With overkill adding a new function to add files(DB:create_entry) I found out you can force existing assets to be loaded by loading them from the map itself but sadly this has a few issues, first of all it takes a lot of space and secondly biggest issue is that it cannot load effects from what I know which can cause some units to crash.

Phase 2:

After releasing the editor I had that idea floating in my head that maybe we don't need the model and texture of the asset to make it load in the map(had the idea after finding out you can mostly only read these files inside the game using DB:open even if they're not loaded) and I was right, after testing that it had no issue what so ever to load the units.

With phase 2 we cut the file size of the map by a lot(for example I tried doing that for a big custom heist and it was only around 8mb) this makes that method a more viable option now the only remaining issue is that DB:create_entry does not support effects which is a big issue and can cause some units to fail to load, this option is not really viable for characters.DB:create_entry also doesn't support fonts from what I know(pls ovk)

In future versions of the editor you will see an improvement to the load from extract system.

Loading packages

After fiddling around with packages I found out you can load as much as you want as long as you monitor the size of the packages(packages are actually bundles just non hashed! so we can see their actual size by using core lua functions) this method a limitation, it can be quite hard to load packages for big maps resulting in the map loading too much packages which can also cause the loading to be very slow and make the map unstable.

(Old pages, still useful for reference)

Environment is like a config which decides how light and shadows look in your level, this is what makes the level a night map or a day one, you can also use environment areas to make rooms look better, here we will talk about making them generally.

All of the actions are done in environment menu which is the world icon at the top menu.

You can edit the values of the environment freely, for now we won't have an exact explanation for each value in there, you can play around with it until you feel comfortable with the controls and the environment itself.

Some points:

• Colors are buttons for color selection dialog
• Intensity sort of controls how much the color is being applied.
• Sky texture is the texture of the sky, you can use moon texture to make it a night map(play with color top, color low and sun color also)

You can save the environment for any use by pressing save, this will open a dialog to fill a file name for the environment(the directory starts from your game directory)
Press Apply and you're done.

If you wish to include that environment in your level you have to press Include current, this will add the environment to your level, which will allow you to use it in the level in an envrionment area.

After pressing it, the environment should be added to the Included Environmnents

(Old pages, still useful for reference)

Navigation links or navlinks for short are ElementSpecialObjectives that have "Is Navigation Link" set to true.

They are used to allow enemies to get from one navigation part to another.

When they are executed they can be used freely by enemies/ai teammates. You need to go to "Manage Access Flags" and select which units should be able to use this navlink.

"Search Position" needs to be somewhere in the navigation area that the enemy should go to after doing the animation.

(Old pages, still useful for reference)

Occluders are simple planes that are used to hide props (specifically objects of a unit).

In the model itself oc_planes (the commonly name for them) are a one-sided plane pointing its occluding face in the Y-Positive direction.

Occluder planes are set in the object file of a unit.

<dynamic_object><occluders><occluder name="oc_plane_001" /><occluder name="oc_plane_002" /><occluder name="oc_plane_003" /></occluders></dynamic_object>

Warning, occluders are limited to 5 active at a time decided by what occluders are nearest to the camera.

Portals are groups of units that are made visible by standing inside shapes.

You first make a Portal in the Portal World menu, Then once a portal is made you can select that Portal. Having a Portal selected and then selecting units in your level will allow you to Add To Current Portal (Or Remove).

Units inside a Portal group will show a red bounding box over that unit to indicate that its in the active Portal.

Units do not have to be inside a Portals shapes to be included, they can be for example Backdrop props that get hidden once you are not outside.

Occluders do not have to be in a dedicated occluder unit, if you believe its neccisary they can be included in a prop unit.

Occluders have a hard time updating in the level, You cannot use an Enable/Disable/Move/Rotate Unit Element to toggle or reposition them, but you can use the Delay Load setting on the occluder unit and have it show later using Load Delayed Elements.

Occluders may be limited to 5 closest planes at a time, but if you arent looking at an occluder plane it will not be used.

Occluders will ignore units that use <network sync="spawn" /> or other forms of network sync. This includes most interactable units or enemies.

Multiple Portals can be used on a single unit, you are not limited to 1 Portal per unit.