Getting started with Modipulate

As you'll see, using Modipulate is pretty simple in most cases. If you're new to programing or currently battling werewolves you may think otherwise (tip: use the silver axe.)

Let's get this party started

Before we do anything else, we need to initialize Modipulate.

modipulate_global_init();

Likewise, you can close Modipulate with modipulate_global_deinit()

Here's how to load your awesome new module into a ModipulateSong and press play:

ModipulateSong song;
modipulate_song_load("myAwesomeModule.it", &song);
modipulate_song_play(song, 1); // 1 is play, 0 is pause

A word on error checking

Many methods return a ModipulateErr value. Nothing is wrong if the value is MODIPULATE_ERROR_NONE, You can check for that case easily with the MODIPULATE_OK() macro.

If an error occurs, you can get the error string with modipulate_global_get_last_error_string() and save it to your game's error log method.

Here's an example of how you might handle an error:

if (!MODIPULATE_OK( modipulate_global_init() )) {
    logError( modipulate_global_get_last_error_string() );
    
    return;
} 

Callback model

Modipulate uses a callback model to send music data to your game. Here's a simple example where we print out notes playing on channel 3.

Here's your callback method:

void on_note(ModipulateSong song, unsigned channel, int note,
    int instrument, int sample, int volume_command, int volume_value,
    int effect_command, int effect_value, void* user_data)
{
    if (channel == 3)
        std::cout << "Note " << note << " played on channel 3" << std::endl;
}

To use the on_note() function defined above, set the note callback. You generally want to do this right after loading a song and before playing it.

modipulate_song_on_note(song, on_note, NULL);

Don't skip this next part, it's important!

For performance and thread safety all callbacks are triggered from your game's context, not the audio thread context. You must trigger the callbacks manually by calling modipulate_global_update(). Here's a simple example:

// Game loop
while(true) {
    modipulate_global_update();
    
    // Your code here.
}

The callbacks are sent in a predetermined order, which is yet to be documented.

Other sources of help

Modipulate includes several open source examples in C and other languages.

The full Modipulate C API documentation is online.