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 together into a single folder.

The .box format was initially created for the Snowberry launcher app. Recent versions of Doomsday support it, too.

In Doomsday 2, packages can be set up to contain other packages.

The .box format 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 a GUI) to customize components and to drill down to the information of a specific component (e.g., determining the author of your favorite 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
|...

Info is a plain text file — note the lack of extension in the name — which describes the contents of the box (i.e., metadata). This is analogous to the use of Info in addon bundles.

A box may contain multiple sub-component addons. For example, a box might comprise two required PK3s, an optional DED, and one WAD file. The only restriction is that a box cannot contain other boxes.

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 GUI.

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.

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.