Back To Guides

How to use custom packages in your heist

This page will explain what a custom package is, how it works and why you should use it.


  • BeardLib Wiki - Package Module
  • BeardLib Wiki - AddFiles Module

  • What is a custom package?

    A custom package is emulating base game packages. They're basically just lists with assets that should be loaded whenever the package is being called.
    Assets in a package are not loaded when launching the game, but only when it's needed.

    Why use custom packages over add.xml?

    First of all, using the add.xml is a perfectly fine way of handling assets. We're not suggesting to exclusively use only one of the 2 options, but to use both to make use of each of their advantages.
    That being said, there are several reason as to why you should use custom packages:


    It's easier to keep custom packages organized. You can arange the assets however you like and even add comments to label them.
    Trying to do that in the add.xml doesn't quite work, as any little change to it by the editor, such as loading a new unit, will reset the formatting and remove all comments.

    You can also use multiple packages for different purposes. For example have a package for just NPCs while keeping props and architecture units in a different package.


    To keep memory usage as low as possible, it's recommended to unload unused assets from your add.xml. There's even a handy button for that in the Asset Manager. However this will also unload characters, dependencies and custom assets from it.
    Having those assets in a package separate from the add.xml can help in reducing crashes from unloaded assets, as the Asset Manager can not touch your package and won't remove stuff from it.

    Custom Assets

    If you are working with custom assets, you absolutely want to use custom packages for them. All 3 points mentioned above apply here, you want to keep your custom assets separate from vanilla assets for all those reasons.
    Another advantage is that custom packages can make use of unload_on_restart, which reloads the assets every time the level is being restarted. This is a huge help when developing your custom assets as you won't have to restart the entire game every time you make a little change.


    Once set-up, a custom package can be used by any level in your heist. Assets inside the package will be available for all levels using the package with just a single line of code, rather than copy-pasting whole chunks of code from one add.xml to another.

    How to set up a custom package

    To set-up a new custom package, simply create a Package module inside the table tag of your heist's main.xml.

    XML (Custom XML)
    <Package id="your package id"/>

    To add assets to the package, you can just add them into the module like this:

    XML (Custom XML)
    <Package id="your package id" unload_on_restart="true" directory="assets"> <unit path="path to the .unit file"/> <object path="path to the .object file"/> <model path="path to the .model file"/> <material_config path="path to the .material_config file"/> <texture path="path to the .texture file"/> </Package>

    However, doing this will quickly clutter your main.xml, even more so when making multiple packages.
    The solution to that is to create a new XML file for your package and linking to it using the file parameter.
    Remember to put the file extension into the path as well.

    XML (Custom XML)
    <Package file="path to your xml file with file extension" id="your package id" unload_on_restart="true"/>

    Now you can just put your assets into the newly created XML file the same way you would in the level's add.xml:

    XML (Custom XML)
    <table directory="assets"> <add> <unit path="path to the .unit file"/> <object path="path to the .object file"/> <model path="path to the .model file"/> <material_config path="path to the .material_config file"/> <texture path="path to the .texture file"/> </add> </table>

    You can add as many packages this way as you want.

    How to add the package to your level

    To add your custom package to a level, look for the <packages> node inside your level module and add your package ID as a value_node like this:

    XML (Custom XML)
    <level id="your level id"> <packages> <value_node value="your package id"/> </packages> </level>

    Alternatively you can also add your package through the ingame Asset Manager.

    For custom instances this works in the same way.