Using Song Events

This article will explain a bit on how to create and receive song events.

Song events are triggered by the unused effect SFx with S3M and IT modules, or EFx with MOD and XM modules.

Fig 1.1 Song Events in a Pattern

Above is a piece from the final boss music of Super Wings. The SF3 effect is a signal for the boss to dissapear from the screen. The SF8 effects are cues for a fresh batch of laser shurikens to appear :). In the previous pattern, there is an SF2 effect to tell the boss to move to the center of the screen (before dissapearing).

If you are confused, you should go play Super Wings right now!

Handling Song Events

There are two types of events, and they are triggered for both the main module and the jingle.

To receive song events, you must first setup a special callback function. After that you can use the mmSetEventHandler() function.

mm_word myEventHandler(mm_word msg, mm_word param)
{
    switch(msg)
    {
        case MMCB_SONGMESSAGE:
            // Process song message
            break;
        case MMCB_SONGFINISHED:
            // A song has finished playing
    }
}

Use the mmSetEventHandler() function to install your handler. Call this after you have initialized Maxmod.

mmSetEventHandler(myEventHandler);

MMCB_SONGMESSAGE

This is the event that was explained above. The low 4 bits of param will contain the number specified in the pattern effect (ie. param will be 1 for SF1/EF1). The top 4 bits contain the layer that has triggered the effect (MM_MAIN or MM_JINGLE):

mm_byte effect_num = param & 0xF;
mm_layer_type layer = (mm_layer_type)(param >> 4);

MMCB_SONGFINISHED

This is another special event that occurs when the song reaches the END marker. It only happens if you passed MM_PLAY_ONCE to mmStart(). param will contain either 0 or 1. If the main module has ended, it will contain MM_MAIN. If the sub module (jingle) has ended, it will contain MM_JINGLE.

mm_layer_type layer = (mm_layer_type)param;

MMCB_SONGERROR

It's possible that Maxmod detects a problem while playing a specific module. For example, it may be trying to play a module with too many channels, more than the ones allocated for the layer.

Jingles always have 4 available channels. On DS, main modules have 32 available channels. On GBA, the user decides how many channels are available when calling mmInit() or mmInitDefault().

The value of param is the layer that has had the error:

mm_layer_type layer = (mm_layer_type)param;