Note: Before version 2022.1 of the Wwise Unreal Integration, this feature was called the "Split Switch Container Media".

By default, when Wwise Event assets are loaded, all resources they might use (SoundBanks and media) are loaded with them. In deep, nested switch container hierarchies, a large number of media resources can be loaded, and the amount of memory required to load these resources increases accordingly. You can use reference-loaded switch containers on a per-event basis to optimize memory usage: when enabled, resources are only loaded if they are referenced, based on Switch or State values.

If the media in your Switch Container is streamed, which is common for large music files, this feature improves performance because the files are only opened for streaming when necessary. Memory usage is also reduced if the media has a prefetch chunk.

This feature is only available for certain Events that use Switch Containers. It provides the most benefits for Events used in several different contexts, and that only use a subset of the container's Switch values in each context.

For example:

• A main character's footstep Event can contain a deep hierarchy depending on multiple Switches such as footwear, ground material, and weather conditions. However, most maps only contain a subset of materials or weather conditions. Similarly, the character typically only wears one type of footwear at a time, so loading sounds for all other footwear types are unnecessary.
• Different branches of a dynamic music system based on Switch Containers could depend on Switches or States that are only used in specific maps.

The following image shows a Footstep Event dependency tree:

If the active level references the Human_Surface_Material Switch and only references the Material_Dirt Switch Value (through a SetSwitch node in the Level Blueprint, for example), only the FS_Dirt_[01-04] media files are loaded into memory. When a sublevel that references Material_Grass is loaded, grass_[01-04] media files are automatically loaded with the Switch.

Warning: When this option is enabled, Switch or State values are loaded in memory to determine which media to load. Be cautious in the following cases: Setting State or Switch Values with strings. You must ensure that the corresponding Switch or State value asset is loaded, for example by using the Load Asset Blueprint Node. Setting State or Switch Values from C++. You must ensure that the corresponding Switch or State Value asset is loaded, for example by using Unreal Engine Asynchronous Asset Loading. Using RTPC-Controlled Switch Containers. This type of container causes inconsistencies when loading media. Avoid using this option if you are using RTPC-Controlled Switch Containers. In addition, be careful when loading and setting Switches or States in submaps or menus. When those levels are unloaded, the Switch or State Value assets will probably be unloaded as well if they are not referenced in the persistent level, which causes their associated media to be unloaded. This can produce unexpected behavior if the Switch or State Value is still set on GameObjects in the scene.

Enabling Reference-Loaded Switch Container Media

Each UAkAudioEvent contains a FWwiseEventInfo structure, which identifies the Wwise Event it represents. The WwiseEventInfo structure also contains the SwitchContainerLoading field, which can enable reference-loaded Switch Container media.

.

When set to AlwaysLoad, the default mode for all Events, all media resources are loaded with the Event. When set to LoadOnReference, only the referenced media resources are loaded with the Event.

Technical Details

When this option is activated and a Wwise Event asset is cooked by the WwiseResourceCooker, its cooked data contains a set of SwitchContainerLeaves. These leaves are a flattened map of different sets of Switch (or State) Values to media and SoundBanks to load. As seen in the previous example, the FS_Dirt_[01-04] media are only needed if the Human_Surface_Material and Material_Dirt Switches Values are loaded as well. This is represented by a SwitchContainerLeaf with a "key" formed by the pair of Human_Surface_Material and Material_Dirt switches and a payload of FS_Dirt_[01-04] media to load. When a Wwise Event is loaded by the WwiseResourceLoader, its set of SwitchContainerLeaves is added to a list of leaves that the WwiseResourceLoader tracks for each known Switch and State Value. When Switch and State Values are loaded (or unloaded) by the WwiseResourceLoader, it checks its list of known SwitchContainerLeaves associated with that value to see if any media need to be loaded (or unloaded).

Note: Media dependencies are evaluated only when Event, Switch, and State assets are loaded by the WwiseResourceLoader. Setting and unsetting Switches or States in the Sound Engine does not cause media to be loaded or unloaded.

When a Default Value is set on a Switch Container, the resources that only depend on Default Values are always loaded. The same behavior applies to the Generic Path that can be set in Music Hierarchy Switch Containers. In these cases, resources such as SoundBanks and Media are not put in SwitchContainerLeaves. Instead, they are always loaded with with Events that use those Switch Containers.

This system is easiest to work with when you use Blueprints and Wwise assets to post Events and set Switch and State Values. In this case, the assets are loaded in memory with the level so the WwiseResourceLoader does not miss any information. To optimize memory usage even more, you can also disable the AutoLoad property exposed by UAkAudioType, available in all Wwise assets. When this option is disabled, each asset's LoadData and UnloadData methods (available in Blueprints) must be called for the WwiseResourceLoader to load and unload them.

Finally, it is the game designer's responsibility to ensure that the WwiseResourceLoader has already loaded the necessary resources when attempting to post Events or set Switches and States in the Sound Engine by using strings. This likely requires the relevant Event, Switch Value, and State Value assets to be manually loaded (or referenced in maps or Blueprints). However, it is possible to build Switch or State Value CookedData programmatically, and then load and unload them in the WwiseResourceLoader instead of assets.