This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
fs:packages [2018-12-19 05:40] – [Dependencies] skyjake | fs:packages [2019-11-17 07:32] (current) – [Metadata] skyjake | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | ====== Packages ====== | ||
+ | |||
+ | |||
+ | In Doomsday 2, resources are collected into [[packages]]. This article describes the Doomsday 2 package format and how you should go about creating your own packages. | ||
+ | |||
+ | |||
+ | ===== Package format ===== | ||
+ | |||
+ | A //Doomsday 2 package// can either be a folder or a ZIP archive. Regardless of the type, the file name must have a **.pack** extension. The package is also required to contain metadata that describes the contents of the package. | ||
+ | |||
+ | Below is an example of what a package might look like as a folder structure. This package is from one of the Doomsday test apps, and it contains 3D model and image files. | ||
+ | |||
+ | File structure: | ||
+ | | ||
+ | net.dengine.test.glsandbox.pack/ | ||
+ | info.dei | ||
+ | models/ | ||
+ | boblampclean.md5anim | ||
+ | boblampclean.md5mesh | ||
+ | guard1_body.png | ||
+ | guard1_face.png | ||
+ | guard1_helmet.png | ||
+ | iron_grill.png | ||
+ | marine.md2 | ||
+ | Marine_green.pcx | ||
+ | round_grill.png | ||
+ | testpic.png | ||
+ | |||
+ | The **info.dei** file has the following contents: | ||
+ | | ||
+ | title: GLSandbox Test | ||
+ | version: 1.0 | ||
+ | license: GPL 3+ | ||
+ | tags: test | ||
+ | |||
+ | |||
+ | ==== File name and identifier ==== | ||
+ | |||
+ | **Naming conventions.** Here is a brief overview of the conventions used in package file names. These conventions are described in more detail elsewhere on this page. | ||
+ | |||
+ | * File extension must be **.pack** | ||
+ | * Prefer to use lower case letters | ||
+ | * Underscore is a special character (separates name from version number) | ||
+ | * Must have at least two components (dot-separated) — see also [[# | ||
+ | * Reverse domain name notation | ||
+ | |||
+ | **Package identifier.** The name of the package file/folder has a special meaning: it is used as the package' | ||
+ | |||
+ | We have chosen to use [[http:// | ||
+ | |||
+ | A package identifier is required to have at least two components. For example: // | ||
+ | |||
+ | **Alternative versions of packages.** Consider the package file name: **net.dengine.test.glsandbox.pack**. What if you have two versions of this package that need to co-exist in the same folder on a hard drive (or in an online repository)? | ||
+ | < | ||
+ | net.dengine.test.glsandbox_1.2beta.pack | ||
+ | | ||
+ | </ | ||
+ | Anything following the left-most underscore (_) found in the package file name is excluded from the package identifier. Doomsday attempts to parse a version number from the part following the underscore. | ||
+ | |||
+ | **Folders and ZIPs.** A package may be either a regular folder or a ZIP archive. Likewise, subpackages contained within a package may be either regular folders or ZIP archives. At runtime, Doomsday accesses all ZIP archives as regular folders. Therefore, you can use whichever format is most suitable for your needs. | ||
+ | ==== Metadata ==== | ||
+ | |||
+ | |||
+ | Every package is required to have metadata. In practice, the metadata is a [[:Doomsday Script]] [[script: | ||
+ | |||
+ | **The Info file.** The root folder of the package must contain a file named **info.dei** or **Info**. This is the primary place where the package' | ||
+ | |||
+ | **Required metadata.** The following four variables must be defined in the metadata for a package to be loadable by Doomsday. | ||
+ | |||
+ | ^ Variable^ Description | | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | | '' | ||
+ | |||
+ | |||
+ | **< | ||
+ | |||
+ | |||
+ | ==== Scripting ==== | ||
+ | |||
+ | |||
+ | **Globally available DS modules.** A package may contain [[:Doomsday Script]] modules that are made available for importing from all DS scripts. This is done by adding the '' | ||
+ | importPath < | ||
+ | The import path must be specified as an array, which is why the angle brackets are used here (see [[modding: | ||
+ | |||
+ | **Load/ | ||
+ | |||
+ | |||
+ | ==== Subpackages ==== | ||
+ | |||
+ | |||
+ | A subpackage is a package that is contained inside another package' | ||
+ | |||
+ | Let's examine the client' | ||
+ | | ||
+ | net.dengine.client.pack/ | ||
+ | Info | ||
+ | defaultstyle.pack/ | ||
+ | modules/ | ||
+ | renderer.pack/ | ||
+ | lensflares.pack/ | ||
+ | testmodel.pack/ | ||
+ | |||
+ | Here we have **.pack** folders inside the main // | ||
+ | |||
+ | The rule about **Info** remains: a package is only loadable if it has metadata. However, subpackaging still works without metadata. In the above example, you could omit the **Info** inside the root folder, and still be able to load // | ||
+ | |||
+ | It is allowed to place packages in other folders inside a package, however those will have to be named using their full identifiers as they are not treated as subpackages. | ||
+ | |||
+ | |||
+ | ==== Dependencies ==== | ||
+ | |||
+ | |||
+ | A package may require other packages to be loaded before it can be used. The required dependencies of a package are specified using the '' | ||
+ | | ||
+ | requires < | ||
+ | |||
+ | |||
+ | Packages may also be configured to be optional. The '' | ||
+ | | ||
+ | recommends < | ||
+ | extras < | ||
+ | |||
+ | Below is a link to an example that demonstrates setting up dependencies between packages: | ||
+ | |||
+ | * {{file: | ||
+ | |||
+ | ==== Assets ==== | ||
+ | |||
+ | |||
+ | Packages may contain any kind of files and any amount of Doomsday Script. To let Doomsday know that the package contains something it can use (an // | ||
+ | |||
+ | Package assets are a generic mechanism in the sense that it builds on the Doomsday 2 file system and Doomsday Script, and leaves the interpretation of the asset definitions to whichever subsystem uses the asset. | ||
+ | |||
+ | All the assets provided by a package are defined in the package metadata. For instance, a 3D model asset definition could look like this: | ||
+ | | ||
+ | asset model.thing.possessed { | ||
+ | path = " | ||
+ | } | ||
+ | |||
+ | |||
+ | The Info block type '' | ||
+ | |||
+ | |||
+ | ==== DED definitions ==== | ||
+ | |||
+ | |||
+ | Packages can contain [[:DED]] definitions that are only in effect when the package is loaded. | ||
+ | |||
+ | The '' | ||
+ | | ||
+ | defsPath = " | ||
+ | |||
+ | This would look for DED files in the folder **/defs** inside the package. Only this folder is checked — any DED files in subfolders are not automatically read. You can use the '' | ||
+ | |||
+ | |||
+ | ==== Icon image for the UI ==== | ||
+ | |||
+ | |||
+ | Packages can provide an image file specifically meant for representing the package in GUIs. Simply place an image file called **icon.jpg** or **icon.png** in the root of a **.pack** package. The maximum allowed size for the image is 512x512 pixels. There is no other limitation for the resolution and aspect ratio (doesn’t have to be square; can be small). If you use a PNG image, it is allowed to have an alpha channel for a non-rectangular shape. | ||
+ | |||
+ | The package icon is not declared or affected by the package metadata in any way — only the presence of the **icon.jpg**/ | ||
+ | |||
+ | |||
+ | ===== Aliases and features ===== | ||
+ | |||
+ | |||
+ | A package may have an alias, i.e., an identifier that is different from the one that is determined based on its file name. When such a package is loaded, the package appears under the **/packs** folder also under the alias in addition to its real identifier. | ||
+ | |||
+ | For instance, the shaders and images for lens flares are stored in the // | ||
+ | alias: feature.lensflares | ||
+ | However, since the lens flare renderer accesses these resources using the identifer // | ||
+ | |||
+ | For more details about the feature packages used by Doomsday, see [[feature_packages]]. | ||
+ | |||
+ | |||
+ | ===== Creating a package ===== | ||
+ | |||
+ | |||
+ | Here are a few notes that you should bear in mind when creating your own packages: | ||
+ | |||
+ | * **Pick the identifier of the package carefully.** If you own a domain name and distribute your packages on the domain, use that as the basis of the identifier (// | ||
+ | * **Take advantage of subpackages and hierarchical organization.** This allows one to break a larger amount of data into more manageable components. For instance, common resources needed by several assets could be contained in a subpackage. | ||
+ | * **Meaningful title.** The title is the primary name presented to the user, so it should be concise. Don't put a version number in the title, as that is specified separately. | ||
+ | * **Tags.** It is important that packages are tagged using all the [[package_tags|relevant tags]] since that enables users to locate the package more easily. | ||
+ | * **Zipping.** When distributing a package, the top-level package folder should be zipped, and its extension should be **.pack** (NOT **.pack.zip**). However, when developing a package, it is likely easier to leave the package unzipped. | ||
+ | |||
+ | |||
+ | ===== Loading packages ===== | ||
+ | |||
+ | |||
+ | ([[version: | ||
+ | |||
+ | The '' | ||
+ | |||
+ | |||
+ | ==== Knowing which packages are currently loaded ==== | ||
+ | |||
+ | |||
+ | While it is unimportant to understand exactly how Doomsday manages packages at runtime, one detail should be noted. All the packages that are currently loaded (i.e., in use) appear inside the special **/packs** folder in the [[: | ||
+ | |||
+ | Assets appear under **/packs**, too. For example, given the asset above, the symbolic link **/ | ||
+ | |||
+ | |||
+ | ===== Implementation status (2.0 →) ===== | ||
+ | |||
+ | |||
+ | The Doomsday 2 package system was first introduced in [[version: | ||
+ | |||
+ | |||
+ | ===== See also ===== | ||
+ | |||
+ | * [[modding: | ||
+ | * The // | ||
+ | * '' | ||
+ | |||