Version
menu_open

Migrating your projects

When you are ready to upgrade to a new major version of Wwise, you must follow a coordinated protocol to ensure that your projects created in an earlier version are migrated smoothly to the later version. The goal is to avoid putting any aspect of your game at risk, so you must examine the changes in the new version and selectively and systematically implement any modifications to your game code.

The protocol for upgrade and migration can vary depending on the following conditions:

  • Projects under source control: The project must be checked in at key points.

  • Multiple users: The Wwise upgrade, project migration, SDK upgrade, and game code update must be completed on a local system before multiple users can upgrade Wwise on their workstations.

  • Integrated game project: The game code must be modified as specified in the migration notes.

We strongly recommend that a migration team, composed of one or two designated individuals, perform the following tasks on a local system first:

After the migration team has carried out these tasks, you can proceed with:

For an overview of the upgrade and migration workflow for a project under source control, consult the following chart:

Preparing your projects for migration

Before you upgrade to a new version of Wwise, you must prepare your projects for the upgrade, particularly if your Wwise project has been integrated into a game. Repeat the procedures in the following sections for all projects that you want to migrate.

The migration team must carry out the following tasks to prepare projects to be migrated to the latest version.

  1. Commit all projects:

    1. For projects under source control, ask the other members of your team to commit all their changes.

      This will avoid merge problems later.

  2. Get the latest version of all projects to be migrated:

    1. For projects under source control, import all the projects locally to your system.

    2. Ensure that all project files have read and write permissions.

      For projects under source control, you might need to check out the project file (WPROJ) and all Work Unit files (WWU) from the various subfolders.

  3. Validate projects to be migrated:

    1. In the current version of Wwise, open each project that you plan to migrate and save.

    2. If the Project Load Log dialog displays messages and suggested fixes, accept these fixes, save the changes, and close the project. Repeat this procedure until there are no such messages. Your goal is to remove any project errors to simplify the upgrade.

  4. Tag projects to be migrated:

    1. For projects under source control, commit and tag or label this as the last version of the project prior to the upgrade.

      Committing the project at this point records all changes made prior to the migration process. Any other changes will be directly associated with the migration in the source control history.

Upgrading Wwise and migrating your project

The project migration process has been designed to ensure that your migrated project very closely approximates the sound of your previous project despite the significant changes made to the feature set. For more information about these changes, refer to the current version of the Wwise release notes, as well as the corresponding Important Migration Notes linked within.

We recommend that the migration team migrates the Wwise project to the new Wwise version on a local system first. All other users must not modify the project until the migrated project has been tested and then committed by the migration team.

[Note]Wwise Versioning

Depending on the types of changes made to Wwise from one version to another, your projects might not need to be migrated when upgrading to a new version.

  • Major Release: If the year number of the version or the first decimal point after the year changes, this is a major release likely involving several major changes. For example, 2019.1 and 2019.2 were both major releases. When opening a project saved in the former version of Wwise with the latter version, Wwise will prompt you to migrate the project. If you accept, it's no longer possible to open that project with the 2019.1 version.

  • Minor Release: If the year number of the version or the first decimal point after the year remain the same, but there is iteration of an additional decimal point, then this is a minor release. For example, 2019.1.3 and 2019.1.4 were both minor releases with only a few changes. When opening a project saved in the former version of Wwise with the latter version, no migration is necessary.

  1. Upgrade Wwise:

    1. Upgrade Wwise on your local system as described in Installing Wwise and Component Packages.

  2. Migrate a project to the new version:

    1. Verify that all files in the current Wwise project have read and write status.

    2. Perform a backup of the project and store the backed up project in another folder on your system or network. The project will be backed up automatically by Wwise, but it is good practice to create your own backup as well.

    3. Open the new version of Wwise. In the Project Launcher dialog that opens, select the project you plan to migrate.

      The Project Migration dialog opens prompting you to migrate the project to the later version of Wwise.

      [Note]Note

      The Migration dialog is only displayed when significant changes have been made to the project file between versions. If your project does not require migrating, Wwise will skip to the next step in the migration process.

    4. Click Migrate.

      Wwise migrates the project. After the project is migrated, Wwise checks to see if the existing project cache folder is compatible with the current version of Wwise. If not, Wwise deletes the project cache folder. When the project cache is deleted, the following message is displayed.

    5. Click OK.

    6. From the Wwise menu bar, click Views > Utilities > Logs. The Logs view opens.

    7. In the Logs view, select the Project Load tab. The Project Load log displays messages related to the migration and indicates if any files were created for the new version of Wwise.

      [Note]Note

      This information is stored in the file named projectname.wproj_migration.log in the project folder. If needed, you can click Copy to clipboard to save this information for later reference.

    8. If you are using source control, add any new files that were created during the migration process to your source control system.

    9. Close the Logs view.

  3. Generate SoundBanks:

    1. Generate SoundBanks for migrated projects that will be used for testing.

Upgrading the Wwise SDK and updating game code

In addition to upgrading the Wwise authoring application, carry out the following tasks to upgrade the Wwise SDK and update the game code.

  1. Upgrade the Wwise SDK:

    1. Confirm that your system meets the Wwise SDK Platform Requirements.

    2. Optionally, uninstall the earlier version of the Wwise SDK.

      It's good practice to also manually remove any temporary files created by the sample C++ projects.

    3. Install the later version of the Wwise SDK. Refer to Install Wwise through the Launcher and select SDK (C++) under Packages.

    4. Verify that the WWISESDK environment variable points to the installation folder of the later version. (See Working with Multiple Versions of the Wwise SDK for more information on setting the environment variable.)

  2. Update the game code for the later version of the Wwise SDK:

    1. Refer to the migration notes in the Wwise SDK documentation to familiarize yourself with the modifications you will be making.

    2. To migrate the game code, you must port the existing functionalities of the C++ project from the earlier version of the Wwise SDK to the later version. This task might include modifying or refactoring code in different modules. Changes to the following modules might need to be addressed to update the game code:

      • Sound Engine

      • Memory Manager

      • Stream Manager

      • Communications Module

      [Note]Note

      To ensure that your game is not adversely affected by some of the new features in the later version, we recommend you first upgrade the components that you need for your game. After you are satisfied that your game is stable, you can integrate the new features, if needed.

    3. Modify the code as required.

      [Tip]Tip

      It's good practice to rebuild the C++ project often when you are modifying the code.

  3. Build your game.

Testing

Before you can complete the upgrade and migration, you need to test the migrated game. To augment any testing protocol you might already use at your workplace, we have included a procedure. We recommend these tests are carried out by the migration team in both the Wwise authoring application and the game.

Test the migrated game project, then commit:

  1. In the game, verify the sound and audio behavior. This can include verifying the following:

    • Basic audio playback.

    • Behaviors affected by changes you have made to the code.

    • Platform behaviors.

    • Communication with the Wwise authoring application.

  2. Commit your migrated Wwise project and the code changes to source control.

After the testing is complete and you are satisfied with the results, you are ready to instruct other users to upgrade to the latest version of Wwise.

Upgrading Wwise on all workstations

After Wwise has been upgraded, the project has been successfully migrated, the SDK has been upgraded, game code changes have been made, and testing is completed on a local system, you are ready to advise other users to upgrade Wwise on their workstations.

This upgrade must be carried out on all the workstations where Wwise is being used, including the following:

  • Build machines

  • Sound designers' workstations

  • Developers' workstations

  • Any other Wwise user workstations

Ensure you have identified all the workstations that run Wwise so that you can upgrade them all.

Upgrade Wwise on all workstations:

  1. Optionally, uninstall all Wwise components. This might include:

    • Wwise authoring application

    • Wwise SDK

    For more information on uninstalling, refer to Uninstalling Wwise.

    [Note]Note

    It is not necessary to uninstall Wwise. If required, you can maintain several builds and versions of Wwise on the same workstation.

  2. Install the later version of Wwise. This might include:

    • Wwise authoring application

    • Wwise SDK

    • Wwise Game Simulator

    For more information about installing, refer to Installing Wwise and Component Packages.

Access the migrated Wwise project on all workstations:

  1. After you have installed the later version of Wwise, retrieve the migrated Wwise project.

  2. Open Wwise.

    The End-User License Agreement is displayed.

  3. Read the agreement and if you accept, click Accept.

    The Project Launcher window opens.

  4. Open the migrated project.

    [Note]Note

    If some users have Work Units in the Wwise project that have been saved locally and are not under source control, a message appears prompting them to accept that these Work Units will be migrated when the project opens in the new version of Wwise.

    Before the project can be loaded, Wwise checks to make sure that the project cache folder is compatible with the current version. If not, Wwise deletes the project cache folder. When the project cache is deleted, the following message box is displayed.

  5. Click OK.

    After the cache is deleted, the project is loaded into Wwise.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise