Porting challenges

Porting this game has been a heroic effort, mostly pulled off in the span of four or five insanely productive weeks by @dcwatson.

• Avara's graphics engine was completely custom and unique. It was able to fill and shade complex polygons in screen-space, which is unheard-of in any modern 3D graphics engine. This was achieved through clever use of Motorola 68k/PowerPC assembly. Though porting the original renderer proved possible, it has been replaced with an OpenGL context to take advantage of hardware acceleration.
• Because of the nature of Avara's 3D engine, all existing BSP shape data was not compatible with OpenGL, which accepts only triangles (the term "BSP" is used loosely here, as the models are technically binary space partition trees, but they are in a format specialized to Avara's rendering engine and are unique from the commonly used BSP format popularized by Quake and other games later in the 90s). Scripts were written to decompose all complex polygons into triangles and save the models into a JSON format that can be read easily.
• The sound engine includes a Doppler/positional audio simulation which was extremely advanced for its time. The custom Huffman encoder and sampling algorithms have been successfully ported. You can thank @jonathan-voss for allowing us to experience the expressiveness of Avara's sounds in the new millennium!
• Avara had its own memory management system that made extensive use of old Macintosh APIs, this was fixed with backward-compatible shims to minimize code changes.
• The game timer originally used interrupts available on early Macintosh systems--it is now based off of threads and system timing functions provided by SDL.
• The networking subsystem required significant refactoring to make use of modern network socket APIs and the expectation of broadband speeds. The original was (successfully!) designed to make the game playable over 14.4k modem internet connections and some expectations about latency needed adjustment.
• The original Avara stored assets in a resource fork, which is a special type of format used in classic Macintosh OSs. These resources were easily parsed with the standard library on the Macintosh, we were able to replace these system calls in a backwards-compatible manner so that the port can use exactly the same assets that the original did. We are in the process of updating the formats to modern and easily used equivalents, and our backwards-compatibility allows us to unit test those updates.
• Many of the algorithms in Avara relied on bit shifting to do math operations, including on pointers, to save processor cycles. Type widths were adjusted, and most of these operations worked without any adjustment, though some were removed to make use of the C++ standard library functions.
• Various mathematical operations in the Avara source were written in 68k assembly only. These have been replaced with equivalent code in C++.
• Countless conversions of Pascal strings to string classes and back, replacing arrays and pointer math with modern data structures when necessary, correcting endianness.
• The entire interface to the original was created with the Macintosh Toolbox libraries, which all had to be ripped out and replaced. We are currently testing different UI options, and using nanovg for in-game information.
• Avara's level format was based around a Macintosh binary picture drawing format called PICT, also known as QuickDraw. We created a new format called ALF to store the equivalent level data in XML. Also provided are tools that can convert PICT resources to the new ALF format.

Other than these specific items, the core of the game logic was immediately cross-platform. The code is designed very cleanly and Juri's wizardry, especially for having done it all in 1996, cannot be overstated. Avara is a joy to work on and play, so we hope you decide to check it out! Visit us at irc://avaraline.net:6667/avaraline to chat and maybe even ✓✓ play some games.