Static Sound Engine Bridging

The WwiseSoundEngine Module contains the Wwise Sound Engine API interface, as well as various bundled plug-ins.

Most of the functions in the Wwise Sound Engine are bridged at the lowest level possible. In order to call any Wwise Sound Engine API, you must call them through the bridge:

注意： Do not use any AK:: or ak:: functions directly. It can cause linker errors, instability, or a crash.

Prior to Wwise 2022.1, it was necessary to make all AK::SoundEngine calls from AkAudioDevice from within the AkAudio module. While this is no longer necessary, that legacy approach remains possible. It might be preferable in some cases because it provides more functionality to user code, including converting from Unreal classes to Wwise native types, alongside Blueprintable operations.

There is a second module, WwiseSoundEngine_2022_1, that contains the bridging code from the WwiseSoundEngine interface to the actual Wwise 2022.1 Sound Engine API.

Global Callbacks

The Integration includes a Global Callbacks singleton feature. This allows games and tools to leverage the Sound Engine’s AkGlobalCallback. For a description of the callbacks, refer to AkCallbackType in the Wwise SDK documentation.

For each callback, the following functions are available:

• <Location>Async: The least expensive method, where the callback is executed as soon as a Task Graph thread is available. You must make sure the callback follows the best practices for multithreaded code.
• <Location>Sync: The fastest, most reactive method, but also the most risky. It executes the callback in the Sound Engine threads, potentially causing slowdowns and audio glitching. You also need to be mindful of the limitations of threads created external to the Unreal thread pools. They don’t have the same Unreal thread-local data, the stack size is different, and the priority might be different. In other words, use at your own risk!
• <Location>Game: The preferred method for user interface tasks, where the callback must be executed on the Game Thread.

Each function has its own uses; none is perfect for all scenarios.

Null SoundEngine

The Wwise Integration for Unreal connects the Wwise SoundEngine to the Unreal Engine. There are valid reasons to disable the SoundEngine at build time:

• Executing a server: The Wwise Integration for Unreal is client-specific. Avoid running a Wwise SoundEngine on a server.
• Executing a program: Unreal programs perform various tasks, such as building, packaging, or cooking. Unreal Frontend and Insights are examples of programs with user interfaces. The Wwise SoundEngine is meant to be used exclusively for what Unreal defines as Games, and the Editor.
• Building for an unsupported platform or platform version: The Wwise SoundEngine includes optimized binaries for many modern platforms, but the binary files might not be installed for a particular platform. There might also be a different platform SDK version installed and selected than the ones used to build the Wwise SoundEngine.

It is therefore impossible to link the actual Wwise SoundEngine to the final executable. In these cases, the build scripts use the null SoundEngine. The null SoundEngine is an empty implementor that sits on top of the SoundEngine abstraction provided in the WwiseSoundEngine bridging module. Most functions return AK_NotImplemented without any side effects.

Because the bridge requires the Wwise SoundEngine type definitions to be accurate for the platform, the ThirdParty/include folder must contain an interface for the platform, even if it is not activated in the current context. It is therefore impossible to guarantee that a build for an unsupported platform will work, even with the null SoundEngine.

There are also valid reasons to disable the SoundEngine at runtime:

• Using the null SoundEngine from build time.
• Disabling audio: Multiple options allow a game or the editor to run without sound.
• Running a commandlet: Editor commandlet operations complete without displaying a user interface. These are specialized programs built inside the Unreal Editor itself.
• Error in initialization: If the Wwise SoundEngine fails to initialize, or if the SoundBanks were never Generated for the project.

Typically, the Wwise SoundEngine is disabled when the Wwise SoundEngine is linked inside the final executable package. Some of the issues can be fixed without restarting the Editor. Runtime issues do not use the null SoundEngine unless specified.

The logic for a supported target is executed during Unreal's project generation step in WwiseUEPlatform.IsWwiseTargetSupported. You can determine whether the null SoundEngine is used in UBT's logs: The "Wwise SoundEngine is disabled: Using the null SoundEngine instead." log will be displayed along with the reason. This message appears multiple times when building the Wwise SoundEngine as an Engine plug-in. The message is informative, not an error.

To help with debugging, a similar message is also repeated at runtime in the logs during the Wwise plug-in initialization: "Wwise SoundEngine is disabled: Using the null SoundEngine."