====== Resource packaging guidelines ======


This page details the recommended conventions for packaging resources for Doomsday 2.


===== Packaging an asset =====


Every asset, for example a 3D model for a barrel, should be packaged into its own [[fs:packages|Doomsday 2 package]]. This will give users the freedom to load this asset separately from any other assets that you provide.

Common resources needed by many assets, for example texture images, can be placed into a separate package that is then automatically loaded when needed. This common package should be [[fs:tagged]] "hidden", and the packages that need the common resources should use the ''requires'' metadata variable to tell Doomsday to load the common package first. The "hidden" tag will keep the package from showing up in the user interface. 

When choosing the title and tags for the package, consider them together: when the user searches for something, both words in the title and the tags are checked for a match, so including suitable terms/words in both is unnecessary. Also, refrain from adding game names (for example "hexen") in the package title, because Doomsday expects these to be included in the package tags.

Tags should be used primarily as a tool for allowing the user to find the package. For example, if the user is interested in 3D models for Hexen, they might enter "hexen model" as the search terms. All packages that have the tags "hexen" and "model" will then be listed.

In the user interface, package lists are usually sorted by package title. This has two implications:
  *  Making the title as short as possible will help the user to navigate package lists.
  *  If you have several packages that are related to each other, they will be listed together if the beginnings of the titles are the same.

Doomsday supports version numbers with up to four components. If you prefer to use a date-based package version, note that you can split it as follows: ''2017.01.21''.  Writing the version as ''20170121'' causes the version to be parsed as ''20170121.0.0.0'', i.e., the entire version is interpreted as the major version number.


==== Example ====


<code>title: Quartz Flask (Health Item)
version: 2016.03.27
license: GPL 3+
author: veirdo
tags: hexen model item
category: items

requires <veirdo.hexen.common>

asset model.thing.healthflask {
    # ...
}
</code>

===== Organizing a collection of packages =====


When you have a larger collection of assets it will become cumbersome for the user to load each of the packages individually. To help with this, Doomsday implements package dependencies.

A collection package is an empty package that lists a set of required and optional packages in its metadata. The user can easily pick and choose which of these packages are used when the collection package is loaded.

Use the ''notes'' variable to provide any guidance to the user or any other relevant information.

In the Doomsday UI, the package options popup will categorize the contents of the collection using the ''category'' variable defined in the packages. Note that this is separate from and independent of the package tags. (See the previous example.)

Both the ''recommends'' and ''extras'' arrays must be included in the metadata.


==== Example ====


Below is an example of the **info.dei** of a package named **veirdo.hexen.models.pack**. Note that the collection package can and should be a [[fs:subpackage]] and a sibling of the rest of the packages in the collection. This way it can be easily distributed together with the rest of the packages.
  
  title: 3D Models for Hexen
  version: 2016.10.17
  license: GPL 3+
  author: veirdo
  tags: hexen models
  
  notes = "This package gathers all the 3D models into a single collection.
  Loading this package will by default load all the models.
  
  You can pick and choose individual models using the Options button or by
  loading individual packages separately."
  
  recommends <
      veirdo.hexen.item.flask,
      veirdo.hexen.item.vial,
      veirdo.hexen.missile.wand,
      veirdo.hexen.weapon.serpent,
      veirdo.hexen.weapon.wand
  >
  
  extras <>


<note>Support for the Snowberry (launcher front-end application) **.box** format is implemented by internally converting the add-on into a Doomsday 2 collection package.</note>