Using Wwise Components In Unity

Most Wwise SDK functions are available in Unity through the AkSoundEngine class. Think of it as the replacement of C++ namespaces AK::SoundEngine, AK::MusicEngine, and so on. See API Changes and Limitations for changes made in the API binding compared to the original SDK.

This integration provides a few components that can be used without code directly in a scene for the most frequent usage scenarios:

• AkAmbient
  Use this component to attach a Wwise Event to any object in a scene. The sound can be started at various moments, dependent on the selected Unity trigger. This component is more useful for ambient sounds (sounds related to scene-bound objects) but could also be used for other purposes. . See How to use AkEvent and AkAmbient with the inspector.
  
• AkAudioListener
  Add this script on the game object that represent an audio listener. It will track its position in Wwise. This is normally added to the Camera object or the Player object.
  
• AkBank
  Loads and unloads a soundbank at the specified moment.
  
• AkEnvironment
  Use this component to define a reverb zone. This needs to be added to a collider object to work properly. . See How to use AkEvironment and AkEvironmentPortal with the inspector (Reverb Zones).
  
• AkEnvironmentPortal
  Use this component to define an area that straddles two different AkEnvironments zones and allow mixing between both zones.
  • How to use AkEvironment and AkEvironmentPortal with the inspector (Reverb Zones).
  See How to use AkEvironment and AkEvironmentPortal with the inspector (Reverb Zones).
  
• AkEvent
  Helper class that knows a Wwise Event and when to trigger it in Unity. See How to use AkEvent and AkAmbient with the inspector.
  
• AkGameObj
  This component represents a sound emitter in your scene. It will track its position and other game syncs such as Switches, RTPC and environment values. You can add this to any object that will emit sound. Note that if it is not present, Wwise will add it automatically, with the default values, to any Unity Game Object that is passed to Wwise API (see AkSoundEngine.cs).
  
• AkState
  This will call AK::SoundEngine::SetState whenever the selected Unity event is triggered. For example this component could be set on a Unity collider to trigger when an object enters it.
  
• AkSwitch
  This will call AK::SoundEngine::SetSwitch whenever the selected Unity event is triggered. For example this component could be set on a Unity collider to trigger when an object enters it.
  

See also:

Wwise Picker

How to add a Wwise sound to a game object

There are three ways to add sounds to your game:

• Using the Wwise Picker. This is the simplest way to add a sound to an object. Drag an Event from the Wwise Picker window to an object in the Unity Viewer or the Inspector. This automatically creates an AkAmbient component on the target Game Object.
• Using the Add Component menu. Add an AkAmbient or an AkEvent component to any Unity Game Object.
• Using scripts. Call AK::SoundEngine::PostEvent() at any time from a C# script.

How to use AkEvent and AkAmbient with the inspector

• AkEvent:
  • Trigger On:
    Provides a list of Unity events that can trigger your event. You are not limited to those events. You can trigger an event at any time by calling AkSoundEngine.PostEvent anywhere in your code. You can also code your own triggers, so they appear in the list for your co-workers. See Adding new triggers for Wwise events.
  • Action On Event:
    Enables users to override some event parameters defined in Wwise directly from Unity. This allows the reuse of existing events insted of creating new ones.
    
    • Action On Event Type:
      Overrides the event type.
    • Curve Interpolation:
      Overrides the interpolation curve.
    • Fade Time:
      Overrides the sound's fade time.
  • Use Callback:
    Provides an easy way to make a game object react to an event callback.
    • Game Object:
      The game object that will receive the callback. To select a game object, drag it from the hierarchy and drop it in the game object field.
    • Callback Function:
      This is the function that will get called by Game Object when the callback happens. To select a function, type its name in the Callback Function text field.
      For this to work, Game Object must define Callback Function in one of its components.
      The function's definition must be void FunctionName(AkEventCallbackInfo in_info).
    • Callback Flags:
      Select a flag which specifies when Callback Function will be called. More than one flag can be selected at the same time. See the AkCallbackType enumeration in the Wwise SDK documentation for more information about each flag.
  • Event Name:
    Specifies the name of the current event. To select an event, click on the current event's name to open the event picker window. Then, you can either click on an event and click on the Ok button or double click an event to select it. You can also drag an event from the Wwise picker and drop it on the current event's name to select a new one.
    

• AkAmbient:
  AkAmbient inherits all the functionalities of AkEvent and adds the following ones:
  • Position Type:
    Defines the way the event's position will be sent to the audio engine.
    • Simple_Mode:
      The event's position will be the same as the game object to which it's attached.
    • Large_Mode:
      The event can have multiple positions that are defined by a set of points. You can add a point by clicking the Add button in the AkAmbient Tool Bar. You can then move each point by dragging it around. This mode is useful when a sound is coming from multiple positions at the same time. The sound of water in the middle of the ocean is a good example.
    • MultiPosition_Mode:
      This mode enables us to have only one instance of a sound for all instances of AkAmbient using the same event in order to save memory.
      All AkAmbient instances that are using this mode and that have the same event will automatically get detected and the same sound instance will be used for all of them insted of loading the same sound multiple times.
      Note that all AkAmbient instances in this mode and with the same event will have the same trigger (see Trigger On in AkEvent). So, changing the trigger of one AkAmbient will automatically change the trigger of all the others with the same event.
  • Show Attenuation Sphere:
    Shows a sphere that defines the space where the sound played by an event can be heard.
    For this to work you need to enable Max Attenuation in the SoundBank settings in your Wwise project (Project->Project Settings->Soundbanks->Max attenuation)
    
    • Dont_Show:
      No attenuation sphere is shown.
    • Current_Event_Only:
      Shows the attenuation spheres for all the sounds that would be played after a call to AkSoundEngine.PostEvent while in the current mode.
      If in Simple_Mode, then only the attenuation sphere of the sound coming from the game object is shown.
      if in Large_Mode, then an attenuation sphere is shown for each point.
      If in MultiPosition_Mode, then an attenuation sphere is shown for every other AkAmbient in MultiPosition_Mode with the same event.
    • All_Events:
      Shows the attenuation sphere of all AkAmbient instances in the scene.

How to use AkEvironment and AkEvironmentPortal with the inspector (Reverb Zones)

In Wwise, Reverb Zones are called Environment or Auxiliary Sends. Reverb Zones are not limited to being reverb effects and are defined in the Wwise project. Conceptually, all sound emitters inside an environment are affected by some amount of the AK::SoundEngine::SetGameObjectAuxSendValues send that the game must pass to Wwise.

An AkEnvironment component embodies a very simple environment zone. You can attach an AkEnvironment to any type of collider. To add an AkEnvironment to your scene:

• Using the Wwise Picker. This is the simplest way to add an AkEnvironment. Drag an AuxBus from the Wwise Picker window to an object in the Unity Viewer or the Inspector. This will automatically create an AkEnvironment component on the target Game Object.
• Using the "Add Component" menu. Add an AkEnvironment component to any Unity Game Object. Select the desired environment from the selector in the inspector.
• Using scripts. You can call AK::SoundEngine::SetGameObjectAuxSendValues() at any time from a C# script.

We also have portals which can be used to combine the effects of two environments. The contribution of each of the two environments is relative to their distance from the game object.
This is useful if a game object is standing between two rooms or in a tunnel connecting two environments.

• To add an environment portal to your project, go to GameObject->Wwise->Environment Portal in Unity's menu bar.

To use environments and environment portals, you need a game object with an AkGameObj component that is environment-aware.
AkEnvironmentPortal objects will automatically detect AkEnvironment objects that overlap it. The overlapping environments will appear in the two select-lists in the portal's inspector. If too many environments overlap the portal, you can select which ones the portal will mix together.

In Wwise, only 4 environments can be active at the same time. Those 4 environments are selected as follows:

• The environments that are connected to a portal and that have the highest priority are selected until we reach 4 environments or until there are no more environments connected to a portal.
• If we still don't have 4 selected environments, we select the environments that are not connected to a portal as follows:
  • Environments with the highest priority will be selected until we reach 4 environments (if the Default and Exclude Others flags are not set).
  • A Default environment will be selected only if no other environment is selected.
  • If your game object is inside an environment with the Exclude Others flag, then it will be selected and all other environments will get discarded.
    

• AkEnvironment component:
  Only 4 environments can be active at the same time.
  • Priority:
    Defines the priority of an environment.
    A smaller number has a higher priority.
    If a game object is inside more than 4 environments, only the 4 environments with the highest priority will be active (if the Default and Exclude Others flags are not set).
  • Default:
    A default environment will be active only if it's the only environment containing your game object.
    If your game object is inside more than one default environment, then only the one with the highest priority will be active.
  • Exclude Others:
    An environment with this flag can't be overlapped by other environments.
    If your game object is inside an environment with the Exclude Others flag, then all other environments will get discarded.
    If your game object is inside more than one environment with the Exclude Others flag, only the one with the highest priority will be active.
  • AuxBus Name:
    Specifies the name of the current AuxBus. To select an AuxBus, click on the current AuxBus's name to open the AuxBus picker window. Then, you can either click on an AuxBus and click on the Ok button or double-click an AuxBus to select it. You can also drag an AuxBus from the Wwise picker and drop it on the current AuxBus's name to select a new one.

• AkEnvironmentPortal component:
  You can create an environment portal in Unity by going to GameObject->Wwise->Environment Portal.
  You can place an environment portal between two environments to combine their effects while your game object is inside the portal. The portal must intersect with both environments for this to work.
  The contribution of each of the two environments is relative to their distance from the game object. The closer the game object is from an environment, the more that environment will contribute towards the final effect.
  
  • Environment #1:
    The portal will automatically detect all environments that intersect the portal. Of those environments, the ones that are placed on the negative side of the portal (opposite to the direction of the chosen axis) will be available in the drop down menu. The reason the environments are sorted this way is to reduce the computation needed to determine the contribution of each environment at runtime.
  • Environment #2:
    The portal will automatically detect all environments that intersect the portal. Of those environments, the ones that are placed on the positive side of the portal (same direction as the chosen axis) will be available in the menu. The reason the environments are sorted this way is to reduce the computation needed to determine the contribution of each environment at runtime.
  • Axis:
    The axis is used to find the contribution of each environment.
    For example, if the z axis is chosen, then moving along the x axis won't have any effect on the contribution of each environment. Only movement on the z axis will have an effect on their contribution.
    Note that the axis is in object space. So, rotating the portal will also rotate the axis.

See also:

• Integrating Environments and Game-defined Auxiliary Sends
• AK::SoundEngine::SetGameObjectAuxSendValues

Using C# code to control the sound engine

The API from the C++ Wwise SoundEngine is exposed in C#, with a few exceptions (see API Changes and Limitations). For more complex situations, you'll need to call Wwise functions from code. In the API, the GameObjectID in all functions is replaced by the Unity flavor of the GameObject. At runtime, an AkGameObj component is automatically added to this GameObject, unless you have already manually added it before.

Using numeric IDs instead of strings for Events and Banks.

The native Wwise API allows you to use strings or IDs to trigger events and other named objects in the Wwise project. You can still do this in the C# world by converting the file Wwise_IDs.h to Wwise_IDs.cs. Click Assets > Wwise > Convert Wwise SoundBank IDs. You need to have Python installed to make this work.