This page will explain what a custom package is, how it works and why you should use it.
Shortcut: 'BeardLib Wiki - Package Module'
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 custom package are not loaded when launching the game, but only when it's needed.
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:
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.
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.
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.
To set-up a new custom package, simply create a Package module in the main node of your heist's main.xml.
To add assets to the package, you can just add them into the module like this:
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 like this:
Now you can just put your assets into the newly created XML file the same way you would in the level's add.xml:
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:
Alternatively you can also add your package through the ingame Asset Manager.