ADDING A THIRD-PARTY HOUSE TO AEROFOIL
-------------------------------------------------------------------------------
To add a third-party house to Aerofoil, copy the house .gpf file, and .gpd/.gpa
files, if necessary, to the "Houses" directory inside of the "Aerofoil"
directory in your "Documents" directory, then restart Aerofoil.


IMPORTING EXISTING COMMUNITY CONTENT TO AEROFOIL
-------------------------------------------------------------------------------
If you want to import an existing third-party Glider PRO house to Aerofoil,
a few steps are required.  All Aerofoil import tools are currently command-line
only, so you will need to use a command prompt to use them.  Launch the tool
programs without any arguments and they will give instructions for usage.


Some history: On most modern operating systems, files are a single stream of
data, and the file type is represented by an extension at the end of the file
name.  On classic Macintosh systems, files have 2 streams: The data fork and
resource fork, and the file type (among other things) is stored in a metadata
block that is separate from the file data itself.

Macintosh Glider PRO house files use the data fork to store the level data and
the resource fork to store custom features like sounds.

However, most server software only supports transmitting files as a single data
stream, so Macintosh files were shared in formats that bundle the 3 types of
data into a single data stream, and were converted into the full Macintosh
format files using conversion software on a Macintosh machine.

Aerofoil's unpack tools will always extract Macintosh files as a triplet of 3
files:
- The resource fork will be split to a file with a ".gpr" extension
- The data fork will be split to a file with a ".gpa" extension
- The metadata will be split to a file with a ".gpf" extension

Some file types you may encounter in the wild:
- MacBinary files (.bin): These encode a single file.  Use the "bin2gp"
  utility to unpack it.
- BinHex files (.hqx): These encode a single file.  Use the "hqx2gp" utility
  to unpack it.
- Compact Pro (.cpt) and StuffIt (.sit) archives encode multiple files.
  Use the "unpacktool" utility to extract it.
- Self-extracting archives (.sea) are programs that contain archive data,
  usually in StuffIt or Compact Pro format, in the data fork, and a
  decompression program in the resource fork.  Typically you will encounter
  these as ".sea.hqx" or similar.  For these, you need to extract the .sea
  file from its original encoding, and then pass the data fork file (.gpd)
  to the "unpacktool" utility.


Once you've unpacked the data for the house, you may need to convert the
resources (.gpr file) to Aerofoil's resource format.  Aerofoil can not read .gpr
files directly.

To convert resources for a house, use the "gpr2gpa" utility.  Note that
gpr2gpa's PICT converter may not support all PICT encodings.  If you find a
house with custom PICT resources that isn't supported, please submit a sample
to Aerofoil's issue tracker.

Once you've done this, you should have a .gpf, .gpa, and .gpd file for the
house.  Put them in the Houses directory to add the house to Aerofoil.


IMPORTING TV QUICKTIME MOVIES
-------------------------------------------------------------------------------
Converting QuickTime movies for displaying on in-game TVs is a bit more complex.
First, you need to convert the movie to a sequence of BMP images, which you
can do with third-party tools such as FFMPEG.  Second, you need to create a
JSON file containing the movie metadata, which looks like this, for example:

{
	"frameRateNumerator" : 8,
	"frameRateDenominator" : 1
}

Once you've done that, create a ZIP archive where the path of the JSON file is
"muvi\0.json" and the frames are "PICT\<frame number>.bmp", where <frame
number> is the frame number, starting with 1 as the first frame, and name that
the same as the house name, but with a ".mov.gpa" extension.

Next, you need to create a metadata file for the movie, which should have a
".mov.gpf" extension.  You can create the metadata file using the "FTagData"
utility, using a timestamp file created with the "MakeTimestamp" utility.
I'd recommend using "MooV" as the file type and "ozm5" as the file creator.

You do NOT need to keep the .mov.gpd file once you've done this - Aerofoil
expects all of the movie data to be in the resource archive.


Some old QuickTime movies contain movie tracking information in the movie
resource fork, in which case you need to merge them into the data for modern
utilities to read them.  You can use the "flattenmov" tool to do this: Pass
it the data (.gpd) and resource (.gpr) data files for a movie, and it will
merge them into a single .mov file.


BATCH CONVERSION
------------------------------------------------------------------------------
To batch-convert house resource files, use gpr2gpa with a path that ends
with an asterisk (*) and omit the output filename.


SECURITY CONSIDERATIONS
------------------------------------------------------------------------------
Glider PRO didn't really do any validation of houses.  Aerofoil 1.1 has a
significantly stricter validator, which will reject data that seems
excessively large or invalid.

Also, Glider PRO houses were able to take advantage of a resource overlaying
feature of the Macintosh operating system, where a resource being present in
the house file with the same ID as an application resource would cause the
resource to override the application resource.

Aerofoil's resource loader is much more restrictive: Currently, only
backgrounds, audio triggers, and icons may load from the house data.