Dynamic Music Documentation

// Overview

The music in Mixolumia changes as the player progresses through a game, and the game’s sound effects harmonize with the music being played.

Songs are loaded from external files, which means anyone can make and distribute or sell their own songs (or what I might call “sound packs”) for Mixolumia.

In a nutshell, a song is a folder with one JSON file and a bunch of Ogg Vorbis audio files. A composer can create a series of sections comprised of loops. Each loop has associated sound effects, which are organized into progressions to aid in harmonization.

There are four important sections to make the progression trick work: The start, middle, outro, and end. When the player hits certain numbers of clears, the next section is queued to play after the currently playing loop. The final section, end, is a short finisher when the game ends.

// Sections and Song Structure

Here’s an example of how a song could be structured. Each block in this example diagram represents a loop. Loops that start a section (start, middle, outro, end) must be named correctly, but any other names are up to you.

You can use fewer or more loops depending on how you want to structure the song, and loops can link to any other loop in the progression. The diagram above is just a few examples of how a song might flow.

Note: I am considering allowing for some randomization if you link a loop to multiple other loops to make songs more unpredictable.

The end section may interrupt the song at any time because the player could win before hitting the outro during some game modes. The music should be designed to work, even if the transition is abrupt.

When composing your song, keep in mind that the game will be moving faster as the player progresses, so in a typical Marathon game, the outro will likely last a shorter amount of time than the start or middle sections.

// Loops

Loops are comprised of the following:

The bpm and length of each loop is used so that the loop audio files can contain reverb tails that overlap the next loop instead of abruptly switching.

An example loop might look like:

"start": {

        "audio": "intro.ogg",

        "bpm": 140,

        "length": 32,

        "progression": "prog_0",

        "next": "loop_0"


The end loop doesn’t require any information except for the audio file. It might look like:

"end": {

        "audio": "end.ogg",


// Progressions

Progressions are what allow the sound effects to harmonize with a loop. You can use the same progression on any number of loops.

Let’s take a simplified example. Let’s say a loop is just a C major chord. You can define a progression that is just C.

Let’s say a loop is 1 measure of C, then 1 measure of F. Your progression would be C/F because a progression divides the time for each step equally.

What if your loop is unequal? Say we have 3 beats in C, and 1 beat in F. Your progression could be C/C/C/F.” The length of the progression is not defined, so if this was applied to a 4 measure loop instead of a 1 measure loop, it would mean 3 measures of C and 1 measure of F.

Progressions are a little more than that in practice because instead of just “C” you actually define a drop group, move group, clear group, and combo group for each step. So an example progression might look like:

"progression_0: [

        ["drop_0", "move_C", "clear_C", "combo_0"],

        ["drop_0", "move_C", "clear_C_alt", "combo_0"],

        ["drop_1", "move_F", "clear_F", "combo_0"],

        ["drop_1", "move_A", "clear_A", "combo_0"]


// Drop Groups

This is the sound that plays when the player’s tetrad lands. I used a deep bass thud in Tessellation and a snap sound in Minimum, but it’s open to your musical inspiration.

Right now you can only specify one drop sound per group, but I may change this to function more like move groups in the future.

The JSON for drop groups looks like this:

"drop_0": "drop.ogg"

// Move Groups

Move groups define the sounds that will play when the player twists or moves the tetrad.

They work kind of like a mini progression within themselves, so you could define a sort of melody or arpeggio as the player plays. You can make this as simple or as complex as you like.

The movement sounds won’t necessarily play in the order you write them, but will play depending on where in the progression the player happens to trigger a sound while playing. The way this happens is through magic and nonsense and no one should attempt to understand it.

The JSON for move groups looks like this:

"move_C": [


















As you can see, you can reuse sounds as much as you need to, even across groups. The game will only load each audio file into memory once, so don’t worry about that.

// Clear Groups

Clear groups define the sounds that will play when the player clears blocks.

Because we want to give feedback when the player clears a lot of blocks, or if they have a really strong combo going, clear groups are made up of 3 sound files. Think of them as a small clear, medium clear, and big clear. The JSON for a clear group looks like this:

"clear_C": [





I’ve been adding notes to make fuller chords for bigger clear sounds, but how you want to use it is up to you. You could use short riffs, or nontonal sound effects, or anything you dream up.

// Combo Groups

Combo groups define the sounds that will play when the player starts a chain reaction and gets multiple sets of clears with one drop. When the board has finally settled, a visual effect and sound will be triggered.

Like clear groups, combo groups are made up of 3 sound files, for small, medium, and big combos. The JSON for a combo group looks like this:

"combo_0": [





// Gain Adjustment

Sometimes you want to adjust your mix after you’ve exported all your sound effects, and you don’t want to have to go back and do it again. The good news is that you can adjust the gain for sounds in the JSON in a section that looks like this:

"gain": {

            "master": 0.7,

            "drop": 0.9,

            "move": 0.5,

            "clear": 1,

            "combo": 0.6,

            "loop": 1


This allows you to lower the volume of sets of sounds, or of the track as a whole, to easily adjust the mix of your song and keep its levels in line with other songs in Mixolumia.

Keep in mind that this number adjusts the gain of sounds linearly. Human perception of sounds is not linear, so a change from 0.1 to 0.2 is going to sound more drastic than a change from 0.9 to 1.0. It’s weird, I know! Just keep it in mind as you adjust, and consider using a percentage to decibel conversion tool online if you need to be precise.

// Song Info

Finally, there’s a place to put the title of the song and the artist name. Simple enough!

"info": {

        "title": "tessellation",

        "author": "davemakes"


Rush mode tracks have an extra field in the song info section. See the Rush mode section in this doc to learn more.

// Cover Art

Cover art for your song is a 96x96 pixel square image called cover.png in the song folder. I suggest using only black and white (1-bit), no grays, or you may see unexpected results in-game. The game will automatically display the album art in the player’s currently selected palette. If the user selects a “light” palette, cover art will be inverted automatically. If you don’t provide a cover, the game will show some default art.

// File Location

Song files are located in the app folder (or on mac, inside the app package) under data/music. Feel free to look at the included song as an example.

If you add a folder with a custom music pack in the music pack directory, it will be added to the sound selection screen. Mixolumia will load custom sound packs when the game starts, and you will be able to use the left and right arrow buttons to choose a song.

The music pack directory on Windows is: %LOCALAPPDATA%/Mixolumia/data/music/

On Mac it should be:

~/Library/Application Support/com.davemakes.mixolumia/data/music


It’s super important to format the JSON right and use {} or [], commas in the right places, and quotation marks correctly. JSON is a pain to read and write but it works really well on the programming side.

I recommend taking a look at the included song to get a feel for how it’s structured. There’s a handy visual JSON editor online that will help you avoid errors, so consider giving that a shot when creating your song.

If your song is breaking in some way, try pasting your JSON into a website that will check it for syntax errors. A missing comma can throw the whole thing off.

// Ogg Vorbis

Ogg Vorbis (.ogg) files are compressed audio files like MP3, but the format is open source. Mixolumia uses this format because it’s what Game Maker Studio 2 supports for streaming audio from outside the game executable.

Your DAW likely doesn’t support exporting to Ogg Vorbis, but there’s a quick way to convert a bunch of WAV files quickly using the free program Audacity. Simply drag your WAV files into an Audacity project and they will be added as separate tracks. Choose File > Export > Export Multiple and set the Format to Ogg Vorbis Files. I set the quality to 3, which seems fine for my purposes, but if your ears are more attuned to audio compression than mine, feel free to experiment.

// Sound Test

It can be difficult and time consuming to test songs in Mixolumia, especially if you’re not an expert player. I highly suggest enabling sound test when building a track. All you have to do is add a line to the game settings file.

The game settings file location on Windows is: %LOCALAPPDATA%/Mixolumia/game_settings.ini

On Mac it should be:

~/Library/Application Support/com.davemakes.mixolumia/game_settings.ini

Open that file and add the line:


You can change this value to “0” and restart the game to disable sound test.

When sound test is enabled, you will see a readout along the left side showing you the name of the current loop, the loop that’s queued to play next, and the current drop/move/clear/combo groups. Along the top is a progress bar showing how long until the next loop will be played.

Sound test also enables a few extra keyboard commands.

If you press enter three times total, the you will reach the end section and the game will conclude.

// Rush Mode

In Mixolumia, there is a game mode called Rush in which the player tries to score as many points as possible in two minutes. This creates a very different musical experience, which is why the Rush song selection is different from other modes.

Rush songs begin from the start section like any other song in Mixolumia, but no other sections are ever triggered by gameplay, and are not required in your JSON file. Progression of a Rush track is based on time instead of clears, and should be designed to reach its climax at the 2 minute mark when the player runs out of time. Your song structure will likely be much more linear than in other modes.

To mark a song so that it is included in the selection of Rush mode music, the song info section of the JSON needs the line “mode”: “rush” added to the info section.

"info": {

"title": "example",

"author": "davemakes",

"mode": "rush"


// Copyrighted Samples

Just a quick note: Be wary of using copyrighted samples for sound effects outside of your loops. It’s a good idea to make sure you’ve transformed them enough that you aren’t doing anything to break the license by redistributing them since they’re essentially just sound files in a folder.

// Distributing Songs

So, you made a song, and want other Mixolumia players to be able to play it! I would love to be able to pay folks for their work and include more songs with the game, and if enough people buy Mixolumia, maybe that dream will come true (please tell your friends about Mixolumia).

However, Mixolumia is set up so that anyone can make and distribute/sell their own songs. Obviously please don’t bundle and redistribute the game itself, that would really hurt my ability to add cool features to Mixolumia and make more games in the future, but any Mixolumia songs you create belong to you and you can do with them as you wish! Nothing would make me happier than seeing fans making money off their musical creations on itch or elsewhere.

As far as the technical side of things, you can distribute your song as a folder, or you can bundle the files as a zip and the game will automatically extract it. The player just needs to drop your song into the music pack directory and it will be available the next time they start the game.

Note: I would like for this process to be easier for players, but I haven’t had time to look into possibilities yet!

// Future Plans

I would like to make a companion app to help generate the JSON files and test songs, but that’s kind of a big investment, and I’m not sure if I’ll have the resources to get to it.

I am open to feedback and ideas, so please let me know if you think of anything.