Table of Contents

Wwise SDK 2018.1.11
Important Migration Notes 2018.1

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

Please thoroughly read the following important migration notes:

Event Action property Fade Curve split into Fade-in Curve and Fade-out Curve

The Fade Curve property of Event Actions has been split according to the Action type, such that Actions related to activation (such as Play, Resume, and Set LPF) now have a Fade-in Curve property and Actions related to deactivation (such as Stop, Pause, and Reset LPF) now have a Fade-out Curve property.

Contents Editor

The Contents Editor has been rewritten as a tree, allowing object nodes to be expanded to show their descendants. The column headers can be resized and customized much like in the Multi Editor, and the inclusion now has a dedicated column. In order to allow objects to be sorted when clicking on the column headers, it is no longer possible to reorder objects in the Contents Editor.

Positioning Tab

The Positioning tab of the Property Editor has been thoroughly reorganized. Here is a short guide for those who were used to the old set of controls.

Enable Positioning

The Enable Positioning check box was renamed to Listener Relative Routing. It behaves exactly as before, but the name makes it more apparent that its effect goes beyond positioning and affects routing. In effect, it forces the engine to evaluate the emitter-listener association at that node. Emitters and listeners are game objects, assigned via the SDK; listeners are assigned to emitters using AK::SoundEngine::SetListeners, or when setting aux sends; and emitters are set when posting Events. Evaluating the emitter-listener association means that the signal will "jump" from the current game object to its listener. This can be observed in the Voices Graph. Evaluating the emitter-listener association is a prerequisite for any positioning feature (distance attenuation and spatialization) that involve an emitter and a listener.

2D with Enable Panner off

This used to be the default setting, and still is. The Speaker Panning list must be set to Direct Assignment. The Listener Relative Routing option has no effect on panning.

2D with Enable Panner on

The Speaker Panning list must be set to Balance - Fade. Then you can edit panning by clicking on Edit… to the right, in the same dialog as before. The Listener Relative Routing option has no effect on panning.

3D Game-Defined

Enable Listener Relative Routing, set Position list to Emitter, set 3D Spatialization to either Position or Position + Orientation (the former the default value). Ensure Speaker Panning / 3D Spatialization Mix is set to 100. The equivalent of disabling the former option, Update At Each Frame, is to enable Hold Emitter Position and Orientation. You can also set an attenuation, like before.

3D User-Defined

Enable Listener Relative Routing, set Position list to Listener + Automation, set 3D Spatialization to either Position or Position + Orientation (the former the default value). Ensure Speaker Panning / 3D Spatialization Mix is set to 100. Edit the path by clicking on Automation…, in the same dialog as before. The equivalent of disabling the former option, Follow Listener Orientation. is to enable Hold Listener Orientation. You can also set an attenuation, like before.

Spatialization set to None

Before, when setting positioning to 3D but Spatialization to None, the resulting positioning was equivalent to having the 2D panner enabled, with the dot in the middle. Now, Spatialization set to None takes whatever Speaker Panning option you choose, whether it is Direct Assignment or Balance - Fade with the position you desire. Also, this reorganization allows you to apply an attenuation on "2D" (panned) sounds.

New features

The Listener + Automation mode is equivalent to the former 3D User-Defined mode because the sound positions were always set relative to the listener. Now you can also have the sound positions occur around the emitter game object instead, by setting the Position mode to Emitter + Automation. In this case, the path automation will be done around the Emitter game object, where the front is defined by the orientation of the game object in game. The automated position is used for distance attenuation (if set) and spatialization (if set).

Last but not least, you can blend between Panning and Spatialization (formerly referred to as 2D and 3D) using the Speaker Panning vs 3D Spatialization Mix slider, where 100 is full spatialization.

Note: Using a value lower than 100 will be slightly more expensive at run-time due to the fact that both types of positioning must be calculated.

Mixer plug-in API

The functions IAkMixerInputContext::IsSpatializationEnabled and IAkMixerInputContext::IsPannerEnabled have been removed. You should instead use the following functions, which more accurately match the settings described above:

  • GetSpeakerPanningType
  • HasListenerRelativeRouting
  • Get3DSpatializationMode

GetNum3DPositions() and other "3D"-related functions apply only when HasListenerRelativeRouting() returns true. Designers may use these positions for attenuation and/or spatialization, according to the other settings, which you can query.

Migration Details

Here are a few details to be aware of:

  • The attenuation is now independent from spatialization, and is therefore not affected by Speaker Panning / 3D spatialization Mix. There is no way to directly disable attenuation at runtime. The alternatives are:
    • Playing the sound on a game object at the position of the listener, or directly on the listener game object.
    • Adjusting the attenuation via AK::SoundEngine::SetScalingFactor.
  • Game object-defined obstruction and occlusion now apply to all sounds and busses that have Listener Relative Routing enabled (typically, all objects of the actor-mixer hierarchy have Listener Relative Routing enabled). For avoiding obstruction / occlusion, post your event on a different, unobstructed and unoccluded game object.
  • API / Plug-in API changes: Removed functions AK::IAkMixerInputContext::IsSpatializationEnabled and AK::IAkMixerInputContext::IsPannerEnabled, and added functions AK::IAkMixerInputContext::GetSpeakerPanningType, AK::IAkMixerInputContext::HasListenerRelativeRouting, and AK::IAkMixerInputContext::Get3DSpatializationMode.
  • Project migration of RTPCs on "Positioning Type" moves curves over to Speaker Panning / 3D Spatialization Mix with constant segments. You can later change these constant segments to any line type of your liking by right-clicking on the curve in the RTPC view.
  • Project migration clears Attenuation from 2D sounds except if there is an RTPC on "Positioning Type".
  • Priority change based on distance will occur on objects with Listener automation, whereas sounds with the former 3D User-Defined Positioning mode would not.
  • Sounds whose Position is set to Listener + Automation, but Spatialization set to None, will get distance attenuation due to automated positions, whereas before it did not.
  • "3D" (spatialized) sounds with Spatialization Mode set to None used to mimic the behavior of "2D" sounds with "panner enabled" (Balance-Fade) with the cursor in the middle. The new behavior takes what you choose as the Speaker Panning option, that is, either Direct Assignment or Balance-Fade. However, the automatic project migration does not explicitly set the Speaker Panning option of "3D" sounds with Spatialization Mode set to None, so it will likely fall back to Direct Assignment.

WAAPI ak.wwise.core.audio.importTabDelimited error format changed

The details field in the error object returned by ak.wwise.core.audio.importTabDelimited is now compliant with WAMP specifications. It changed from an array to an object. The array was moved to a field called results in the object.

Opus for Nintendo Switch has been renamed OpusNX

With the introduction of the standard software Opus codec, the Switch-specific Opus codec was renamed OpusNX. This means that the related files have changed as well:

  • include file AkOpusFactory.h is now AkOpusNXFactory.h
  • library file libAkOpusDecoder.a is now libAkOpusNXDecoder.a

These files should be used on the Nintendo Switch to make use of the hardware decoder of that platform. Note that the standard Opus codec is also available on Switch but will be decoded in software. The standard Opus codec files are named AkOpusDecoderFactory.h and AkOpusDecoder[.lib, .a].

Using the geometry API in 2018.1

For 2018.1, the geometry API has been changed in order to streamline the data, and provide a more convenient and compact representation. Note the following changes:

  • Vertices are now defined in a separate array from the triangles, and each triangle in the triangle array references indices in the vertex array.
  • Each triangle also includes an index to an AkAcousticSurface structure, which defines the acoustic texture, description string, and reflector channel mask.
  • The correspondence between acoustic surfaces and triangles is up to the user. For example, the user may choose to have one surface for each triangle, a single surface for all triangles, or something in between.
  • Defining acoustic surfaces is optional. If it is not desired to customize the acoustic properties of a surface, the triangles may be left as AK_INVALID_SURFACE and NULL may be passed into AkGeometryParams::Surfaces and AkGeometryParams::NumSurfaces set to zero.

Built-in Game Parameter Diffraction Changed to Percentage

In Wwise 2017.2, units of the built-in Game Parameter Diffraction were degrees, ranging from 0 to 180. In 2018.1, Diffraction is now expressed in percentage, with 100% corresponding to 180 degrees. Likewise, the Diffraction value displayed in the 3D Game Object Profiler is now a percentage. This makes it easier to work with diffraction-driven Obstruction, which already ranges from 0 to 100. Your existing projects will automatically adapt your curves accordingly, as you migrate them to 2018.1.