Wwise Unity Integration Documentation
Unity Addressables is a system built around AssetBundles for the purpose of packaging assets separately from the player. This is particularily useful in the context of DLC, where the extra assets can be stored on an external server.
The following sections will show you how to get started using our package for Addressables with Wwise:
- Particularities of the Addressables System
- Known Issues and Limitations
- Installing the Wwise Addressables Package with the Unity Package Manager and GitHub
- Setting Up and Building with the Wwise Addressables Package
- Building the Project
- Removing the Wwise Addressables Package
- Basic Tutorial For Packaging DLC
- Wwise Addressable Assets Explained
|Caution: This package should be considered as experimental. Addressables support is a new feature for the Unity integration and is subject to change.|
|Caution: Unity 2018 is not supported. Considering that using external packages in Unity 2018 can be prone to issues, we do not guarantee that this package will work properly in Unity versions older than 2019.|
The Addressables system has the following particularities of which you should be aware:
- Loading assets with Addressables is inherently asynchronous: This can cause issues if loading a SoundBank and posting an event are both linked to the same trigger. It is therefore recommended to ensure the SoundBank is loaded before its associated Events can be triggered if precise event timing is particularly important. The Init Soundbank is a particular case, as it must be loaded before all other SoundBanks in the scene. If the Init SoundBank asset is updated remotely, you can expect there to be a slight additional delay in loading any SoundBanks at the start of a scene, as the new Init SoundBank must first be fetched from a webserver using Addressables.
- Addressable assets should not be referenced directly in the scene: Addressable assets are meant to be loaded dynamically in your scenes using the Addressables system. Any assets that are referenced directly in your scene will be built into the scene's AssetBundle and will not be loaded via the Addressables. If you place an asset directly in your scene and also package that asset with Addressables, there will be two different copies of the asset in your game data: one in the scene's AssetBundle and one in the Addressable group's AssetBundle.
- All platforms in the project must share the same root Generated SoundBanks Path.
- Setting the Generated SoundBank Path in the Unity project settings doesn't automatically change the output paths for External Sources.
- Saving and loading of Decoded SoundBanks are not yet supported.
- Prepared Events are not yet supported.
- External Sources are not yet supported.
The official repository for the Wwise Addressables Package is : https://github.com/audiokinetic/WwiseUnityAddressables.
- Open the Unity Package Manager, click the '+' icon and select Add package from git URL....
- Paste https://github.com/audiokinetic/WwiseUnityAddressables.git in the text field and click Add.
More information about using packages hosted on Git repositories can be found in the Unity documentation.
|Note:||If you see an error containing the message "No 'git' executable was found", you will have to add the directory containing the git.exe executable to your system environment and possibly restart your system for the changes to take effect.|
|Note:||The Unity Addressables Package must also be added to the project for Wwise addressables to function properly. The package is listed as a dependancy of the Wwise Addressables Package and should be installed automatically.|
If using Unity 2018.x, add AK_WWISE_ADDRESSABLES and UNITY_ADDRESSABLES to Scripting Define Symbols in Project Settings > Player > Other Settings.
|Warning: This package is not officially supported for Unity 2018. Use this version at your own risk.|
Step 1: Set the target directory for your generated SoundBanks in Project Settings > Wwise Editor > Generated SoundBanks Path.
|Caution: This directory must be inside your Assets folder for the SoundBanks to be properly imported.|
- In this example we set the target directory to
- Changing this path automatically modifies the output target directories in Wwise.
- If Wwise Authoring is open when this change is made, a dialog opens prompting you to reload the project.
Step 2: Generate SoundBanks, either from within Wwise Authoring or using the Wwise Picker.
- At this point, the custom asset importers for .bnk and .wem files create Unity assets for generated SoundBanks and streaming media files.
- Metadata files and platform-specific groups are automatically generated in the AddressableAssetsData directory.
- You can confirm that your assets were properly imported by inspecting the files in the Generated SoundBanks Path.
- For more details, see Wwise Addressable Assets Explained.
Step 3: Click Window > Asset Management > Addressables > Groups. The Wwise Addressables Groups window opens.
By default, one group is created for each deployment platform containing the platform-specific SoundBank assets. Separate groups are created containing only the Init SoundBank for each deployment platform.
If you inspect the WwiseGlobal object in the scene, you will find that an Init Bank Holder component has been added to it.
Step 4: Create a Wwise Build Script for Addressables.
- We recommend placing this in
AddressableAssetsData/DataBuildersalongside the default build scripts.
- Right-click anywhere in the browser and select Create > Addressables > Content Builders > Wwise Build Script.
- This creates an asset named BuildScriptWwisePacked.
Step 5: Inspect the Addressables settings.
- By default, they are found in AddressableAssetsData/AddressableAssetSettings
- From the Groups window: Tools > Inspect System Settings
- From the editor: Window > AssetManagement > Addressables> Settings
Step 6: Add BuildScriptWwisePacked to the Addressables build scripts. In the inspector for AddressableAssetSettings, add the BuildScriptWwisePacked asset you created in Step 4 to the Build and Play Mode scripts.
Build the Addressable asset bundles from the Groups window using the Wwise Build Script. This will generate all general asset bundles (e.g. Default Local Group) as well as platform specific asset bundles in
Caution: The Wwise Build Script modifies the Include in Build property of WwiseData group schemas. If a group has WwiseData in its name, it will only be included if the name also contains the current build platform name. This behaviour can be modified in the
Once the addressable assets have been built, the project can be built as usual.
|Caution: You will have to rebuild the Addressable groups if you modify or add new SoundBanks to your project. Also remember to rebuild Addressable groups after you switch platforms.|
In the build directory :
- Addressable asset bundles are copied to
Removing this package requires a few additional steps for the Wwise integration to function properly.
- Delete the folder containing generated SoundBanks from your Unity assets folder.
- Uninstall the package, either through the Unity package manager or by deleting the corresponding line in the
- In your Wwise Project Settings, set the SoundBank Paths to a path outside of the Assets folder.
- Regenerate your SoundBanks.
- If you are still using the Unity Addressables package, be sure to clean up your Addressables groups.
|Note:||If using Unity 2018, remember to remove the AK_WWISE_ADDRESSABLES and UNITY_ADDRESSABLES Scripting Define Symbols in Project Settings > Player > Other Settings.|
In this example we will show how to handle the simple situation where we want to separate some assets (for example a new item or character) into their own DLC asset bundle that is packaged using Addressables.
The official repository for the Addressables Demo Scene used in this tuorial is https://github.com/audiokinetic/WwiseUnityAddressablesDemoScene. The demo scene uses assets that are found in the Unity Demo Game so it must be installed beforehand using the Wwise Launcher.
- Install the latest Unity Demo Game (minimum version 2021.1.0) using the Wwise Launcher.
- Clone the Wwise Unity Addressables demo scene to your computer.
- Open the Demo Game in Unity.
- In the Unity Package Manager, add the Wwise Unity Addressables package to the project as detailed in section Installing the Wwise Addressables Package with the Unity Package Manager and GitHub.
- Finally, add the Wwise Unity Addressables Demo Scene package with the Add package from disk option in the Package Manager.
|Note:||This package cannot be added using Add package from git URL as this type of installation will prevent you from opening the scenes contained in the package.|
For this tutorial we have created two sound effects, an event and a SoundBank in the Wwise project.
We created two GameObject prefabs with AkBank and AkEvent components : DlcAssetHighImpact and DlcAssetLowImpact. These prefabs load the DLC SoundBank and play a sound effect when they are instantiated.
We also created two scenes: AddressablesDemoScene and AddressablesSubScene. AddressablesDemoScene is a simple Unity scene with some interactive buttons so we can test loading and unloading our Addressable assets. AddressablesSubScene is a scene containing only the DlcAssetLowImpact prefab. We will use it to test loading scenes containing Wwise objects with Addressables.
|Note:||The AddressablesDemoScene also contains an example of using localized voices and changing languages with the Wwise Addressables package.|
All of these assets, as well as the scripts described in the following section, are found in
Mark these three assets as addressable by enabling the Addressable check box in their inspector.
|Caution: Removing the Unity Addressables package from your project will remove the Addressable field from all assets and the state of this check box will not be preserved if you reinstall the package.|
In the Addressables Groups window, you will find that these Addressable assets have been placed by default in the Default Local Group.
New groups can be created by either right-clicking the groups window and selecting Create New Group, or from the menu Create > Group > Packed Assets. Create two new groups for the DLC assets:
- DLC_Assets for our prefabs and subscene.
- DLC_WwiseData_Windows for our platform specific Soundbank assets.
|Note:||In this example we only create one additional SoundBank group for the Windows platform, but in general you should create one for each platform you plan on deploying to.|
- Move the DlcAssetHighImpact, DlcAssetLowImpact and AddressablesSubScene from the Default Local Group to the DLC_Assets group.
- Move the platform specific DLC SoundBank asset from WwiseData_Windows to the DLC_WwiseData_Windows group.
|Note:||We made sure to include the strings WwiseData and the platform name Windows in the platform specific group name, so that it will be properly handled by the BuildWwiseData script when building Addressables.|
In the Groups window, set the Play Mode Script to Use Existing Build and build the new Addressable packages with the Wwise Build Script (as described in Building the Project).
Now, open the AddressablesDemoScene.
In this scene there are two buttons
- The button on the left loads and instantiates the DlcAssetHighImpact prefab using Addressables.
- The button on the right loads and instantiates the AddressableSubScene.
- This scene contains the DlcAssetLowImpact asset.
If you inspect the Loading DLC Assets Demo GameObject, you will see that we have created an AssetLoader object, which contains the AddressablePrefabLoader component.
This component contains an AssetReference, which we have set to be the DlcAssetHighImpact prefab in its inspector.
When we run the game and press the left button, the Load method on the AddressablePrefabLoader will be called, loading it from the DLC_Assets and instantiating the DlcAssetHighImpact prefab. Once instantiated, the AkBank component will load the SoundBank from the DLC_WwiseData_Windows asset bundle.
If you inspect the Loading DLC Scene Demo GameObject, you will see that we have created a SceneLoader object, which contains the AddressableSceneLoader component.
This component uses an AssetReference to hold a reference to our AddressablesSubScene. The first time the button is pressed, the LoadSceneMethod is called, which will load the scene using the LoadSceneAsync method and add it to our current scene. The second time the button is pressed, the scene will be unloaded.
The AddressablesSubScene only contains our DlcAssetLowImpact prefab, which upon instantiation will load the DLC soundbank and play its corresponding event.
The third demo in this scene lets you switch between the English and French languages and play a localized voice sample. This demo uses the AkWwiseSetLocalization script. Upon pressing the green or blue buttons, this calls the AkAddressableBankManager.SetLanguageAndReloadLocalizedBanks function to change the language to English or French.
This function performs the following operations:
- Unload all localized banks
- Unload the Init bank
- Set the language using AkSoundEngine.SetCurrentLanguage
- Reload the Init bank
- Reload the localized banks
You can now build the AddressablesDemoScene and test the buttons to ensure that your built game is loading these assets.
Now we will configure Unity to serve our addressable DLC assets using its built-in hosting service. This will allow us to test updating assets using Addressables, without rebuilding our player.
First, build the AddressablesDemoScene and ensure that it works as expected. In the build window, you will have to add the AddressablesDemoScene with the Add open scenes button and select it as the scene to build.
Next we will configure Addressables Hosting, which can be accessed from the Tools menu.
Now create a Local Hosting service and enable it by selecting the Enable check box.
Open the Addressables Profiles window through the menu (Profile > Manage Profiles) and create a new profile named Editor Hosted.
Then set the Paths to the following :
- LocalBuildPath : HostedData/[BuildTarget]
- LocalLoadPath : http://[PrivateIpAddress]:[HostingServicePort]
- RemoteBuildPath : HostedData/[BuildTarget]
- RemoteLoadPath : http://[PrivateIpAddress]:[HostingServicePort]
Then, use this profile by right-clicking Editor Hosted and selecting Set Active.
|Note:||Consult the official documentation for more information about using Addressables hosting service.|
Inspect the DLC_WwiseData_Windows group asset and ensure that its Build path and Load path have been updated.
Open your Addressable Asset Settings and enable Build Remote Catalog . Set the Build Path and Load Path to LocalBuildPath and LocalLoadPath, respectively.
Rebuild your addressable assets using the Wwise Build Script. The new adressable AssetBundles should be created in
<Unity Project Path>\HostedData.
Now rebuild the AddressablesDemoScene to test that your assets are being served properly.
Open the Addressables Hosting window to view incoming requests as you run the game. The first time a button is pressed, a request should appear in the events log at the bottom of the window.
Now, we will update our DlcAssetHighImpact sound using Addressables.
First, in Wwise, adjust the imp_axe_stone_high sound sample's pitch value so that the change will be obvious. Then regenerate your SoundBanks.
Then, in the Addressables Groups window, select Build >Update a previous build. In the selection window that opens, select the addressables_content_state.bin file in AddressableAssetsData/Windows.
Finally, run your built game again (without rebuilding it). When it opens, you shoud see a request for the update catalog in the Addressables hosting window.
Then, when you press the left button, you should hear the sound effect at its new pitch height.
For more infomation about the Addressables catalog and the intended development cycle, consult the official documentation.
|Note:||This scripts provided in this tutorial are the minimum required to test loading assets with Addressables. You will likely want to use a more robust solution for loading assets in your project. Some more advanced examples can be found in the Unity Addressables Sample repository.|
When created, .bnk and .wem files are processed by the WwiseBankImporter and WwiseStreamingAssetImporter classes. This script creates assets containing the binary data of the files. Our custom asset postprocessor WwiseBankPostProcess then adds the new assets to the Addressables group of their respective platform. The Init SoundBank for each platform is added to its own Addressables group. The reason the Init Bank is kept separate is because it must be updated when modifications to the project (such as adding new audio busses) are made post-release. By packaging the Init SoundBank in its own addressable AssetBundle, we minimize the time it will take to fetch the new version of this asset from the hosting service.
The asset postprocessor also creates a WwiseAddressableSoundBank for each SoundBank in the project. This asset contains a dictionary that maps platform names to their respective SoundBank and streaming media assets.
- WwiseAddressableSoundBanks are found at the root level of the Generated SoundBanks folder.
- The WwiseAddressableSoundBank class uses AssetReferenceT to point to the SoundBanks and media files.
- When building the project, the Current Platfrom Assets field of the WwiseAddressableSoundBank is set to the target build platform.
|Caution: SoundBanks and streaming media referenced in the WwiseAddressableSoundBank are soft references. They will be loaded using Addressables and must be packaged in an Addressables group.|
|Caution: If you delete a WwiseAddressableSoundBank by mistake, you will have to delete and regenerate the SoundBanks it is associated with in order to create a new one and set up its references properly.|
When the WwiseAddressableSoundBank for the Init SoundBank is created, an InitBankHolder component will be added to the WwiseGlobal gameobject in the scene. This component simply stores the WwiseAddressableSoundBank so that the AddressableBankManager can find it easily.
When using Wwise Addressables, the loading and unloading of soundbanks into memory is handled by the AkAddressableBankManager. This class stores references to loading and loaded AddressableSoundBanks and ensures that the Init SoundBank is always loaded first. If an AkEvent is triggered before its SoundBank has finished loading, this class will store the triggered call's parameters and retrigger the event once the SoundBank is loaded.
When a SoundBank is loaded, the SoundBank asset corresponding to the current platform is loaded using Addressables. Once it has been loaded, the soundbank data is pinned and a copy of the memory is loaded into the soundengine using AkSoundEngine.LoadBankMemoryCopy().
When in play mode in the editor, the AssetDatabase is used instead of addressables to load SounBanks synchronously. Asynchronous loading can only be tested in the built game.
The WwiseBankReference class is used in our custom inspector for the Ak.Wwise.Bank component. The WwiseBankReference contains a hard reference to a WwiseAddressableSoundBank. This reference is updated when a Master SoundBank Asset is created via the AkAssetUtilities.MasterBankUpdated delegate. If the WwiseBankReference is created after the WwiseAddressableSoundBank, it will search in the SoundBanks folder for a master SoundBank asset matching its bank name. Serialized WwiseBankReferences are stored in
|Note:||Any assets that are referenced directly by a game object will be packaged with the game object. AkBank Components contain a hard reference to a WwiseBankReference, and the WwiseBankReference contains a hard reference to its corresponding WwiseAddressableSoundBank. If you put a GameObject with an AkBank component in an Addressables group, the WwiseBankReference and WwiseAddressableSoundBank will be packaged with it (without having to explicitly add them to the group).|
Streaming media (.wem files) are also handled by the WwiseBankImporter script. The WwiseAddressableSoundBank contains a list of references to the platform specific streaming media assets associated with the bank. When a bank is loaded, the media assets are loaded via Addressables and copied to the Application.persistentDataPath folder. If a file with the same name already exists in the folder, their hashes are compared. If the files differ, the file is overwritten by the one from the AssetBundle.