About sound and music
Like any game engine, DizzyAGE supports both sound effects and music.
Sound effects, also called sound samples, are usually small sounds, played during the game, when various events happen.
From small beeps played when game menus pop up, to cracks, bangs and expolsions, they are all sound effects.
Musics are usually long songs, played during the game as ambiental music.
They can be changed to reflect the game's or the room's mood, but in DizzyAGE games, only one music can play at a time.
An important difference between sound effects and music, is that sound effects are small (a few seconds) and they are fully loaded in the computer's memory, by the game's engine.
The music, on the other hand, can be quite long (even up to 5 or 10 minutes) and the engine is streaming it from the hard disk, bit by bit.
So don't try to use one of these long music files as a sound effect because it will take forever to load and you will run out of memory.
If you make a Dizzy game in the classic Z80 style, you may also want to have a suitable music and specific sound effects.
The Z80 computer doesn't have a sound card, like today's PCs capable of high quality music. It is only using a small cip that can produce
a variety of beeps. But, used by skilled people, this cip can produce wonderful tunes. In fact, it could be quite strange to mix
the classic Z80 graphics and the high CD quality music.
If you go for a more colorfull Dizzy game, you may want to use other kind of music, more suitable for PC games.
DizzyAGE supports a variety of audio file formats.
Sound effects files must be placed in the DATA/SAMPLES folder.
The file names must begin with a numeric id, followed by a space character and a symbolic name.
The id must be unique among them and it is used to access the sound and play it from the scripts.
The file name can also specify the maximum number of instances of the sound, that can be played at once.
It must be added after the symbolic name and separated by a space character. If not specified, this number will be 1,
meaning that the sound will not play if it's already playing. Using more instances for a sound consumes more memory,
but can be usefull for fast repetitive sounds, like water drops.
The engine loads all the sound files found in the samples folder.
Example of sound files:
5 coin 2.ym
The recommended audio format for sound effects is OGG or YM.
OGG files are similar to MP3 files, or to WAV files, but they are compressed.
The YM files store original Z80 audio, so they can be a right chioce for Z80 style games.
Only small length (usually less than 10sec) sounds should be used as sound effects.
Music files must be placed in the DATA/MUSIC folder.
Their file names must begin with a numeric id, followed by a space character and a small name.
The id must be unique among them and it is used to access the music and play it from the scripts.
The engine loads all the music files found in the music folder.
Example of music files:
The recomended audio format for music is YM for Z80 style games,
MOD, IT, XM or S3M for PC style games and
OGG for high CD quality music.
- normal wave files uncompressed, containing digital sound.
- can be used as sound effects, if small, or as music if bigger.
- it is possible to convert any sound format to WAV.
- digital sound compressed using OggVorbis library.
- are equivalent to the MP3 format (which is not supported by DizzyAGE)
- for details on OGG files, see http://www.vorbis.com
- when used for sound effects, OGG files are decompressed into memory.
- it is possible to convert from WAV or MP3 to OGG
The advantage of OGG files is that they are well compressed, and they can store any kind of digital sound. Even voice.
You can do the same with WAV files, but, since WAV files are not compressed, the size of your game's data will get pretty huge.
You can convert from any audio format to WAV and then compress it to OGG.
- are emulated Z80 sound files, somehow similar to MIDI files.
- very small in size, very suitable for original Dizzy tunes.
- YM files are played by DizzyAGE using the StSoundLibrary by Arnaud Carré
- for details on YM files check http://leonard.oxg.free.fr
- there is also possible to create YM from AY files, another popular Z80 format.
- for details on AY files check http://bulba.at.kz
You can't convert from other formats to YM, except from AY format.
MOD, IT, XM, S3M
- tracked music files played by DizzyAGE using the DUMB library by Ben Davis.
- for more details on DUMB, check http://dumb.sourceforge.net
- these files are pretty small in size and they are very popular.
The MOD, IT, XM and S3M are somehow equivalent formats and you should be able to convert between any of them.
Of course you can convert them to WAV and then OGG, but you can't convert to them from other formats.
You can download free sounds and music from the internet.
Playing sound effects
Start from the default template data and add an action object, for example Grand Dizzy.
Write an action callback for him as follows.
Run the game and try to talk with him. You can hear the success sound.
The FX_SUCCESS is defined in the sound.gs file as 1, represents the sample's id and it corresponds to the 1 success.ym file found in the DATA/SAMPLES folder.
As you add more sound files, you can add specific defines for them, to use them through the scripts and to
make the code more easy to read.
SamplePlay( id [,loop] )|
It plays the sound effect with the specified id and returns a voice index on which this sound is played.
The engine supports a total of 16 voices, meaning there can be up to 16 sounds effects playing at once.
If there are no more voices available, or if there are enough instances of this sound already playing,
-1 will be returned and the sound will not be played.
The loop parameter is optional. It's default value, if not specified, is 0, meaning the sound will be stopped after reaching it's end.
If loop is 1, the sound will be looped, played over and over, until stopped by the user. Like an engine sound.
SamplePlaying( voiceidx )
This tells if a voice is busy playing a sound and returns the id of the sound, or -1 if the voice is available (free).
SampleStop( voiceidx )
This stops the sound playing on a specified voice, making the voice available for other sounds.
This stops all the voices at once.
SampleVolume( percent )
This will change the sound effects volume to a given percent 0=silent, 100=very loud.
When playing sounds, you must always consider that the player could disable the audio from the game's setup.
In this case, all SamplePlay calls will return -1, because no sounds are loaded and the id is not found.
So, do not depend on a sound you have played, like to wait until it ends. If you do have to wait for a sound to finish playing,
use a latent wait function and delay a few seconds, as the approximate sound's length.
Script the audio part of the game like an optional feature, allowing people to play the game with no sound if they want or must to.
DizzyAGE supports a single music playing at a time.
This music can be changed during gameplay and fade options can be used to smoth the transit.
The default template deals with storing the current playing music in the saved game
and it also plays it back, from where it was left, when the game is loaded.
And so it does when Dizzy is respawned at a safe location, after he died.
This may be important, because, in the room with the last safe location, other music could be playing, than
the music from the room where he died. Imagine a long fall from a top of a cliff, down into the water below.
The idea is that you don't have to deal with these things anymore, you just request your music to be played wherever you want.
In the previous example, add the folowing room callbacks. Move from room to room and see how the music changes.
Observe the difference between the fade options.
Like for the sound effects, it is recommended you use well named defines for your musics, for clarity of the scripts.
MusicPlay( id [,position] )|
It plays the specified music file, from an optional position given in miliseconds (1sec=1000ms).
If no starting position is specified, the music will start from the begining (0).
If playing fails, due to wrong id or audio disabled, -1 is returned. If everything is fine, 0 is returned.
You can request to play an invaid id music (-1), to benefit of a fade out for the current playing music, until it stops.
This returns the id of the current playing music, or -1 if no music is playing at the moment.
This returns the position in miliseconds of the current playing music, or -1 if no music is playing.
This stops the current playing music and it does that immediately, without fading options.
MusicVolume( percent )
This changes the music volume to a given percent 0=silent, 100=very loud.
MusicFade( fadeout, fadein )
This sets the fading options in seconds.
When the music is changed, it fades out in fadeout seconds and only then, the engine plays the new requested music, also applaying a fade effect during the first fadein seconds.
If fadein and fadeout are set to 0, the music will stop and start immediately.
Even if the old music is fading out, the engine considers the new requested music to be current.
Coding the music for a game can be as simple as playing a single music during the whole game, or changeing it now and then, when entering specific rooms.
But it can also be a complex thing, takeing a lot of aspects in consideration. Like having a few songs playing one after another in a special order.
DizzyAGE supports this through a special handler, HandlerMusicLoop(), that is called by the engine when a song is about to loop from the begining and it can
be used to start another music, in any relation with the one already playing, or with the map area where the player is.
Add other sound effect and music files to the game's data, and play them during the game.
You can use any resources you want, and you can use specific tools to do the audio format conversions, if necessary.
To learn more about sound samples and music, read the related reference chapters:
Engine exported sample functions
Engine exported music functions