OpenArena data for Debian
=========================

The version of the OpenArena data in Debian is split into several source and
binary packages, to avoid having to upload hundreds of megabytes for any
change. The source packages come from branches of a common git repository,
with minimal changes: to simplify this, the majority of the packaging is
duplicated between all the source packages.

The binary packages mostly consist of large zip files ("PK3 files"), which are
loaded by the ioquake3 engine. The source packages contain smaller files
(textures, sounds, etc.) which are compressed into the PK3 file, and the
source files for those smaller files. Most of the source packages correspond
to a single PK3 file, since that's the smallest unit that can produce a useful
binary package; some source and binary packages combine a number of smaller
PK3 files.

During the build step, we pack up the smaller asset files using zip(1) to get
an equivalent of the upstream-supplied PK3 files.

Checksums and network compatibility
-----------------------------------

In the default "pure server" mode, the Quake III engine enforces compatibility
between versions by requiring that the PK3 files used on the server and all
clients are basically identical: they must contain files with the same CRC-32,
in the same order.

As a result, modifying the assets (textures, sounds, etc.) is possible, but
not particularly useful, since it breaks compatibility with almost every
server. The normal way to replace assets in Quake-III-based games is to add
them to a new PK3 file that comes later than the upstream-supplied ones in
strcmp() order: assets in a later PK3 file will override assets of the same
name in an earlier PK3 file.

To keep the files in the order that will be compatible with upstream and
prevent accidental checksum mismatches, each PK3 file has a corresponding
file matching debian/*.pk3.contents which lists its contents. If you really
want to break compatibility, modify those files. (But don't do that.)

As a result of the "add instead of replacing" approach, all PK3 files in
OpenArena 0.8.8 are actually from OpenArena 0.8.1, except for
pak6-patch085.pk3 and pak6-patch088.pk3 which are from 0.8.5 and 0.8.8
respectively.

QVM bytecode not supplied in Debian
-----------------------------------

Some OpenArena PK3 files include bytecode files (*.qvm), compiled from GPL
C source code by a non-GPL compiler (q3lcc, which is not included in Debian).
In Debian, the bytecode has been removed from openarena-data and its
related packages; the source code is in the openarena package, and is compiled
to native code with gcc instead.

The QVM files inside the PK3 files are replaced by a dummy file starting with
the magic number 'NTVE', and ending with padding produced by debian/qvmbrute.c,
chosen so that its CRC32 matches the one supplied by upstream. Debian's
modified openarena engine detects the magic number 'NTVE' and loads a
native-code equivalent of the original QVM file.

For convenience, since they're slow to generate and entirely deterministic,
the generated fake QVM files are included in the source package and the git
repository. They can be deleted at any time and will be regenerated by the
next package build; it takes about a minute each on a 1.8GHz laptop.

Source code/build system (or lack of)
-------------------------------------

Upstream do not have an official source code release or build system for the
assets. For some files (scripts, most sounds and some textures), the data in
the PK3 is already in the preferred form for modification.

Where source files exist, they are only in the upstream svn repository (which
isn't branched or tagged), and are exported manually into the format that gets
distributed. This source package contains a best-effort attempt at finding the
sources, and does not attempt to automate the manual export process (unlikely
to work well, since as discussed above, identical output is needed). I suspect
that in practice the preferred form for modification is the combination of
the source and exported files.

It appears that upstream svn revision 901 corresponds to 0.8.1, revision
931 corresponds to 0.8.5 (some of the exported files were renamed in r926,
but that's not relevant to obtaining sources), and revision 947 corresponds
to 0.8.8.

Assets from the PK3 files, and the source files for them, are not included in
the pkg-games git repository due to their size; please obtain them from the
orig tarball, or as described below, before building.

How the orig.tar.bz2 is constructed
-----------------------------------

The .orig.tar.bz2 tarball of this package was derived from the upstream's
binary distribution as follows:

* Unpack the documentation files except for CREDITS (COPYING, etc.) from
  oa081.zip to the base directory

* Unpack CREDITS and readme_085.txt from oa085p.zip, and rename CREDITS to
  CREDITS-0.8.5

* Unpack CREDITS and readme_088.txt from oa088p.zip, and rename CREDITS to
  CREDITS-0.8.8

* Copy at least the upstream PK3 files listed in debian/openarena-data.paks to
  the base directory (replacing openarena-data with the name of the source
  package)

* Unpack CREDITS from mp-pak0.pk3 (which is not identical to the one from
  either of the tarballs) as CREDITS

* List the source files corresponding to the assets, or a superset, in
  debian/pak0.r901, etc.

* Run 'make -f debian/rules import-orig', which does the following:
  - list the contents of each PK3 file, with their CRC32s, to
    debian/pak0.pk3.contents (etc.)
  - unpack ../pak0.pk3 to pak0/ (etc.), omitting any QVM files
  - check out upstream svn revisions 901, 931, 947 of /source/assets/ into
    debian/svn-r*/ (which are excluded from the tarballs)
  - delete some non-GPL files from debian/svn-r*/source/assets/ which
    have been excised from releases but are still in svn for some reason
  - copy the source files corresponding to the relevant PK3 files (only)
    into ./source/assets/

* Run 'make -f debian/rules export-orig' to make the "orig" tarball
