SFXState Class Reference
[Sound]

A boolean switch used to modify playlist behavior. More...

Inheritance diagram for SFXState:

Public Member Functions
void	activate ()
	Increase the activation count on the state.
void	deactivate ()
	Decrease the activation count on the state.
void	disable ()
	Increase the disabling count of the state.
void	enable ()
	Decrease the disabling count of the state.
bool	isActive ()
	Test whether the state is currently active.
bool	isDisabled ()
	Test whether the state is currently disabled.
Callbacks

void	onActivate ()
	Called when the state goes from inactive to active.
void	onDeactivate ()
	called when the state goes from active to deactive.
Public Attributes
State

SFXState	excludedStates [4]
	States that will automatically be disabled when this state is activated.
SFXState	includedStates [4]
	States that will automatically be activated when this state is activated.

Detailed Description

A boolean switch used to modify playlist behavior.

Sound system states are used to allow playlist controllers to make decisions based on global state. This is useful, for example, to couple audio playback to gameplay state. Certain states may, for example, represent different locations that the listener can be in, like underwater, in open space, or indoors. Other states could represent moods of the current gameplay situation, like, for example, an aggressive mood during combat.

By activating and deactivating sound states according to gameplay state, a set of concurrently running playlists may react and adapt to changes in the game.

Activation and Deactivation

At any time, a given state can be either active or inactive. Calling activate() on a state increases an internal counter and calling deactivate() decreases the counter. Only when the count reaches zero will the state be deactivated.

In addition to the activation count, states also maintain a disabling count. Calling disable() increases this count and calling enable() decreases it. As long as this count is greater than zero, a given state will not be activated even if its activation count is non-zero. Calling disable() on an active state will not only increase the disabling count but also deactivate the state. Calling enable() on a state with a positive activation count will re-activate the state when the disabling count reaches zero.

State Dependencies

By listing other states in in its includedStates and excludedStates fields, a state may automatically trigger the activation or disabling of other states in the sytem when it is activated. This allows to form dependency chains between individual states.

Example:

// State indicating that the listener is submerged.
singleton SFXState( AudioLocationUnderwater )
{
   parentGroup = AudioLocation;
   // AudioStateExclusive is a class defined in the core scripts that will automatically
   // ensure for a state to deactivate all the sibling SFXStates in its parentGroup when it
   // is activated.
   className = "AudioStateExclusive";
};

// State suitable e.g. for combat.
singleton SFXState( AudioMoodAggressive )
{
   parentGroup = AudioMood;
   className = "AudioStateExclusive";
};