Managing project files with a source control plug-in

Wwise's open architecture makes it easy for you to integrate your source control software by using or creating a Source Control plug-in. The Source Control plug-in creates a link between Wwise and your source control software so that you can manage your files and perform source control functions, such as check in and check out, directly in Wwise.

Because each source control system works differently, the specific functions available and the workflow you adopt depend on the system with which you are working.

To help you get started, Wwise comes with two fully functional sample Source Control plug-ins for the Perforce® and Subversion software configuration management systems. Perforce and Subversion both use the copy-modify-merge model as opposed to the lock-modify-unlock solution. In this model, each member of the team reads the repository or depot and creates a client workspace, which is a directory that contains a personal working copy of the files and/or project on their workstation. This allows each member of your team to work in parallel, modifying their own private copies. When ready, each member can merge their private copies together into a new, final version. If there are conflicts, the version control system assists you with the merging, but ultimately you are responsible for resolving any issues correctly.

If you are using another source control management system, you can create your own Source Control plug-in for Wwise. For information on creating and integrating your own Source Control plug-in, refer to How to Create a Source Control Plug-in DLL in the SDK documentation.

You can select and configure the Source Control plug-in in the Project Settings dialog. For more information, refer to Configuring source control plug-ins.

When using a source control plug-in, a number of different source control functions are available directly in Wwise. For example, when using the Perforce plug-in, you can perform the following source control operations from within Wwise:

Get latest version to update your working copy by retrieving the latest version of the file from the depot.
Submit changes to send pending files to the Perforce server for processing.
Check out to make the working copy of the depot file in your client workspace.
Lock to lock a file so that other clients can't submit their working copies of the file to the server.
Unlock to unlock a file so that other clients can submit their working copies of the file to the server.
Mark for add to add a file to the depot. When a file is marked for add, it is added to a changelist and then must be submitted to the depot.
Mark for delete to delete a file from the depot. When a file is marked for delete, it is placed in a changelist and then must be submitted to the depot where it is deleted.
Move to move a source file between folders within the Originals directory.
Rename to rename a file in the depot.
Revert changes to discard the changes you have made to a file in your client workspace.
Resolve to reconcile the differences between two revisions of a file.
Diff to compare the file in your client workspace with the file in the depot.
File History to display a file's revision history.

	Note
	A list of similar source control functions exists for the Subversion plug-in.

Not only will you have access to these source control commands in Wwise, but special icon overlays are displayed in the Project Explorer to help you quickly identify the status of your Work Unit files. The following table displays the icon overlays used, for example, in the Perforce Source Control plug-in.

Overlay Icon

Name

Description

Normal (not checked out)

File is up-to-date and not checked out by anybody.

Marked for add

Moved

Files have been marked for add to the Perforce depot or has been moved with the move/add status.

Checked out (Open for Edit)

Files have been checked out from the Perforce depot.

Checked out by another user

Files have been checked out by another user in your team.

Concurrently checked out

Files have been checked out by you and by another user in your team.

Outdated (not latest revision of file)

A more recent revision exists on the server. You can get the latest version of the file.

	Note
	The icons “Checked out by another user,” “Concurrently Checked out” and “Outdated” are only available with the Perforce Source Control plug-in.

Supported Perforce/Subversion versions

Before using either of the Source Control plug-ins, review the following information to make sure that your version of Perforce or Subversion is compatible with the Source Control plug-in.

Perforce: The Perforce Source Control plug-in was built using the Perforce SDK version 2022.1, but should work with most versions of the Perforce servers. If you are using a different version of Perforce that is not compatible with the Source Control plug-in, you can use the sources in the Wwise SDK to rebuild the plug-in with the version you are using. For more information about the Perforce plug-in, refer to the Wwise SDK documentation.
Subversion (deprecated): The Subversion Source Control plug-in has been deprecated since Wwise 2023.1 and will no longer be updated.
The Subversion Source Control plug-in was built using Subversion version 1.8.5. If you are using a different version of Subversion that is not compatible with the Source Control plug-in, you can use the sources in the Wwise SDK to rebuild the plug-in with the version you are using. For more information about rebuilding the Subversion plug-in, see the Wwise SDK documentation.
Subversion's bin folder, which by default is located in C:\Program Files\Subversion\bin, must be in the system's PATH environment variable. Subversion installers normally add it to the PATH, but if Subversion is installed manually from the ZIP file mentioned above, for example, then you must add the bin folder to the PATH manually.

The following sections describe how to manage your assets using a Source Control plug-in. Although they primarily focus on the Perforce Source Control plug-in, a similar workflow exists when using Subversion.

	Tip
	Perforce, Subversion, and other Platform SDK updates are announced in our SDK Documentation's Release Notes.

Setting up your project files in Perforce

Before you can start using the Perforce Source Control plug-in, you or your system administrator need to do the following:

Install and set up the client version of the source control management software on the workstation of each person in your team.
Configure a client workspace on the workstation of each person in your team.
Get the latest version of the project files from the depot and save them in your client workspace.
Select and configure your Source Control plug-in in Wwise.

For more information on installing and configuring Perforce, contact your system administrator, or consult the Perforce documentation.

You can select and configure the Source Control plug-in in the Project Settings dialog. For more information, refer to Configuring source control plug-ins.

Adding files to Perforce

Before you start working in a project, you should add your project files and audio sources to the depot or repository. Adding files to Perforce consists of the following two steps:

	Note
	When you create new Work Units or import new audio files into your project, you are prompted to mark these new files for addition to Perforce.

To add files to the changelist:

From the menu bar, click Project > File Manager.
The File Manager opens.
Switch to one of the following tabs:
- Work Units, to add Work Units to Perforce.
- Sources, to add audio files to Perforce.
Select the file or files that you want to add to Perforce.
Right-click the selected project file(s) and select Mark for add from the menu.
The Process Log dialog opens showing that the selected file has been added to the changelist or “opened for add” and is ready to be submitted to the depot.
Click OK to close the Process Log.
The status of the files is set to “add.”
Click Close to close the File Manager.
In the Project Explorer, the project files now have the Marked for add overlay icon.
At this point, the files have only been added to the changelist. You need to submit the changelist to check the new files into the depot. For more information on submitting files to the depot, refer to Submitting your changes to the Perforce depot.
Save your project.

Checking out files from the Perforce depot for editing

Before editing the files in your project, you should check them out first to make sure that you have the latest version of the files in your client workspace. When you check out files in Perforce, the files become writable. This means that you will be able to save the changes you made to a file.

By default, Perforce does not do an exclusive check out, which means that other members of your team may be working on the same files at the same time. Communication is key to avoid merge conflicts that can be time-consuming and difficult to resolve.

To check out files for editing:

From the menu bar, click Project > File Manager.
The File Manager opens.
Switch to one of the following tabs:
- Work Units, to add Work Units to Perforce.
- Sources, to add audio files to Perforce.
Select the file(s) that you want to open for edit.
Right-click one of the selected project files and select Check out from the menu.
The Process Log dialog opens showing that the file has been checked out or “opened for edit.”
Click OK to close the Process Log.
The status of the files is set to “edit”.
Click Close to close the File Manager.
In the Project Explorer, the project file now has the Checked out overlay icon.

Note

When the project setting Prompt for checkout on edit is enabled, if you make changes to files that are not checked out, the Pending Source Control Operations dialog will open. Select the Check out modified files option and click OK to check out the files that have changed. Selecting Cancel will undo the changes that triggered the dialog. If you deselect the Check out modified files option and click OK, you will be allowed to proceed with your modifications, but will be prompted again to checkout the files when you attempt to save your project. Refer to General Tab for more information.

Submitting your changes to the Perforce depot

If you are finished working with a particular file or want others in your team to have access to your changes, you can submit the file back to the depot. It is very important that you give a detailed description of the changes you made so that you and others fully understand the extent of the changes made to the files. These comments can help when dealing with conflicts.

When you submit your files back to the depot, Perforce merges the changes you made with the file already in the depot. If any conflicts exist, they must be resolved before a file can be successfully submitted to the depot.

To submit your changes to the depot:

From the menu bar, click Project > File Manager.
The File Manager opens.
Click the Submit Changes button and then one of the following options:
- Work Units - Sends only the Work Units to the server for check-in.
- Sources - Sends only source files to the server for check-in.
- All - Sends all pending files (Work Units and source files) to the server for check-in.
The Submit Changes dialog opens.
If you don't want specific files to be checked-in to the server, clear the selection for those files and then click OK.
Right-click one of the selected project files and select Submit Changes from the menu.
The Description dialog opens.
Type a detailed description of the changes you made to the files.
Note
To submit changes using double byte characters in the description, such as with Japanese or Chinese characters, set the P4 system environment variable P4CHARSET to utf8.
If you want to continue editing the files again immediately after submitting your changes, select the Check out file(s) after submit option.
Click OK.
The Process Log dialog opens showing that the files have been checked in or “submitted.”
Click OK to close the Process Log.
The status of the file is set to “normal.”
Click Close to close the File Manager.
In the Project Explorer, the project files will have the Checked in overlay icon, unless you selected the Check out file(s) after submit option.

To submit individual files to the depot:

From the menu bar, click Project > File Manager.
The File Manager opens.
Switch to one of the following tabs:
- Work Units, to add Work Units to Perforce.
- Sources, to add audio files to Perforce.
Select the file or files that you want to submit.
Right-click one of the selected project files and select Submit Changes from the menu.
The Description dialog opens.
Type a detailed description of the changes you made to the files.
Note
To submit changes using double byte characters in the description, such as with Japanese or Chinese characters, set the P4 system environment variable P4CHARSET to utf8.
If you want to continue editing the files again immediately after submitting your changes, select the Check out file(s) after submit option.
Click OK.
The Process Log dialog opens showing that the files have been checked in or “submitted.”
Click OK to close the Process Log.
The status of the file is set to “normal.”
Click Close to close the File Manager.
In the Project Explorer, the project files now have the Checked in overlay icon, unless you selected the Check out file(s) after submit option.
Tip
You can also submit changes to the Perforce depot by right-clicking a Work Unit in the Project Explorer and selecting Source Control > Submit Changes.

Comparing your files with the files in the Perforce depot

You can compare or diff a file in your client workspace with the latest revision of the file in the depot to determine if there are differences between the two files. Before diffing a file, you should save your project so that you are using the latest version of a file for the diff.

To compare your file with a file in the depot:

From the menu bar, click Project > File Manager.
The File Manager opens.
Right-click the Work Unit file you want to compare, and select Diff from the menu.
The differences between the two files are displayed in the default Perforce diff viewer.
Review the differences between the two files.
When you are finished reviewing the differences, close Perforce to return to Wwise.

Moving source files within the Originals folder using Perforce

You can move the source files within your project's Originals folder, but before doing so you should make sure that no other team members are working on the files. If you do move a file while others have the file checked out, they will run into problems when they try to submit their changes to the depot.

When Perforce moves a file, it opens the current file for delete and creates an exact copy of the file in the new location. These files are not automatically updated in the depot, so, after the move is complete, you must submit the changelist to the depot. Before you can move a file, it must be checked into the depot.

	Note
	You must save your project before moving the source files in the Originals folder.

To move files between folders within the Originals directory:

Save your current project.
Do one of the following:
- From the menu bar, click Project > File Manager.
- Press Shift+F1.
The File Manager opens.
Switch to the Source Files tab.
Select the file(s) you want to move.
Right-click the selection and select Move from the menu.
The Browse For Folder dialog opens.
Navigate through the folder structure and select the folder where you want to move the file.
Note
If you want to create a new folder, select the parent folder, click the Make New Folder button, and then specify a name for the folder.
Click OK to move the file to the new folder.
The Process Log dialog opens showing that a new copy of the file has been added to the specified folder using the branch command and the original file has been opened for delete.
Click OK to close the Process Log dialog.
Select both entries in the list: the branch and deletion.
Right-click the selection and select Submit Changes from the menu.
The Description dialog opens.
Type in a useful description and then click OK.
The Process Log opens showing that both pending operations were submitted to the depot.
Click OK to close the Process Log.
The file now resides in the specified folder.

Renaming files when using Perforce

You can rename a file in your project, but before doing so you should make sure that no other team members are working on the file. If you do rename a file while others have the file checked out, they will run into problems when they try to submit their changes to the depot.

When Perforce renames a file, it opens the current file for delete and creates an exact copy of the file with the new name. These files are not automatically updated in the depot, so after the rename is complete, you must submit the changelist to the depot. Before you can rename a file, it must be checked into the depot.

	Caution
	Do not rename the Default Work Units as they are critical to the project.

To rename a file in your project:

From the menu bar, click Project > File Manager.
The File Manager opens.
Right-click the Work Unit file you want to rename, and select Rename from the menu.
The Rename File dialog opens.
In the Name field, type the new name for your file.
Click OK.
The Process Log dialog opens showing that a copy of the file was created with the new name using the branch command and the old file was opened for delete.
Click OK to close the Process Log.
The status of the old file is set to “delete,” and a new file has been created with the status set to “branch.”
Select both the old and new files.
Right-click and select Submit Changes from the menu.
The Description dialog opens.
Type in a useful description of the change and click OK.
The Process Log opens showing the deletion of the original file and the addition of the newly renamed file.
Click OK to close the Process Log.
Click Close to close the File Manager.
The Project dialog opens prompting you to reload the latest version of the project because changes have been made externally to the project.
Click Yes.
The latest version of the project is loaded and the file has been renamed.

Deleting files from your project when using Perforce

When you no longer require certain files in your project, you can delete them. When you delete a file in Perforce, you must first open it for deletion and then submit the changelist to the depot. You should always save your project before deleting files to prevent losing the changes you made since the last save.

	Caution
	Do not delete the Default Work Units as they are critical to the project.

To delete a file from your project:

From the menu bar, click Project > File Manager.
The File Manager opens.
Select the file(s) that you want to delete.
Right-click one of the selected project files, and select Mark for Delete from the menu.
A message is displayed prompting you to confirm the file deletion.
Click Yes.
The Process Log dialog opens showing that the file(s) has been opened for delete.
Click OK to close the Process Log.
The status of the file is set to “delete.”
Click Close to close the File Manager.
The Project dialog opens prompting you to reload the latest version of the project since changes have been made externally to the project.
Click Yes.
The latest version of the project is loaded, and the file has been deleted.
At this point, the file has only been added to the changelist and is marked for delete. You need to submit the changelist to delete the file in the depot.

Saving your project when using Perforce

As long as you have checked out all the project files you modified, you won't have any problems saving your project. However, if you made changes to files that are not checked out, Wwise will prompt you to checkout these files before it can save the project.

To save a project:

Do one of the following:

From the menu bar, click Project > Save.
Press Ctrl+S.

Wwise attempts to save all files in the project. If you made changes to files that are not checked out, the Pending Source Control Operations dialog opens.

	Note
	If the project setting Prompt for checkout on edit is enabled, the Pending Source Control Operations dialog also opens as soon as you modify a file that is not checked out. Refer to General Tab for more information.

Select the Check out modified files option to check out the files that have changed so that Wwise can save them.
Click OK.
Wwise checks out the necessary files and saves the project.

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.

Get started with Wwise

	Note
	To submit changes using double byte characters in the description, such as with Japanese or Chinese characters, set the P4 system environment variable `P4CHARSET` to `utf8`.

	Note
	To submit changes using double byte characters in the description, such as with Japanese or Chinese characters, set the P4 system environment variable `P4CHARSET` to `utf8`.

Wwise Help