mirror of
https://github.com/elasota/Aerofoil.git
synced 2025-09-22 22:45:39 +00:00
116 lines
5.5 KiB
Plaintext
116 lines
5.5 KiB
Plaintext
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.
|