Working with Audio in ACE on Amiga
Amiga C Engine aka ACE is a game engine / framework / support library written totally in C for classic Amiga hardware.
ACE provides audio capabilities through integrated PTPlayer by Frank Wille rewritten to C for better integration with ACE features. The basic capabilities are:
- MOD music playback (31-sample format)
- Handling prioritized sound effects playback
- Offers channel management (reserving channels for music vs. effects)
- 64-step volume control
- Custom callback for song end, e.g. for playlists or adaptative music
You can also combine it with 3rd party audio mixers for squeezing out more out of the audio playback.
Amiga-Specific Considerations
- PTPlayer must store music samples as well as sound effects in Amiga's CHIP memory.
- PTPlayer sound effects should have an empty first word to prevent audio glitches after playback - audio_conv can ensure that for you
- Amiga has 8-bit audio channels, totaling to 4 channels, two bound to left channel, two bound to the right one.
- It's quite common to games to ignore the stereo separation and treat them all as mono, leaving to the user to ensure such playback.
Initialization and Configuration
In your main or gamestate create function, do the following:
// Initialize (1 = PAL mode, 0 = NTSC)
ptplayerCreate(1);
// Optional: Configure which channels are reserved for music
ptplayerSetMusicChannelMask(0b0011); // Reserves channels 0 and 1 for music
// Optional: Set master volume
ptplayerSetMasterVolume(48); // Range is 0-64
// Optional: Configure song repeat behavior
ptplayerConfigureSongRepeat(1, onSongEnd);
To play the music in your game, in your main or gamestate create function:
// Load a MOD file
tPtplayerMod *pMod = ptplayerModCreateFromPath("music.mod");
// Start playback (2nd parameter is NULL to use samples from inside the MOD file, set start position to 0)
ptplayerLoadMod(pMod, NULL, 0);
// Enable music playback
ptplayerEnableMusic(1);
While in the game loop, you might want to:
- change the music by calling ptplayerLoadMod() with different pMod,
- change the volume with ptplayerSetMasterVolume()
- enable/disable music temporarily with ptplayerEnableMusic()
At the end of the gamestage or the game itself, do the following:
ptplayerStop();
ptplayerModDestroy(pMod);
// When done with all audio
ptplayerDestroy();
Playback performance will vary depending on:
- Number of channels used in the song
- Amount/kinds of ProTracker commands stored in the song.
Playing Sound Effects
To load a sound effect, be sure to have a .sfx file generated by audio_conv tool.
Manage the sound effect by calling:
tPtplayerSfx *pSfx = ptplayerSfxCreateFromPath("explosion.sfx", 0);
// When done with the sound effect, after your game loop ends:
ptplayerSfxDestroy(pSfx);
To play the sound effect:
ptplayerSfxPlay(pSfx, PTPLAYER_SFX_CHANNEL_ANY, PTPLAYER_VOLUME_MAX, 10);
You can also set the specific channel, as well as set the sound effect priority. When using PTPLAYER_SFX_CHANNEL_ANY, PTPlayer will use any free channel, if possible.
Higher priority sound effects will replace lower priority ones if needed.<You can also stop the sound effects playing on given channel by calling ptplayerSfxStopOnChannel().
Advanced Features
- PTPlayer supports ProTracker's E8 command for synchronizing game events with music. Use ptplayerGetE8() to retrieve the last E8 value.
- You can use mod_tool to separate MOD files from their sample data using sample packs to save memory when using multiple songs with shared samples. Use ptplayerSampleDataCreateFromPath() to load the sample pack and pass it in 2nd parameter of ptplayerLoadMod().
- You can adjust individual music sample volumes with ptplayerSetSampleVolume() even when music is playing.
Find more guides at github
Back to table of contents
