Wwise SDK 2023.1.8

With many new features, you will need to pay attention to several things when migrating to Wwise 2017.1.

Please thoroughly read the following important migration notes:

Listeners are now game objects

In Wwise 2017.1, listeners are now game objects. There is no longer a limit of 8 listeners and the API has been streamlined to remove calls that operate only on listeners; they now operate on any game object. Games that use multiple listeners in Wwise must register a game object per listener; they will now perform a complete mix per listener.

Busses in Wwise are now associated with a game object

Busses are no longer global entities; they can be instantiated multiple times in a manner similar to voices in the Actor-Mixer Hierarchy. It is possible to set game object scoped RTPCs on bus parameters that pertain to a mixing bus. However, be aware that the Voice parameters in the bus’s General Settings tab actually pertain to the game object from which the voice is playing, not the bus’s game object.

The specific game object that is associated with a bus instance is determined by a combination of the Enable Positioning property in the Wwise project, and the emitter-listener associations defined by the game. Refer to the sections below, The behavior or the 'Positioning Enabled' flag in the authoring tool has changed and The algorithm to construct the Voices Graph has changed, for more details. Dynamic signal routing and 3D-positioned busses are now possible in Wwise; however, a basic setup will have various sources playing from one or more ‘emitter’ game objects and the entire mixing bus chain on another game object, the ‘listener’.

The game must register a game object and (optionally) set the listener as the default listener

Wwise does not provide a game object for you. To migrate to 2017.1 and have equivalent behavior, it is necessary to register a game object at initialization time and set it as the default listener.

Assigning a game object as the default listener is simply for the sake of convenience. It removes the need to call SetListeners() after registering subsequent game objects – they will automatically have the default listener assigned as their listener.

Note that if you are using SoundFrame you do not have access to the AK::SoundEngine::SetDefaultListeners API and you need to use SetListeners() explicitly.

The game must specify a listener when setting auxiliary sends

When setting a game-defined send through the API, it is now necessary to fill out an additional field to specify which game object will receive the send (both an Auxiliary Bus ID and a game object ID are necessary to uniquely identify a mixing bus instance). Specifying a game object when setting a game defined aux send is another way to add an emitter-listener association. It is similar to the SetListeners() API call, which defines the emitter-listener associations for the main bus output (sometimes called the “dry path”).

For the sake of convenience, it is possible to set the listenerID field to AK_INVALID_GAME_OBJECT, which will tell the sound engine to simply use the listener(s) that have already been specified with the SetListeners() or SetDefaultListeners() API calls. This feature facilitates both code migration and the most common auxiliary send scenarios, whereby the listener is the same as the one for the direct output.

Busses may now have auxiliary sends

In Wwise 2017.1, busses may now have aux sends to other busses, opening up a wide range of new routing possibilities. As with voices, auxiliary sends may be user defined or game defined. There are a few things to keep in mind when creating aux sends from busses:

It is possible to define routings that result in signal feedback loops. If a signal feedback loop occurs, the output will continue until the loop is broken by removing the send and may result in unstable output. It is not recommended to create routings that result in signal loops.
If a bus sends to another bus that is lower in the bus hierarchy, than the audio for the bus will be mixed next audio update, resulting in an additional latency of 1 audio frame. If this occurs, the connection in the Voice Graph of the Advanced Profiler will be displayed in red.
If a bus sends to the same level of the bus hierarchy (such as a sibling bus), one frame of latency may be induced, depending on the order that the busses are mixed in the sound engine. The sound engine will attempt to resolve the processing order to minimize the amount of latency induced, but in some cases it is not possible.

The behavior or the 'Positioning Enabled' flag in the authoring tool has changed

The Enable Positioning flag in the authoring tool now takes on a very important purpose: it determines whether or not to evaluate the emitter-listener associations for the current game object at this node in the voice graph. Furthermore, the 2D panner is now independent from the Enable Positioning flag; it is possible to pan a sound without positioning it. It is also possible to have a 2D sound that is Positioning Enabled; this means that we will evaluate the emitter-listener associations (the downstream node will be on a different game object), but not preform 3D spatialization. Here are some examples to demonstrate the usage of the Enable Positioning flag:

A voice in the Actor-Mixer Hierarchy has its Enable Positioning flag set and its Positioning Type set to 3D. This voice will be placed in 3D space according to the position of its game object, and it will be panned and attenuated before being mixed into its upstream bus. A unique instance of the upstream bus will be created for each listener game object that is associated with the emitter game object. This is a typical scenario in a modern game.
A voice in the Actor-Mixer Hierarchy does not have its Enable Positioning flag set. The voice instead mixes into a bus that has its Enable Positioning flag set. In this case, the bus is spawned on the emitter game object, the same game object as the voice. A unique instance of the bus that is downstream (the parent) to the positioning-enabled bus is spawned for each listener of the emitter game object. This setup allows us to do something in Wwise that we could not have done before 2017.1: perform a submix before panning, attenuating, or spatializing a sound.

A bus has its Enable Positioning flag set. A voice that also has its Enable Positioning flag set mixes into this bus. In this scenario, we are performing 2 X 3D mixes—a submix of a spatialized sound is then spatialized again. In this setup we have 3 game objects: an emitter, a listener, and a game object that is both listener to the first game object and an emitter to the final listener. A setup such as this can be used to simulate acoustic phenomena such as portals.

Note: If you see two instances of the Master Audio Bus in the Voice Graph when you do not expect to, it is a good indication that you forgot to set the Enable Positioning flag at some point in your signal chain.

The algorithm to construct the Voices Graph has changed

Before 2017.1, the Voices Graph constructed when playing a sound was entirely specified by the Wwise project; there was little that the game could do to manipulate it. In Wwise 2017.1, the Voices Graph is based on a combination of the routing defined by the hierarchies in the Wwise project and the emitter-listener associations defined in the game. The algorithm to construct the Voices Graph can be summarized as follows:

After an Event which plays a sound is posted, a source is spawned and associated with the game object as specified by the Event.
The source is connected to the Voices Graph according to the Enable Positioning flag:
- If the source has its Enable Positioning flag set in the Wwise project:
  - If it doesn’t exist already, an instance of the source’s output bus is spawned for each listener that has been associated with the source’s game object. The source is connected to each of these bus instances.
- If the source does not have positioning enabled:
  - A single instance of the output bus is spawned, if it does not already exist, using the same game object as the source. The source is connected to this bus.
Each successive bus in the Voices Graph is connected to its parent bus, according to the state of the Enable Positioning flag:
- If the bus has its 'Enable Positioning' flag set:
  - An instance of the bus’s parent bus is spawned for each listener that has been associated with the bus’s game object.
- If the bus does not have its 'Enable Positioning' flag set:
  - A single instance of the bus’s parent is spawned using the same game object as the current bus.

The rules that define the routing of a sound can be complicated. The new Voices Graph in the Wwise Advanced Profiler now groups nodes by game object and is an extremely useful tool when debugging routing issues.

AkGameObjectID is now a 64-bit integer on all platforms

For the sake of consistency, AkGameObjectID is now 64 bits wide on all platforms, including native 32-bit platforms.

The valid game object ID range has changed

A game object ID can now be any 64-bit unsigned integer ranging from 0 to 0x‭FFFFFFFFFFFFFFDF‬ (which is -33 as a signed integer). The game object ID range 0x‭FFFFFFFFFFFFFFE0‬ (-32) to 0x‭FFFFFFFFFFFFFFFF‬ (-1) is reserved for internal use. The transport game object, which is registered by the authoring tool, now uses game object ID 0x‭FFFFFFFFFFFFFFFE‬ (-2).

Game object and listener Watches in the Profiler layout are reset when migrating to 2017.1

Following the changes made to the game object and listener system, Watches are not compatible anymore and will be reset.

Plug-ins must be rebuilt

Plug-ins built with versions prior to the official 2017.1 release are not compatible with Wwise 2017.1. They need to be rebuilt.

Some parameters are not used anymore and were removed from the API

These flags are no longer required, so they were removed.

AkPluginInfo::bIsAsynchronous
AkFileSystemFlags::bIsFromRSX

Removed clamping of trigger rate

Prior to Wwise 2017.1, the sound engine was arbitrarily clamping the trigger rate transition time of Random and Sequence Containers to never be less than 22 ms. We removed this limitation to enable creative content.

Universal Windows Platform

The Metro platform has been renamed to Universal Windows Platform and is also available for Visual Studio 2017.

Spherical coordinates are no longer available from AkEmitterListenerPair

Spherical coordinates are no longer computed systematically for all emitter-listener pairs. Thus, they are not directly available from AkEmitterListenerPair anymore. Azimuth() and Elevation() accessors have been removed. Plug-ins and game code that use AkEmitterListenerPair spherical coordinates will need to call the new service AK::IAkGlobalPluginContext->ComputeSphericalCoordinates() to obtain them. The preferred approach is to use Cartesian coordinates with the overload of AK::IAkMixerPluginContext::Compute3DPositioning() that accepts Cartesian transforms.

Import Tab Delimited change

When importing Tab Delimited files using the UseExisting option, the behavior has changed. Like before, if the Wwise object at destination already exists, it will reuse it. However, if a matching object is found and the source's WAV file name is different, the new source will be imported as a new inactive version.

WAAPI changes since Alpha and Beta

Added where transform in ak.wwise.core.object.get. Refer to transform for more information.
Added new merge mode in ak.wwise.core.object.create. Refer to Understanding the name conflict modes for more information.
Added support to create Virtual Folder in ak.wwise.core.object.create. Use the type Folder. Refer to ak.wwise.core.object.create for more information.
Subscription topic ak.wwise.core.object.preDelete was renamed to ak.wwise.core.object.preDeleted.
Subscription topic ak.wwise.core.object.postDelete was renamed to ak.wwise.core.object.postDeleted.
Added support to create Events and Event Actions in ak.wwise.core.object.create.
Added support to query languages ak.wwise.core.object.get. Refer to ak.wwise.core.object.get for more information.
Added support for return options in ak.wwise.core.object.nameChanged, ak.wwise.core.object.notesChanged, ak.wwise.core.object.created, ak.wwise.core.object.preDeleted, ak.wwise.core.object.postDeleted, ak.wwise.core.object.childAdded, ak.wwise.core.object.childRemoved, ak.wwise.core.object.curveChanged, ak.wwise.core.object.attenuationCurveChanged, and ak.wwise.core.object.attenuationCurveLinkChanged.