fur2amk

Since 2018, I have been involved in the modding scene for Super Mario World for the Super Nintendo. A deep community of dedicated rom-hackers have been disassembling and reassembling SMW since the game came out in 1990, leading to a rich tapestry of custom mods that test a range of skills spanning level design, assembly programming for the 6502, gaming skill, and most important for this project – creating custom music for the Super Nintendo.

A still from my romhack, Mycelium
A still from my romhack, Mycelium

Some Background

Making music for the Super Nintendo Entertainment System (SNES) involves working with the command and register set of the SPC700 chip.When Nintendo released the SNES, they did not provide a universal sound driver for the SPC700, and developers were largely left to design their own sound drivers for whichever game they were working on. Nintendo used a sound driver called N-SPC, which is what Super Mario World uses.

In order to easily interface with Super Mario World and its N-SPC sound driver implementation, the SMW community designed a program called AddMusicK which takes a song written with Music Markup Language (MML) and inserts it into a Super Mario World ROM as a compatible command stream.

Here’s what some MML might look like in the AddMusicK format:

$ED $7F $E0
$F4 $01
o2 c+32 / [c+32^64 r64 c+64 r64^16 d+16 e16^64 r64 e64 r64^16 < g+16 a16^64 r64 a64 r64^16 e16 d+16^64 r64 d+32 g+16 > c16 c+32]10

Many have learned this format and created some seriously impressive songs with it. However, as a composer who is primarily accustomed to working in modern DAWs, I found it difficult to find creative flow writing MML. I wanted to find a user-friendly interface that could be used to make a SNES composition, then figure out how to transpile that into well-formed MML.

Looking for Alternatives

This sort of converter had already been done before in a multitude of ways. There were converters out there to go from MIDI to MML, MuseScore to MML, and even already-compiled SNES binaries to MML.

One converter that particularly caught my eye was an Impulse Tracker to MML converter. Trackers are a popular way to compose music for older hardware where music is defined as a command stream. They allow you to specify which commands should happen on a per-tick basis, providing a convenient grid interface for doing so.

Impulse Tracker

While this interface is great for composing retro-style, known as chiptune, it does not tailor specifically to the Super Nintendo’s command set. As a result, the output of this converter must be moulded to fit the constraints of Super Mario World and not all functionality is easily accessed from Impulse Tracker.

Enter the Furnace

Before long, I discovered a modern tracker project called Furnace Tracker.

Furnace Tracker

Furnace not only provides a beautiful tracker interface, but also has modules of command sets tailored to specific chipsets for various old PCs and gaming consoles – including the Super Nintendo! This meant that, in theory, it should be possible to develop a 1-to-1 mapping between a SNES Furnace Tracker project binary and hardware-compatible AddMusicK output.

All that remained was to actually write the conversion project to do this…

Creating fur2amk

After many labors, fur2amk was eventually born and met with great appreciation from the SMW community. I have been using it for some time now to create original music for romhacks, such as the following relaxed tune, entitled Jellyfish Fields.

Because of the great complexity of the Furnace Tracker input format, as well as the output MML, it was crucial that the conversion architecture be carefully designed to allow for modularity and flexibility as formats change over the years. The most helpful design decision in this respect was splitting the program into two halves – one to convert the Furnace project file to an intermediary format I dubbed Chiptune Data, and the other to convert from that format to the AddMusicK format. Each half also has separate classes for the file parsing/writing and the data conversion steps.

The resulting architecture takes this form:

The Furnace project binary is parsed and stored in the internal FurnaceData format for further manipulation. The FurnaceConverter class then abstracts away all the furnace-specific features like macros, command fades, tracker rows, and pitch bends. This gets everything into the uniform, pliable ChiptuneData format.

The AMKConverter then converts the Chiptune Data into a more AMK-like internal data format, putting everything in terms of AMK-specific commands and preparing to write everything out to the final MML syntax we need. The AMKWriter then emits everything into well-formed, human-readable MML.

Making it Fit

One of the most challenging aspects of this projects was optimizing the output. If the generated MML is raw and unoptimized, the song may be too large to fit within the audio RAM constraints of the Super Nintendo. It is therefore important to detect and automatically loop repeated sets of commands, as well as avoid repeating commands that would be redundant. Additionally, in order to have your compositions hosted on the prestigious smwcentral website, the song must be highly optimized.

Most MML generation programs do not make much of an attempt at optimizing the MML, leaving it to the user to do this instead. However, I wanted to create a program that could generate highly optimized MML right of the gate, meaning users would never have any reason to look at the MML at all. I wanted it to behave as a compiler does for generating assembly from C. Of course, it would not only have to be optimized, but human-readable to meet the needs of public hosting on smwcentral.

The result is a musically-informed compression algorithm, running Lempel-Ziv at its core. Using the time signature and grid highlight hints from the Furnace project, the song is broken down into a series of sections, which are then decomposed into a series of “sentences” that containa subset of musical phrases from the composition. The lz77 compression algorithm then scans all of the sections in the song to find repeats and labels and loops them if any are found. It then looks within each section individually to find repeated series of MML sentences to create loops there as well. This required two different implementations of lz77 – one to search for patterns within a contiguous segment of objects, and one to search between two distinct groups of objects. The same core algorithm is used for both section and sentence pattern matching. You can see my lz77 implementation on github here.

You can also check out the whole codebase on github. If you are interested in making music with this tool, I have a tutorial published on smwcentral here.

I learned a great deal about code architecture throughout this project, as well as some interesting low-level optimization algorithms. I have certainly gained a greater appreciation for those who create compilers – the algorithmic complexity can get fairly intense with this sort of task.

I look forward to creating more tools like this going forward – for now, fur2amk is mostly complete.

Thanks for reading, and happy composing!