Adding User Houses

[mendahl]

Hello - thank you for Aerofoil! I used to play Glider PRO in the 90's and this port is very well done.

I am running Aerofoil on Mac OS 10.14. I have a number of houses in .sit format that I am trying to convert to the Aerofoil "triplicate" format. I've read through userhouses.txt but I am unclear on how to use "unpacktool". Can someone provide me with a step-by-step instruction list on what to do? My coding chops are zero.

[elasota]

Unfortunately the Aerofoil tools haven't been ported and are currently only available on Windows.

[mendahl]

OK, thanks for your quick response. I have an archive of about 500 houses, mostly in .sit format. If I send you a Google Drive link, would you be willing to convert some/all of them for me?

[elasota]

I don't think so. The gpr2gpa tool has a wildcard mode now though, so you can bulk-convert houses that way if you can find a Windows machine.

[Diomendius]

Now that #19 has been merged, you should be able to build and run the conversion tools on macOS, unless I overlooked something when porting them. See https://github.com/elasota/Aerofoil/issues/8#issuecomment-2290952634 for more details on building on macOS.

There isn't yet a packaged Mac release of Aerofoil with the tools included, so you will have to build them. I think you need Xcode installed (from the App Store) to provide a compiler, and at minimum you'll need to install CMake to build the tools. For a from-scratch build of Aerofoil itself (and the tools and resources) you also need SDL 2 and FreeType 2. CMake should find these libraries automatically if you have them installed in the way it expects, though I don't know exactly what that way is on macOS.

userhouses.txt provides a broad overview of what you need to convert Glider PRO houses, but it doesn't provide specific usage instructions for any of the tools. You can get a basic usage summary from most of the tools by running them without arguments, but it isn't much. Crucially, userhouses.txt doesn't mention MergeGPF at all, which is needed as a final step for converting any house.

Here's a basic guide to converting an example house from a StuffIt archive with this structure:

Example House.sit
    Example House/
        Example House
        ReadMe

It will help to have some basic familiarity with the command line. Knowing about the working directory and how to change it, and how the shell performs word splitting should be enough, but this is by no means required knowledge.

In Terminal on macOS, you can insert the correctly-escaped full path to any file or folder by dragging its icon onto the Terminal window.

1. Create a folder on the Desktop named ConvertedHouses.
2. Open Terminal and run cd ~/ConvertedHouses to set this folder as the working directory.
3. Run PATH="/usr/local/lib/aerofoil/tools:$PATH" to add the Aerofoil tools folder to your PATH so you can run the tools without having to specify the full path every time.
   • If you installed Aerofoil under a different prefix, or you want to run the tools directly from the CMake build folder, replace /usr/local/lib/aerofoil/tools with the full path to the folder containing the tools.
4. Run MakeTimestamp time.ts to create a timestamp file with the current time. Several conversion tools require a timestamp file.
5. Run unpacktool "Example House.sit" time.ts . to extract the archive. Replace "Example House.sit" with the full path to the archive, for instance via the drag-and-drop method above.
   • Alternatively, just copy Example House.sit into ConvertedHouses and run the command in this step as-is.
   • For each file in the archive, this creates up to three files:
     • file.gpf — Always created.
     • file.gpd — Holds file's data fork, if it has one. Most files have a data fork, including all house files.
     • file.gpr — Holds file's resource fork in raw format, if it has one. Most house files have a resource fork, though it doesn't necessarily contain any useful data.
6. If Example House/Example House.gpr exists, run gpr2gpa "Example House/Example House.gpr" time.ts "Example House/Example House.gpa" to convert the raw resource fork into .gpa format (actually just a zip file with a particular structure).
7. Run MergeGPF "Example House/Example House.gpf" to combine the .gpd and .gpa files into the .gpf file. The .gpf file is also a zip file.
8. Move Example House/Example House.gpf to either the Packaged/Houses folder where the default houses are installed, or to ~/Library/Application Support/aerofoil/aerofoil/Houses.
   • I'm fairly certain about the path under Library based on reading Aerofoil's and SDL's source and Apple's documentation, but I haven't tested this on a Mac. If you've already launched Aerofoil before, these directories should already exist.
9. Delete ~/Desktop/ConvertedHouses, if you want.

---

• For houses archived in MacBinary format, use bin2gp "Example House.bin" time.ts "Example House"
• For houses archived in BinHex format, use hqx2gp "Example House.hqx" time.ts "Example House"

to produce Example House.gpf, Example House.gpd and Example House.gpr, then convert these files as described in the steps above.