How to use custom packages in your heist

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:

Organization

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.

Cleanup

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.

Reusability

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.

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 using the file parameter.
Remember to put the file extension into the path as well.

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

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:

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

For custom instances this works in the same way.