Sometimes it is necessary to combine multiple addons into a single 'mod' package for distribution. A mod consisting of multiple components (perhaps by different authors) can be packaged into a .box.
In Doomsday 2, packages can be set up to contain other packages.
The .box format (introduced in Snowberry) is a special Addon format, allowing several addons to be collected together. The box itself contains no data, only metadata. All data within the box is contained in separate components.
This separation of metadata from addon-data provides several benefits:
- Allows components to be combined dynamically
- Allows the user, via Snowberry, to customize components and to drill down to the information of a specific component (e.g., determining the author of your favourite map)
- Keeps everything nice and clean
The high-level structure of a .box is as follows:
collection.box / | Info | part1.pk3 | part2.pk3 | required / | part3.pk3 | extra / | part4.wad |...
Note: Unlike in bundles, there is no contents/ folder. This is intended to highlight the fact that the box itself contains no data: it is merely a group of other addons.
Addons in the root are optional. They will be loaded by default along with the box itself.
The extra/ folder should contain addons that that are optional but which are not active by default. These components must be activated manually before use, for instance by checking on a checkbox in the Snowberry UI.
The required/ folder should contain addons that are always loaded when the box itself is loaded. These components won't even be visible to the user.
Note: Snowberry automatically categorizes all addons inside the box according to their type and/or contents and all are visible to the user (except those which are under Required) in the addon tree.
First you'll need an Info file which describes this collection of add-ons. Something like:
name: Amaze-DOOM component: game-jdoom language english ( version: 6.01 summary: Amazing TC (trust me) contact: http://www.moddingworld.com author: Mod-O-tron-2000 copyright: 2015 license: Do what you will, I don't care readme = "Amaze-DOOM TC Look, just play it, damn it!" )
Now create a folder and give it a name of your choosing with a .box suffix. Place here the info file and required subcomponents like so:
amazedoom.box / | info - (the 'global' info file) | required / | episode1.pk3 | episode2.pk3 | ...
Congrats! You now have a multi-component add-on bundle.