Table of Contents

Integration Details - States

Introduction

A state is a change that affects the audio properties on a global scale for all game objects. For every state group there can only be one current state, which is shared between all game objects.

For example, a state group could be:

  • Weather

And the different states of this group could be:

  • Sunny
  • Rainy
  • Cloudy
  • None
Note.gif
Note: Every state group has a state called "None". The "None" state represents the initial state of the group, and cannot be removed. In the "None" state, no parameter changes have been applied.

The State System

The state system is a powerful tool that can be used in many ways. It allows you to modify multiple parameters at a time for various objects (sounds, actor-mixers, busses, and so on). You can change the behavior of everything that is going on in the Sound Engine with one single command. However, while states are versatile, they are not the optimal solution for every situation. For example, consider a situation where quick parameter updates are needed for one single parameter for a small number of objects. In this case, using RTPC will be less resource-heavy and faster than using states.

Using the State System

Setting a state from the SDK is as simple as calling:

AK::SoundEngine::SetState( L"Weather", L"Sunny" );

or

AK::SoundEngine::SetState( AK::STATES::WEATHER::GROUP, AK::STATES::WEATHER::STATE::SUNNY );

Identifying States

There are two ways to set a state from the SDK: using strings (Unicode or Ansi) or using IDs.

Using strings makes code more readable and is suitable during development time, or when working in an environment that normally uses strings. Using IDs avoids Wwise from having to hash the names at runtime.

Enabling ID Usage

To work with IDs, select the "Generate header file" option in the Wwise Generate SoundBanks dialog box. The definition file, named Wwise_IDs.h, contains all the required IDs. It is updated at each bank generation.

For an example of a header file, refer to Integration Details - Banks.

Caution.gif
Caution: When working with IDs, it is important to keep the .h file up-to-date when new banks are generated. Otherwise, ID mismatches and/or compilation errors may occur.

For more information on generating banks with Wwise, refer to the Wwise Help.

Driving States

You have two options to drive states: The SDK AK::SoundEngine::SetState() function, and the action "SetState" generated in Wwise. However, using both at once in the same state is problematic. For example, if sound designers introduce SetState actions inside the events they create while audio developers drive states using the SDK AK::SoundEngine::SetState() function, the states may become difficult to control. We strongly recommend that sound designers and audio developers decide how the actual states will be driven, either for each state group or for the entire project. Both ways can be used at once, if there is agreement on how states will change. For example, the audio developers can initialize states using the SDK SetState() function, but leave the state to be driven by events for the rest of the game.

Tip.gif
Tip: If a state behavior is the same for many sounds, you can give those sounds a common parent (such as an actor-mixer) and put the state settings there, instead of duplicating them in each sound. This will make it faster for the sound designer to edit settings. It will also reduce the memory required for storing state parameters, since they will be stored in one place instead of many.

State Transitions

When a state change is triggered, if transitions have been defined, the transition from Parameter Value A to Parameter Value B will begin. A default transition time is applied to all parameters. Transition times can be defined in Wwise.

If the transition time is set to zero (that is, there is no transition time), there is no transition and the parameter value jumps directly to the target value. If the presence of a transition does not make the game sound better, the transition should be set to zero to save transition resources.

If a second state change is triggered while the previous state is still in transition, the new parameters will define the new target and the parameter will transit from the current value to the new target value using the new transition time. If a transition is interrupted, the current value will transit to the previous value. For example, if a state change to State 1 interrupts a transition from State 1 to State 2, the values change from their current settings back to State 1 using the new transition time.

SoundEngineStates_TransitionInterruption.gif

State transition time is ignored for Boolean type parameters, and for state-driving switch containers. Switch containers have their own options that drive what happens on state or switch changes.

For an example of integrating states, refer to State Example.

See also:
Concept: States, Integration Details - Game Objects, Integration Details - Switches, AK::SoundEngine::SetState()