User Tools

Site Tools


fs:addon_box

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

fs:addon_box [2017-02-23 17:03] (current)
Line 1: Line 1:
 +Sometimes it is necessary to combine multiple addons into a single '​mod'​ package for distribution. A mod consisting of multiple [[#​Components|components]] (perhaps by different authors) can be packaged into a //.box//.
 +
 +In Doomsday 2, [[packages]] can be set up to contain other packages.
 +
 +
 +====== Overview ======
 +
 +
 +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|metadata]]. All data within the box is contained in separate [[#​Components|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
 +
 +
 +====== Anatomy ======
 +
 +
 +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 [[bundle]]s,​ 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.}}
 +
 +
 +===== Metadata =====
 +
 +//​[[info]]//​ is a plain **text file** (note the lack of extension in the name) which describes the contents of the box (known as metadata). (This is analogous to the use of //info// in [[addon_bundle]]s).
 +
 +
 +===== Components =====
 +
 +A box may contain multiple sub-component addons. For example, a box might comprise two required [[pk3]]s, an optional [[ded]], and one [[wad]] file. The only restriction is that a box **cannot contain other boxes**. ​
 +
 +
 +==== Optional ====
 +
 +Addons in the root are optional. They will be **loaded by default** along with the box itself.
 +
 +
 +=== Extra ===
 +
 +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.
 +
 +
 +==== Required ====
 +
 +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|Required]]) in the addon tree.}}
 +
 +
 +====== Example ======
 +
 +
 +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.
 +
 +
 +====== See also ======
 +
 +  *  [[addon_format]]s
 +
 +
 +
 +
 +
  
fs/addon_box.txt ยท Last modified: 2017-02-23 17:03 (external edit)