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

Every asset, for example a 3D model for a barrel, should be packaged into its own 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 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.

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 {
    # ...
}

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.

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