The Wintermute Engine provides various music related functions. All of them are exposed as methods of the Game object. See the Script language reference for a detailed description of each method.
The most important is probably the Game.PlayMusic() method. You pass it a sound file (Wav or Ogg), and specify if the music should loop or not.
For example:
Game.PlayMusic("music\MyMusic.ogg", true);
|
The above line tells WME to play the MyMusic.ogg file and that it should start over once the music finishes.
But since it's not always easy for the musician to achieve a seamless transition when the music starts over, the PlayMusic() has a third optional parameter, which specifies the point from which the music should start when looping. This point is specified in milliseconds:
Game.PlayMusic("music\MyMusic.ogg", true, 6890);
|
This command will play the MyMusic.ogg file, but once the playback reaches the end of the file, it skips to 6890 milliseconds from the beginning.
There are many other music functions but their names are usually self-describing like Game.StopMusic(), Game.GetMusicPosition() etc. See the Game object scripting reference for a complete list with a detailed description.
You will usually put the Game.PlayMusic call to the scene_init.script of the scene where your music should start to play.
While the standard set of functions described in the previous article is able to work with a single music channel, WME provides a second set of functions, allowing you to work with multiple music channels. WME supports up to 5 music channels numbered 0 - 4.
The multi-channel music methods have similar names as their single-channel counterparts, but the word "Music" is replaced by the word MusicChannel. For example there are two methods for playing the music:
All the multi-channel music functions take a channel number as the first parameter. The channel number can be a number in range from 0 to 4. On the other hand, the single-channel methods operate always on channel 0.
Again, see the Game object scripting reference for a detailed description of both single-channel and multi-channel music methods.
The multi-channel music support comes with the ability to cross-fade two music channels. WME has a Game.MusicCrossfade() for this purpose. You need to tell this method what two channels you want to cross-fade, and how long should the cross-fade take. You can also specify, if the two channels should be swapped after the cross-fading is over. This is useful to always hold the main melody in the same channel.
This is the typical scenario of using the music cross-fading. You'll start the first channel playback somewhere, usually at the scene entry, i.e. in the scene_init.script:
Game.PlayMusicChannel(0, "music\FirstChannel.ogg", true); |
The music is now playing at channel 0. Now, once some event happens, we want the music to seamlessly cross-fade to other tune. What we need to do is to start playback in other channel and call the MusicCrossfade method:
Game.PlayMusicChannel(1, "music\SecondChannel.ogg"); Game.MusicCrossfade(0, 1, 3000); |
Those two lines will start the playback in the channel 1 and will initiate the cross-fade. The cross-fading will take three seconds and once it's over, the channels will be swapped, i.e. you still have the main music playing in channel 0, only the music file is now different.
Sometimes you may want to start the second channel not from the beginning, but from a certain point. In that case you'd call the Game.SetMusicChannelPosition method first:
Game.SetMusicChannelPosition(1, 10000); Game.PlayMusicChannel(1, "music\SecondChannel.ogg"); Game.MusicCrossfade(0, 1, 3000); |