 |
TurtleBrains
0.3.5
High quality, portable, C++ framework for rapid 2D game development.
|
|
|
TurtleBrains
0.3.5
High quality, portable, C++ framework for rapid 2D game development.
|
|
Video games may imply visuals quite readily but audio is also required. Sound effecs and music can make and break the game, and adding these effects should be as simple as possible. From code alone play a sound by creating it first then playing it. Do not forget to destroy it later when it is no longer needed.
{
//Initialize.
AudioHandle castleGateOpen = TurtleBrains::Audio::theAudioManager.CreateSoundFromFile("data/audio/castle/gate_open.wav");
//Use where needed.
TurtleBrains::Audio::PlaySound(castleGateOpen);
//Perform cleanup.
TurtleBrains::Audio::theAudioManager.DestroySound(castleGateOpen);
}
PlaySound returns an TurtleBrains::Audio::AudioController which allows the audio to be paused, stopped or adjusted. This controller object is how you would stop a looping audio effect from playing endlessly.
{
//Put this in your class.
TurtleBrains::Audio::AudioController mController;
//Initialize the object's audio controller when necessary. The audio start playing, and looping, here.
mController = TurtleBrains::Audio::theAudioManager.PlayEvent("castle_events", "blacksmith_loop");
//When the player goes away from the blacksmith area, Pause, or Stop, the loop depending if you want the audio to resume or restart on Play().
controller.Pause();
//When the player comes into the blacksmith area, Play the audio again!
controller.Play(true)
}
Playing sounds programmatically is nice an all, but the real power comes with the data driven audio event tables. As of v0.3.1 .json is the only supported format, though there is no reason similar structured formats like .xml or .yml, could be used in the future.
The most basic audio event has a name, unique to the table, and a source that contains the path of the audio file, relative to executable working directory. Specifying the version is highly recommended as a warning will show if the format does not match current loader. Below is an example event table of sounds found in a castle environment including some music and looping effects:
{
"version":2,
"audio_events":[
{ "name":"gate_open", "source":"data/gate_open.wav" },
{ "name":"gate_close", "source":"data/gate_closing.wav" },
{ "name":"pig_grunt", "source":"data/pig_grunt.wav" },
{ "name":"blacksmith_loop", "source":"data/blacksmith.wav", "looping":true },
{ "name":"festival_music", "source":"data/castle_festival.ogg", "looping":true, "music":true }
]
}
To use this event table in code, first load it into the TurtleBrains::Audio::AudioManager:
TurtleBrains::Audio::theAudioManager.LoadEventTable("castle_events", "data/castle_events.json");
Once loaded any of these events can be played by easily refering to the table and event by name, and just like the PlaySound() function, an TurtleBrains::Audio::AudioController will be returned for more control of the effect:
TurtleBrains::Audio::theAudioManager.PlayEvent("castle_events", "gate_open");
As seen above a bit more than just the filepath can be specified for an event. Shown already is a flag for looping audio and one for marking music peices, but there is a lot more power in the data. Consider if gate_closing.wav was twice as loud as other effects and modifying the audio was a time consuming option, or not available at all. This can be quickly changed by adding volume:0.5 to the gate_close event description:
{ "name":"gate_close", "file":"data/gate_closing.wav", "volume":0.5 },
Now when gate_close event is played in the game, it will automatically be at half volume and match the volume of the other effects.
The event really shines when it comes to playing an audio effect that occurs very often. It is good to add variation to these types of effects and the event description allows for some randomization each time it plays:
{
"name":"pig_grunt",
"source":"data/pig_grunt.wav",
"min_volume":0.8, "max_volume":1.0,
"min_pitch":0.85, "max_pitch":1.2
}
Now when PlayEvent("castle_events", "pig_grunt") is called the volume it plays will be randomized as will the pitch so it will sound slightly different every time. The event descriptor can take this two steps further by allowing multiple sources to be added to an event and each source can even have volume and pitch configured differently from other sources or the event, though it takes the event settings by default. In the following example, the pig_grunt_fast source would always have volume of 0.5 while source of pig_grunt_slow would randomize between 0.8 and 1.0.
More information about the value ranges for volume and pitch can be found in TurtleBrains::Audio::AudioController::SetVolume() and TurtleBrains::Audio::AudioController::SetPitch().
{
"name":"pig_grunt",
"volume":0.5,
"source":[
"data/pig_grunt.wav",
"data/pig_grunting1.wav",
{ "file":"data/pig_grunt_fast.wav" },
{
"file":"data/pig_grunt_slow.wav",
"min_volume":0.8, "max_volume":1.0,
"min_pitch":0.85, "max_pitch":1.2
},
"data/pig_grunting2.wav"
]
}
Finally in some cases the path to the audio data may be fairly deep and or not change for many sources. An optional root_path value can be specified in the format that will get prepended to all sources as they get loaded.
{
"version":2,
"root_path":"data/audio/castles/greveholm/",
"audio_events":[
{ "name":"gate_open", "source":"gate_open.wav" },
{ "name":"gate_close", "source":"gate_closing.wav" },
...
]
}
If you have long musical events it can be handy to stream the decompression from disk instead of loading entire file into a buffer to reduce memory. To do this simply add the streaming flag to the event description and set it to true. As of v0.3.1 streaming is only supported on audio compressed in the .ogg format. A .wav formatted audio data will trigger an error condition.
{ "name":"festival_music", "source":"data/castle_festival.ogg", "looping":true, "music":true, "streaming":true }
Current TurtleBrains supports the following formats:
1.8.9.1