adding_a_game.mdwn 10.5 KB
Newer Older
1 2
## Adding a game to `game-data-packager`

3 4 5 6 7 8 9 10 11 12 13
### Step 0: working with the git tree

$ git clone
$ make

Then the `./run` command can be used instead of the
system-installed `game-data-packager` command.

Further calls to `make` will only process modified
new game description data in data/.

### Step 1: locate and describe the necessary files
15 16 17 18 19 20

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

21 22 23
Alternatively, you can try `game-data-packager make-template <directory>`
which should get you easily started.

24 25 26 27 28
#### 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.
29 30
* `copyright`: string: © <year_of_first_release> <developper/publisher>
  This should match the title screen of the game, if any.
* `engine`: string: package name that contain the program needed to run the game.
* `genre`: the game genre
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
* `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
* `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`.
60 61
* `license`: boolean, default false: if true, it is listed as a license
  file in generated copyright file.
  Per policy, license files should go in $pkglicensedir. (see `install_to`).
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
* `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.
81 82 83 84 85
* `install_to`: string: overide location where to install this file.
  The special value $pkgdocdir will be expanded to
  usr/share/doc/<package_name>, and $pkglicensedir will be expanded to
  usr/share/doc/<package_name> or usr/share/licenses/<package_name>
  depending on distribution.
86 87 88 89
* `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.

`sha1sums`, `sha256sums` items at top level can be used to provide
91 92 93 94 95 96 97 98 99 100 101 102
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`.

#### 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
103 104
  in this package. The default is to use the top-level `longname`,
  with appending ` (demo)` appended for packages with a `demo_for` tag.
* `copyright`: string: the copyright string, if it differs from top-level
106 107 108 109 110
* `demo_for`: this reference the full game included in same YAML file  
  `expansion_for`: this reference the matching full game included
  in the same YAML file.  
  Full games are what you expect.
  Demos are cut-down versions of a full game,
111 112 113 114 115 116
  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
* `engine`: let you overide the engine in special cases

119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
#### Steam games

For games that can be bought from Steam, the top-level metadata, the
individual packages or both can have a mapping named `steam`, with
these keys:

* `id`: the numeric identifier of the game, as seen in
  URLs like
* `path`: the directory below `steamapps` where Steam installs the game,
  usually starting with `common/`

#### GOG games

Similar to Steam, games sold on can have a mapping named `gog`
with these keys:

* `url`: the game-specific part of games' URLs, such as
  `the_ultimate_doom` for
* `game`: some games are sold on as a bundle, this is the
138 139
  name of each individual part. Use `lgogdownloader --list` to
  know this value. If not specified, this default to the value of `url`.
140 141
  Example: `the_zork_anthology` includes `zork_the_great_underground_empire`,
  `zork_ii_the_wizard_of_frobozz`, `zork_iii_the_dungeon_master` ...
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169
* `pp`: an affiliate ID, typically used to donate to a relevant game engine
  (if not specified, g-d-p will use ScummVM's affiliate ID)
* `path`: the directory below `GOG Games` where the GOG installer puts
  the game by default, or a list of strings if more than one directory
  is used by different installer versions. game-data-packager will
  search any directory that starts with this string, so language
  suffixes are not necessary: if GOG will install "Some Game (German)",
  only "Some Game" is needed.

#### Origin games

Similar to Steam, games sold on Origin can have a mapping named `origin`
with these keys:

* `path`: the directory below `Origin Games` where Origin installs the game

Use the `url_misc` top-level key for Origin download URLs: see
`data/syndicate.yaml` and `data/theme-hospital.yaml` for examples.

#### dotemu games

Similar to Steam, games sold on dotemu can have a mapping named `dotemu`
with these keys:

* `id`: the numeric identifier of the game
* `pp`: an affiliate ID, typically used to donate to a relevant game engine
  (if not specified, g-d-p will use ScummVM's affiliate ID)

170 171 172 173 174 175 176 177 178 179
### Step 2: 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`

180 181 182 183 184 185
`game-data-packager` will automatically build the copyright file
using the contents of the `copyright:` tags in the yaml file;
you only need to provide one if the default generated
copyright file isn't suitable; see for example

186 187 188
`game-data-packager` will automatically build the control file.
It will also ensure that all the field required by policy
are present:
189 190 191 192

 * `Version` field. This will automatically be filled with
   the version of gdp which generated the template package.
   If the generated package is guaranteed to contain the vendor's
   version 1.23 data, you may set it in the `debian: version:`
194 195 196 197 198 199
   of the YAML file.
 * `Maintainer`.  We recommend using the same maintainer as for gdp,
   which is the Debian Games Team. This is also the default value that
   will be provided if this field is missing.
 * `Description`. Both the single line synopsis and the extended
   description that follows.
200 201
   Most of the extended description is automatically edited,
   you can provide extra information by using a `description:` tag.
202 203 204
 * Any required dependencies.  For game data packages, we use
   `Recommends` to recommend a corresponding engine package, where
   appropriate. To document an engine, you should add
   a `engine:` key in the YAML file.
   If your game is split in several packages, the package with
207 208
   the full game should have a `Suggests` relationship on all the available
   expansions; to avoid them being classified as unused
   and then removed by aptitude or deborphan. This is done
210 211 212
   automatically if you set the correct `expansion_for:`.
   An expansion will also automatically have a `Depends` relationship with
   the matching full game.
213 214
   If ever needed; the standard Debian dependencies are also supported
   using the `debian: depends:/recommends:/suggests:/replaces:/...` keys.
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231

`game-data-packager` also 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

### Step 3: advanced

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

If you're adding a scummvm game, this list will help you find out
239 240
which version you have, but it only includes md5sum of
the N-th first bytes of the main data file: