A datablock describing a playback pattern of sounds.
- Inherit:
SFXTrack
Playlists allow to define intricate playback patterns of invidual tracks and thus allow the sound system to be easily used for playing multiple sounds in single operations.
As playlists are SFXTracks, they can thus be used anywhere in the engine where sound data can be assigned.
Each playlist can hold a maximum of 16 tracks. Longer playlists may be constructed by cascading lists, i.e. by creating a playlist that references other playlists.
Processing of a single playlist slot progresses in a fixed set of steps that are invariably iterated through for each slot (except the slot is assigned a state and its state is deactivated; in this case, the controller will exit out of the slot directly):
- delayIn: Waits a set amount of time before processing the slot. This is 0 by default and is determined by the delayTimeIn (seconds to wait) and delayTimeInVariance (bounds on randomization) properties.
- transitionIn: Decides what to do before playing the slot. Defaults to None which makes this stage a no-operation. Alternatively, the slot can be configured to wait for playback of other slots to finish (Wait and WaitAll) or to stop playback of other slots (Stop and StopAll). Note that Wait and Stop always refer to the source that was last started by the list.
- play: Finally, the track attached to the slot is played. However, this will only start playback of the track and then immediately move on to the next stage. It will not wait for the track to finish playing. Note also that depending on the replay setting for the slot, this stage may pick up a source that is already playing on the slot rather than starting a new one. Several slot properties (fade times, min/max distance, and volume/pitch scale) are used in this stage.
- delayOut: Waits a set amount of time before transitioning out of the slot. This works the same as delayIn and is set to 0 by default (i.e. no delay).
- transitionOut: Decides what to do after playing the slot. This works like transitionIn.
This is a key difference to playlists in normal music players where upon reaching a certain slot, the slot will immediately play and the player then wait for playback to finish before moving on to the next slot.
Note
Be aware that time limits set on slot delays are soft limits. The sound system updates sound sources in discrete (and equally system update frequency dependent) intervals which thus determines the granularity at which time-outs can be handled.
For greater variety, many of the values for individual slots may be given a randomization limit that will trigger a dynamic variance of the specified base value.
Any given field xyz that may be randomized has a corresponding field xyzVariance which is a two-dimensional vector. The first number specifies the greatest value that may be subtracted from the given base value (i.e. the xyz field) whereas the second number specifies the greatest value that may be added to the base value. Between these two limits, a random number is generated.
The default variance settings of "0 0" will thus not allow to add or subtract anything from the base value and effectively disable randomization.
Randomization is re-evaluated on each cycle through a list.
A unique aspect of playlists is that they allow their playback to be tied to the changing set of active sound states. This feature enables playlists to basically connect to an extensible state machine that can be leveraged by the game code to signal a multitude of different gameplay states with the audio system then automatically reacting to state transitions.
Playlists react to states in three ways:
- Before a controller starts processing a slot it checks whether the slot is assigned a state. If this is the case, the controller checks whether the particular state is active. If it is not, the entire slot is skipped. If it is, the controller goes on to process the slot.
- If a controller is in one of the delay stages for a slot that has a state assigned and the state is deactivated, the controller will stop the delay and skip any of the remaining processing stages for the slot.
- Once the play stage has been processed for a slot that has a state assigned, the slot's stateMode will determine what happens with the playing sound source if the slot's state is deactivated while the sound is still playing.
A simple example of how to make use of states in combination with playlists would be to set up a playlist for background music that reacts to the mood of the current gameplay situation. For example, during combat, tenser music could play than during normal exploration. To set this up, different SFXStates would represent different moods in the game and the background music playlist would have one slot set up for each such mood. By making use of volume fades and the PauseWhenDeactivatedstateMode, smooth transitions between the various audio tracks can be produced.
Example:
// Create a play list from two SFXProfiles.
%playList = newSFXPlayList()
{
// Use a looped description so the list playback will loop.description = AudioMusicLoop2D;
track[ 0 ] = Profile1;
track[ 1 ] = Profile2;
};
// Play the list.sfxPlayOnce( %playList );