About Unity Addressables
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.
If you are just starting out with Addressables, we recommend first familiarizing yourself with the official documentation and educational resources.
To get setup with the Wwise Unity Addressables package, we recommend starting here:
The following sections will describe how the Wwise Addressables package functions:
- Particularities of the Addressables System
- Known Issues and Limitations
- Wwise Addressable Samples
Wwise Addressable Assets Explained
- SoundBanks and AddressableSoundBanks
- The Addressable Bank Manager
- Wwise Asset Importers
- Streaming Media
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.
Particularities of the Addressables System
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.
Known Issues and Limitations
- 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.
Wwise Addressable Samples
The Wwise Addressable Samples page provides additional information about code samples designed to help manage Wwise addressable assets.
Wwise Addressable Assets Explained
Wwise Asset Importers
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. If you wish to customize what addressable group the assets are added to, and which labels are applied to the assets, please consult the Wwise Addressable Samples page.
SoundBanks and AddressableSoundBanks
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.
The Init Bank Holder
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.
The Addressable Bank Manager
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 WwiseAddressableSoundBank Asset is created via the AkAssetUtilities.AddressableBankUpdated delegate. If the WwiseBankReference is created after the WwiseAddressableSoundBank, it will search in the SoundBanks folder for a WwiseAddressableSoundBank asset matching its bank name. Serialized WwiseBankReferences are stored in
||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.