Differences

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

--- fs:addon_box [2020-01-06 20:16] – [Box (add-on format)] skyjake
+++ fs:addon_box [2020-01-10 10:56] (current) – [Example] skyjake
@@ Line 1: / Line 1: @@
+====== Box (add-on format) ======
+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 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.
+===== Overview =====
+The **.box** format is a special [[modding: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 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
+===== 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 [[modding:addon bundle]]s, there is no **Contents/** subfolder. This is intended to highlight the fact that the box itself contains no data: it is merely a group of other addons.</note>
+==== Metadata ====
+[[modding: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 [[modding:Info]] in [[modding: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 GUI.
+=== 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.
+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 [[modding: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.

Doomsday Manual

User Tools

Site Tools

Differences

Page Tools