BLE Overview

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.

BLE Menu.jpg

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.

ble_menu_project.jpg

Anything here can also be edited by opening your project’s main.xml with a text editor.

main_xml.png

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.

ble_menu_levels.jpg 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. ble_menu_scriptdata.jpg

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. ble_menu_options.jpg

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.


Toolbar

The Toolbar gives you quick access to various commonly used settings, without having to navigate through menus.

toolbar.png 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.

gui_select_main.png

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.
gui_select_qa_unit.png

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.
gui_select_qa_element.png

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. gui_select_qa_instance.png

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.
gui_select_transform.png

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.
gui_select_transform_raycast2.png

Grab will grab the selection and temporarily snap it to your cursor. gui_select_transform_grab2.png

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.
gui_select_transform_round.png

Copy will copy the current value into your clipboard.
gui_select_transform_copy.png

Paste will paste the values from your clipboard. Keep in mind that you can’t paste Position values into Rotation and vice versa. gui_select_transform_paste.png

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.
gui_select_transform_shape.png


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


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, gui_select_all.png

or every item from every page.
gui_select_page.png

Additionally you can filter out continents for units and scripts for elements.


Tools

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.