Version
Wwise Unreal Integration Documentation
|
The Wwise Unreal Integration is separated into multiple modules. In order to use Wwise's functionality within a C++ project, you must link these modules within your project's build file (.Build.cs
). You can disable a module by removing it from the build file.
In the following example, the project includes the following modules as public: Core, CoreUOBject, Engine, InputCore, AkAudio, and WwiseSoundEngine. AkAudio
and WwiseSoundEngine
are Wwise modules.
In this case, the functionality of the WwiseSoundEngine
module and AkAudio
module are available. Modules can be in the PublicDependencyModulesNames
or PrivateDependencyModulesNames
. More information about modules can be found in the Unreal Engine Documentation.
The Integration is organized in the following modules:
The Integration's module dependencies are illustrated in the following figure:
The modules in the Integration, aside from WwiseSoundEngine
, AudiokineticTools
, and AkAudio
, are designed to be extensible through inheritance. Most functions in these modules are virtual to allow developers to override them and modify their behavior to best suit their project. To override a module, create a new module and make sure it inherits the module you want to override. Then, override the desired functions. To use your new module, make sure it is included in the Build.cs
of your game and added to the DefaultEngine.ini
like this:
The WwiseSimpleExternalSource module is an example of overriding a module. It overrides the WwiseFileHandler
module to handle external sources with Data tables.
When creating a new AkComponent
using C++, you must attach it to a parent component. The AkComponent
is necessary for the API to work as intended. The following sections provide examples of how to add an AkComponent
.
It's possible to use the Wwise API through the Wwise Unreal Integration. You can call most functions through the WwiseSoundEngine
module or the AkAudio
module.
The WwiseSoundEngine
module provides low-level access to most SoundEngine API operations. With the WwiseSoundEngine
module, you can access API functions directly and securely, as shown in the following example:
This code posts an Event on a given actor. You must add the UAkComponent
on the actor to register it with Wwise. The Event must be loaded as well since loading an Event isn't automatically performed in the WwiseSoundEngine
module.
![]() | Note: Prior to version 2022.1 of the Integration, it was impossible to access code outside the AkAudio module because the API needed to be accessed in the same dynamic library. |
The AkAudio
module is the root module for most of the Integration’s user-facing features. It can accomplish most of what the WwiseSoundEngine
module can using Unreal Components. It contains classes for the asset types and components used by the Integration. As an alternative to calling the SoundEngine directly, the AkAudioDevice provides many helper functions to wrap common uses of the WwiseSoundEngine API. These helper functions also check that the necessary resources required to use the API are loaded, and they provide more informative logging.
The following code, just like the previous example, posts an Event on a given actor, but also takes care of attaching the AkComponent
and loading the Event:
More examples of code can be found in the WwiseDemoGame under WwiseDemoGame/WwiseCodeExample
and can be experimented with in the WwiseDemoCodeExampleMap
.
Each module in the Integration has an independent log verbosity level. This helps to debug efficiently. If an error occurs, you can find which module produced the error, and then you can set the verbosity of that module's logs to Verbose or VeryVerbose to better understand why the error occurred. You can change the verbosity level of each module in the Core.Log
section of the DefaultEngine.ini
file. There's also a special logging category called LogWwiseHints
enabled by default across all modules, which warns about using deprecated functions and other bad habits.
The following verbosity levels are possible:
In the following example, you can see the verbosity level associated with each module:
More information about verbosity levels can be found in the Unreal Engine Documentation.
The Integration includes the following Stats that might help with debugging:
To access this information, select the Stats that interest you in the Unreal Viewport options.
More information about Stats can be found in the Unreal Engine Documentation.
When you package your Unreal project, the assets are "tree-shaken." In other words, Unreal assets that represent Wwise objects are automatically included if they are referenced either by another packaged asset or by a packaged map. If they are, any associated SoundBanks and media files are copied into the built package. Any Wwise Unreal assets that do not satisfy one of these conditions are not included.
This packaging approach is efficient, but in certain cases some Wwise Unreal assets might be improperly excluded, which can cause errors. The following scenarios can cause this type of problem:
If one of these scenarios applies to your project, you must therefore ensure that either the asset is directly referenced by a map, or ensure that the required assets are manually loaded. To manually add assets, add the containing directory to the project's Additional Asset Directories to Cook in the Project Settings. Refer to Project Section of the Unreal Project Settings for more information.
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise