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.

You need to convert the file into Aerofoil's "triplet" format, which consists
of a metadata file (extension .gpf), and file forks (.gpd for data, .gpr for
resources).  How you get these depends on the input format:
- For MacBinary files (.bin), use the "bin2gp" utility
- For BinHex files (.hqx), use the "hqx2gp" utility
- For StuffIt (.sit) and Compact Pro (.cpt) archives, use the "unpacktool"
  utility to extract the contents in triplet format.  The "unpacktool"
  utility should support most vintage StuffIt archives made with StuffIt
  Deluxe 6 or lower.

(NOTE: ".sea" files are self-extracting archives, typically StuffIt or Compact
Pro archives with the self-extractor program in the resources.  These will
always be distributed in a fork-grouping container like MacBinary or BinHex.
For cases like these, you need to split the self-extracting archive using
"bin2gp" or "hqx2gp" and then pass the ".sea.gpd" file (which contains the
archive data) to "unpacktool" to decompress it.)

Once you've done that, if the house has custom resources (i.e. a .gpr file),
you need to convert it to an Aerofoil resource archive, which you can do using
the "gpr2gpa" tool.

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.


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.  Currently, Aerofoil
doesn't do any additional validation either, and it's possible that invalid
house data may lead to crashes or even remote code execution.

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.