Skip to content

Modern Avara Level Design (MALD) Guide

Jump to bottom
Andy edited this page Oct 15, 2025 · 2 revisions

The "Modern" Avara port retains much of the original code from the "Classic" Macintosh version, however several things about creating Level Sets for the game have necessarily changed in order to move away from Resource Forks and the PICT file format. MOST of the information in the original ALD still applies, with the exception of the drafting instructions.

We hope to someday include a combination drafting and instant-preview Forge style editor in the future, but this page serves to document the process in the meantime. Note that this design has already been changed several times and will absolutely change in the future: it is difficult for systems like this to be "perfect", but we're on our way through careful iteration.

Background

Classic Avara used Resource Forks to store all of the assets, and level set files were simply standalone Resource Forks that Avara would load in from the disk at request. Forks (and PICT data) are encoded in binary and difficult to work with. In their place, we designed Avara Level Format (ALF). ALF level sets are (currently) folders full of JSON and XML.

level-set-name/
├── alf/
│   ├── the-city.alf
│   ├── the-country.alf
│   ├── another-level.alf
│   └── common/
│       └── stairs.alf
├── bsps/
│   ├── flower.json
│   ├── head.json
│   └── bomb.json
├── ogg/
│   ├── gravelStep.ogg
│   └── hugeExplosion.ogg
└── set.json

The top level folder should be kebab-cased and contain absolutely no special characters, as it gets used as a slug for triggering level loads over the network. These files basically follow the same structure as Classic's level set files. This next bit assumes you know a little bit about Classic's resource fork format, the four letter tags are resource types.

  • PICT resources have become an alf folder, with an XML file for each level--but with the added benefit of includeing other ALF files from subfolders, which we will get to in the new features section.
  • BSPTs have become a bsp folder full of a bespoke JSON model format.
  • HSNDs have been replaced with an ogg folder that can accept mono OGG files of any bitrate.

Finally, there is a required set.json file to tie everything together, store HULL and LEDI information, sound metadata, and dependencies for the aforementioned include functionality to be able to import things from another set.

Converter

The level converter that automatically parses resource forks and creates ALF files is located in the bin folder of the source tree. It is written in python 3+ but the dependencies are pretty hairy, they include numpy and

  • levelset2rsrc.py creates ".r" files, which are binary encoded resoure forks, from AppleDouble files. However this process only works on Macs as it requires filesystem extensions Apple provides.
  • forker.py parses and dumps resource forks from a ".r" file
  • pict2alf.py parses PICT binary and translates it to XML
  • bspt.py parses BSPT binary
  • tmpl.py is a generalized TMPL resource parser
  • ledi.py uses the above to parse the LEDI information
  • rsrc2files.py ties it all together and accepts a level set file and produces a directory structure like the above.

ALFs

ALFs are XML files, where each element corresponds to Classic's pairing of arc + text box in Claris Works. Instead of a drawing, we specify colors and positions as attributes on an element. Here's a Wall example:

<Wall color="#203608" color.1="#000000" x="17" y="3.95" z="-17" w="6" d="6" h="0.1" />

Walls are a special case, since they are defined with rects, plus a "wa" script, we have combined this into a single element with x/y/z/h/w/d.

<Ramp y="4" deltaY="4" color="#203608" color.1="#000000" x="17" z="10" w="6" d="8" h="0.1" angle="180" />

Ramps, requiring both an arc and a rect. Note the "angle" argument, this is the only data that is used from the arcs of Classic maps on ramps specifically, besides color information.

<Goody shape="bspGrenade" speed="2" grenades="4" start="mShow" out="mTaken" cx="18" cz="-36" y="1.75" />

Here we have a placed actor (a goody). You can see that parameters from the "object Goody" script have been converted into XML attributes. cx and cz stand for center X and center Z respectively, and correspond to the "point" of the arc in Classic's PICT files.

<Teleporter shape="bspLotus" speed="2" scale="0.25" destGroup="@se" color="#ffffff" color.1="#000000" cx="38" cz="38" />

Here is a teleporter. Note that in Classic, we could set up an alias to a resource ID like "3000" by adding script like bspLotus = 3000. Instead, you can now use the abstraction in the set.json file to provide a name that points to the JSON file directly.

The set.json file

Its. a json

Clone this wiki locally