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 are multiple optional modules, specifically WwiseSoundEngine followed by the Wwise version (such as WwiseSoundEngine_2024_1), which contains the code that bridges the WwiseSoundEngine interface and the actual Wwise Sound Engine API.

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."