## Adding a game to `game-data-packager`

### Step 1: required files for the `.deb`

#### things to include in the template package

Debian policy requires the following to be present within the metadata
section of a binary package

 * the control file
 * a copyright file, in `/usr/share/doc/package/copyright`

For new games in `game-data-packager` these are normally
`data/*.control.in` and `data/*.copyright`.

Policy dictates the following fields within the control file:

 * `Version` field. `VERSION` will automatically be replaced with
   using the version of gdp which generated the template package.
   We recommend using either `VERSION` or, if the generated package
   is guaranteed to contain the vendor's version 1.23 data, `1.23+VERSION`.
 * `Maintainer`.  We recommend using the same maintainer as for gdp,
   which is the Debian Games Team.
 * `Description`. Both the single line synopsis and the extended
   description that follows.
 * Any required dependencies.  For game data packages, we use
   `Recommends` to recommend a corresponding engine package, where
   appropriate.  
   If your game is split in several packages, the package with
   the full game should `Suggests` all the avaible expansions;
   to avoid that those are recognised as useless
   and then removed by aptitude or deborphan.

`game-data-packager` automatically adds:

 * `md5sums` file, so that the user can check whether a package's installed
   files have been modified if they so desire
 * a copy of gdp's own `changelog`

Finally, it might be worth considering the following

 * Should the data package register any menus, or carry a `.desktop` file?
   In some cases, it makes sense to do this from the data package, rather
   than from the engine package.
   * you may also wish to provide an icon file, but bear in mind that if
     you distribute the icon file inside gdp's source, it needs to meet
     the DFSG.  gdp could generate the icon file at run-time in some
     cases.

### Step 2: locate and describe the necessary files

Write a YAML document that describes the files needed and how to get them.

There are three main constructs in the YAML document: *top-level metadata*,
*known files* and *packages*.

#### Top-level metadata

* `shortname`: string: the short name of the game, such as `quake3`.
* `longname`: string: the "marketing name" of the game, such as Quake
  III Arena.
* `compress_deb`: boolean, default true: If false, the `.deb` will never be
  compressed. Use this if it contains non-compressible files (e.g. `*.pk3`
  which are zip files) for which `xz` will waste a lot of time and
  produce poor results.
* `try_repack_from`: string or list of strings: extra locations to search
  for data files, in addition to the installed location of the .deb
  and likely Steam directories.
* `help_text`: multi-line hard-wrapped string: extra text for `--help`,
  explaining which files are needed and where to get them.

#### Known files

Known files are identified by a unique name. It is usually the canonical
filename, but if there are several variants of a file (e.g. `doom.wad`)
you must use a distinct name for each variant (e.g. `doom.wad_1.666`).

Known files are described in the `files` top-level item, which is
a mapping from unique name to a mapping:

* `size`: integer: size in bytes
* `distinctive_size`: boolean, default false: if true, files of size `size`
  are assumed to be this file. Use this for large files with a characteristic
  size.
* `distinctive_name`: boolean, default true: if false, files whose name
  matches this file's `look_for` names, but which do not match this file
  by size or hashes, do not provoke a warning. Use this for files with
  generic names like `README.TXT`.
* `download`: string or mapping: where to download this file. FIXME: explain
* `provides`: list of strings: unique names of some known files that can be
  unpacked or extracted from this one
* `md5`: string: md5sum of this file
* `sha1`: string: sha1sum of this file
* `sha256`: string: sha256sum of this file
* `unpack`: mapping: how to unpack this file. The mapping must have at least
  one key, `format`, with possible values currently `tar.gz`, `zip`, `lha`
  or `dos2unix`.
* `alternatives`: list of strings: if given, this known file entry
  is actually an abstraction representing a list of possible known files
  identified by their unique names. Use this if more than one version is
  acceptable, and it is not easy to obtain the most preferred version.
  Alternative sets may not have sizes or checksums, but they may be
  installed in packages, which will result in the first available option
  being installed under the name of the alternative set.
* `install_as`: string: when installing this file in a package, use this name
  instead of its own.
* `look_for`: list of strings: when searching for this file, look for
  these names (case-insensitively). The default is a list containing only
  the unique name.

`md5sums`, `sha1sums`, `sha256sums` items at top level can be used to provide
the hashes for a bunch of files at the same time.

The `install_files` item in a package (see below) can be used to flag
several files for installation and also provide their metadata
in the same format as `files`.

The `install_files_from_cksums` item in a package can be used to flag
several files for installation and also provide their sizes, using
cksums(1) syntax.

#### Packages

The `packages` top-level item is a mapping from Debian binary package name
to mapping:

* `longname`: string: the "marketing name" of the game or expansion
  in this package, if it differs from the top-level `longname`
* `type`: string: either `full`, `demo` or `expansion`. Full games
  are what you expect. Demos are cut-down versions of a full game,
  typically advertised as demo or shareware, which can be installed
  if the full game is not available. Expansions are add-ons or mission
  packs which require the corresponding full game, such as
  Quake III Team Arena for Quake III Arena.
* `install`: list of strings: unique names of known files or alternative
  sets to install

### Step 3: advanced

You can write a Python plugin in `game_data_packager/games/SHORTNAME.py`
if you need to implement different command-line parsing or behaviour.
Please don't do this unless you really need to.
