About Wwise 2022.1 Unreal Integration

This version is a major milestone in the Unreal Integration for Wwise. Much like Unreal Engine 5 bringing the engine to a new realm, Audiokinetic’s Wwise Integration for Unreal pushes the boundaries of what is possible with both tools working together. The changes span more than one year of hard development work, as well as many discussions with developers who want to push the boundaries of what is possible with the Wwise and Unreal combo. There were many lessons learned during the incremental optimizations and feature requests throughout the previous years. For example, we initially wanted to support every single possible workflow, where every single game has its own prerequisites and it is a pipe dream to make every fantastic usage working without customization. As such, we are very thankful to Wwise users for making their joys, hurdles and frustrations known to us. This is what ultimately allowed the priorities to be set.

Quick Start

Migrating to Wwise 2022.1

Before beginning the migration process, ensure that you can modify all the necessary files in the Wwise and Unreal projects.

Files you will need to check out in version control:

• The entire Wwise project directory
• All Unreal Wwise Assets (Events, SoundBanks, Aux Busses, etc.)
• Unreal project settings files:
  • DefaultGame.ini
  • DefaultUser.ini

You may also need to check out Maps or Blueprints referencing AkAudioBank assets as these files will be deleted as part of the migration process.

As usual, migration begins by upgrading the Wwise Unreal Integration from the Unreal Engine page in the Audiokinetic Launcher.

Note: If your project was previously using 2022.1.0 Beta 2, a change in casing in some file names might cause build issues on platforms where the file system is case-sensitive. Ensure that all files containing the word "ShareSet" in their file name are spelled correctly (with each S capitalized in "ShareSet") after upgrading from the Audiokinetic Launcher.

After the upgrade is complete, open the Wwise Project and a “Project Migration” dialog will present itself.

Click the Update button to continue.

After the Wwise project is updated and saved, you can open your Unreal project. When it opens, the Wwise Integration Migration dialog appears. In the dialog, you can choose which migration operations to perform. We recommend that you perform all of the migration operations immediately, but you can defer the migration process or perform each operation separately if necessary. If you want to perform these steps independently, we recommend that you read the Partial Migration and Project Migration State section before attempting to migrate your project. When multiple migration operations are selected, they are performed in the same order as they appear in the Migration Window. The migration dialog remains accessible in the Build Menu under Audiokinetic Migration > Finish Project Migration until all migration operations are complete.

There are four distinct operations in the migration:

• SoundBank Migration
• Delete deprecated assets
• Migrate Wwise Assets
• Update Project Settings

SoundBank Migration

SoundBank management is managed through Wwise Authoring once again, and therefore AkAudioBank assets are no longer used and must be deleted. In the previous workflow, SoundBanks were represented in the Unreal Project as manually created AkAudioBank assets. Event and Aux Bus assets could then be manually grouped into these SoundBanks. This was necessary in the Legacy workflow, but not with Event Based Packaging.

The following section in the dialog might appear, depending on whether your Unreal project contains AkAudioBank assets. In Wwise 2022.1, this migration operation helps you transfer your existing SoundBanks from your Unreal project back to the Wwise project and cleans up the deprecated AkAudioBank assets.

Transfer methods

Soundbanks are transferred to Wwise either by creating a SoundBank Definition File or by using WAAPI.

Create SoundBank Definition File will create a text file containing a list of SoundBank names and their content, which can then be imported into Wwise. If this option is selected, a field appears, in which you can select the destination for the generated file. For specifics on how to import this file into your Wwise project, consult the official documentation.

WAAPI will use the established WAAPI connection between the Unreal Editor and Wwise Authoring to update the Wwise Project to contain the SoundBanks. Be sure to save your Wwise project once the SoundBanks are transferred.

Wwise Authoring must be open for this to be usable. If you are not able to establish a WAAPI connection, the “Auto Connect to WAAPI” project setting may be disabled in your Wwise User Settings.

Failed SoundBank Transfers

If the WAAPI transfer of SoundBanks to Wwise fails partially, or if the process fails to write to the SoundBank definition file, a dialog appears with a list of errors. In the dialog, you can either cancel the migration or ignore the errors and continue. Some errors may be acceptable or expected. For example, if events that were removed from the Wwise project still exist as assets in the Unreal project, WAAPI calls involving those events will fail.

Delete deprecated assets

Some Wwise asset types used in the previous integration version have been deprecated and should be removed from the project. By selecting the Delete Deprecated Assets option, all assets of type AkMediaAsset, AkFolder and AkPlatformAssetData will be deleted.

Migrate Wwise Assets

Wwise asset properties have changed and they no longer serialize SoundBank or media binary data. The only information serialized to Wwise assets now is their GUID, ShortID, Name, and type-specific metadata properties used when loading or cooking the assets. During cooking, the information necessary for resource loading is serialized to the asset packaged in the game.

Selecting Migrate Wwise assets marks all Wwise assets in the project as dirty and save them. If you were previously using EBP and Split Switch Container Media was enabled, all events will have the EventInfo.SwitchContainerLoading flag set to LoadOnReference before saving.

Note: If you choose Migrate Wwise Assets as the only migration operation, it will not be possible to "Transfer SoundBanks to Wwise" afterwards, because the information necessary to do so will have been erased from the relevant assets.

Update Project Settings

Selecting Update Project Settings will update project settings depending on whether you were using Event-Based Packaging or the Legacy workflow. Be sure to save your projects after changes have been made.

Event-Based Packaging:

• In Wwise:
  • Enable Auto Defined Soundbanks will be enabled.
  • Create Sub-Folders for Generated Files will be enabled if Split Media Per Folder was enabled.
• In Unreal:
  • The Wwise Sound Data Folder will be removed from Directories To Always Cook.

Legacy: No settings will be changed in the Wwise project.

• In Unreal:
  • The Wwise Sound Data Folder will be removed from Directories To Always Stage As UFS.
  • Generated .bnk and .wem files in the Wwise Sound Data Folder will be deleted.

In both cases:

• The path set in the GeneratedSoundBanks folder location field will be applied to the Generated Sound Banks Folder setting in the Unreal project's Wwise Settings. The field defaults to the current GeneratedSoundBanks Folder path set in the Unreal project. We recommend using the standard <Wwise Project\/GeneratedSoundBanks path, unless your project has specific requirements.

Warning: If you modify the Generated Sound Banks folder location during migration, you might need to manually update the setting in Wwise. See Settings Requiring Manual Update.

Note: In Legacy projects, the GeneratedSoundBanks Folder had to be placed within the Unreal project's Content folder for packaging purposes. This is no longer necessary and we discourage using a folder within the Unreal project's Content for GeneratedSoundBanks. If the GeneratedSoundBanks Folder is inside the Unreal's Content Folder, you will be prompted to import files when SoundBanks are generated.You can ignore these prompts, but we recommend that you keep the GeneratedSoundBanks Folder outside of the Unreal project to avoid the prompts altogether. The GeneratedSoundBanks Folder can be changed at a later time in the Wwise Authoring Project Settings and the Unreal Project Settings. Both settings must be kept up to date independently.

Once all operations from the migration dialog are completed, your project should be ready, unless it uses external sources, which will require an additional migration step.

The Project Migration Commandlet

The integration also provides a commandlet (refer to Using the Project Migration Commandlet) to perform the migration operations described in the previous section from the command line.

Settings Requiring Manual Update

Wwise Installation Path (In Unreal) If you have Wwise installed on your machine, and you want to generate SoundBanks from within Unreal without using WAAPI, you must set the Wwise Mac/Windows Installation Path setting in the Wwise User Settings.

SoundBanks Root Output Path (In Wwise) We recommend verifying that the Root Output Path in Wwise authoring's SoundBanks Settings corresponds to the path set in the Generated Sound Banks Folder in the Unreal Wwise Settings.

Note: The Root Output Path is relative to the Wwise project, while the Generated Sound Banks Folder is relative to the Unreal project's Content folder.

In the case of migrated Legacy projects, ensure that platform-specific SoundBank Folder settings do not point to a location within the Unreal project's Content folder.

Migrating External Sources

The implementation of support for external sources has changed dramatically in 2022.1. It allows for advanced users to implement their own systems for setting and tracking external sources. We also provide basic support with the WwiseSimpleExternalSourceManager, which uses Unreal Data Tables to track external source media and provides an API and blueprint functions to assign media to external source IDs.

The FAkExternalSourceInfo and FAkSDKExternalSourceArray structures are no longer used by this module. For each instance of an FAkExternalSourceInfo being created in a blueprint you will want to replace it with a WwiseSimpleExternalSourceManager::SetExternalSourceMedia blueprint node.

Afterwards, you can remove any references to them in your blueprints. You may also need to recompile blueprints containing PostEvent nodes that were linked to FAkSDKExternalSourceArrays.

For more in-depth information about how to work with External Sources in Wwise 2022.1, consult Using the Wwise Simple External Source Manager.

Partial Migration and Project Migration State

We recommend that you perform all migration operations at the same time. However, if you want to perform the steps one at a time, or perform certain operations manually, be aware of the following:

• Migrating assets will erase the SoundBank grouping information contained in Event and Auxiliary bus assets, rendering subsequent attempts to transfer SoundBanks from Unreal to Wwise ineffective. It will also make it impossible to transfer the "AutoLoad" setting from the AkAudioBank assets to the Events or Aux Busses which were grouped in them.
• Deleting deprecated assets and deleting AkAudioBank assets may require additional (non-Wwise) assets to be checked out, if they contained references to deleted assets.

Project migration state is mainly tracked using fields in the DefaultGame.ini file:

• bSoundBanksTransfered: Tracks whether the SoundBank Transfer operation has been performed.
• bAssetsMigrated: Tracks whether the Asset Migration operation has been performed.
• bProjectMigrated: Tracks whether the Project Migration operation has been performed

The migration process updates these settings depending on whether the corresponding migration operation succeeded.

Project migration state is also determined based on the contents of the Unreal project. If the project contains no AkAudioBank assets, no SoundBank migration is needed and the setting is updated automatically. Likewise, the option to delete deprecated assets is only presented if deprecated assets are found in the project.

Finishing the Migration

Once the migration is complete, you must regenerate your Wwise SoundBanks. This can be performed from the Wwise Picker or Build menu in Unreal, or directly in Wwise (now that SoundBank management has been returned to Wwise).

After SoundBank generation has succeeded, you should now be able to view your Wwise Project structure in the Wwise Picker and hear sounds when you Play In Editor.

Note: The following message might appear after migrating: Unable to load <Asset>_FOLDER with outer Package <Package> because its class does not exist.. These assets are no longer useful in 2022.1. You can delete any such assets if they still exist in your project (manually or during migration), but otherwise this message can be ignored.

Spatial Audio

Portals

• The AkPortalComponent functionality has been updated such that calls to OpenPortal and ClosePortal no longer 'stack'. This means a call to OpenPortal will immediately open the portal, and a call to ClosePortal will immediately close the portal. With the old functionality, multiple calls to OpenPortal would require the same number of ClosePortal calls in order for the portal to be closed. If you have code that relies on this functionality you should update it.

AkGeometry Components

• The default Mesh Type of the AkGeometryComponent was changed to Simple Collision to optimize adding such components in your map. After updating to 22.1, if you had AkGeometryComponent set to Static Mesh, you must set them again because they will have changed to Simple Collision.

PreDelay unit changed from seconds to milliseconds

• In the Unreal integration, the PreDelay reverb parameter was previously estimated in seconds. This value is now computed in milliseconds. Users must update RTPCs that receive the PreDelay value so that the RTPC ranges over milliseconds. For example, if the previous range of an RTPC mapped to PreDelay was 0.0 to 1.0 (seconds), the range must be changed to 0.0 to 1000.0 (milliseconds).

CollisionChannel Properties

• The underlying type for the CollisionChannel properties in AkSpatialAudioVolume and AkAcousticPortal, and the OcclusionCollisionChannel property in AkComponent has changed. This was done in order to be more explicit about what happens to existing objects when the project default collision channel is changed. If you have code that manipulates these properties directly either though Blueprint or C++, you will need to update the type and recompile.

Grouping Events into SoundBanks

Previously, you could group Events into SoundBanks by right-clicking assets and selecting Group into Sound Bank. This is no longer possible; however, you can achieve the same result by using User-Defined SoundBanks in the Wwise Authoring application.