XACT Project Collaboration Techniques

By Scott Selfon, Senior Audio Specialist

Advanced Technology Group (ATG)

Introduction

The Microsoft Cross-Platform Audio Creation Tool (XACT) provides some powerful tools that allow content creators to author, audition, and deploy their audio assets for Windows and Xbox 360 titles. But what happens when multiple artists need to work on the same title at the same time? This paper covers best practices for collaboration and includes a full discussion of the "shared settings" support that was introduced in the June 2006 Game Development Kit (GDK) and Xbox 360 Development Kit (XDK) releases.

Collaboration via Project Merge

When content creators work together on the same content simultaneously, they are exposed to the same challenges that programmers face in the sharing of source code: If two content creators modify the same asset at the same time, their changes need to be wholly atomic (that is, one set of changes cannot begin until another is completed). And there needs to be a process whereby changes can be merged and conflicts addressed. XACT provides several methods for solving these problems, but first and foremost, content creators should understand how to collaborate via Project Merge.

Project Merge is a feature of XACT that allows multiple projects to be joined into a single project, so that all of the content for a title (in particular the shared global settings file) can be built at once. This prevents issues such as conflicting object references, and mismatched dates and versions on content. Project Merge is not designed to replace a well thought-out process for multiple content creators authoring content at the same time; it does not provide elegant "merge" capabilities for handling conflicting data, but is rather a way to combine multiple projects into one project.

If content creators want to collaborate effectively, they should follow some work guidelines. First of all, multiple content creators should never work in the exact same project file (.xap) on separate machines at the same time. With each "save", they would trample each other's changes. And many objects are index-based, so even in a source management system, the kind of merges available in typical programming tools will not be successful.

If content creators are working on content that is completely independent and isolated, then they can work in separate projects and the projects can be merged later. There are two ways that projects can be merged:

1. The just-in-time method, performed via the command-line XACT project build tool, xactbld.exe, allows for multiple projects to be merged in one fell swoop so runtime content can be generated; no merged XACT project is saved out, and if any content conflicts arise, the build will simply fail.

2. Within the authoring tool, the user can click Import Project on the File menu. In this scenario, the entire project, including all of its sound banks, wave banks, variables, categories, etc. will be merged into the currently open project, which can then be saved like any other project (e.g. to a third location or over one of the two merged projects).

How Conflicts Arise in XACT

There are many potential scenarios where content can cause conflicts that are difficult to "merge" in any meaningful way. If two wavebanks in separate projects share the same name and path, for instance, one or both will have to be changed to allow them to coexist. And when the global settings in one project has a category or variable with the same name in another project, even if they are used for significantly different purposes, XACT has no easy way to distinguish these objects and thus the user will still be forced to change one or the other.

Additionally, all XACT projects have so-called "implicit" categories and variables—that is, categories and variables that are always present, such as the Default and Music categories, and the SpeedOfSound and Distance variables. If any of these objects' properties have been modified in one project but not the other, the conflict must be resolved when the projects are merged.

XACT as a Social Worker: Object Conflict Resolution

When objects are imported into a project and those imported objects conflict with existing objects, the user has to decide how XACT should resolve the conflicts. XACT typically offers you several options for conflict resolution when objects are imported that have namespace or property collisions:

1. The imported object can replace the existing object (which the GUI calls "merge").

2. The imported object can be ignored (e.g. the existing object remains intact).

3. The existing object can be renamed, and the imported object is added intact to the project. In this scenario, objects that referred to the existing object now begin to use the imported object, so behaviorally, this option is most similar to option 1 above.

If you try to merge two projects and both projects have a category named "Guns," you will see the Merge Conflict dialog (Figure 1). Merge corresponds to option 1 above; Ignore corresponds to option 2; and Rename corresponds to option 3. You can also cancel the merge by selecting Abort.

Figure 1.  The Merge Conflict Dialog

When addressing conflicting objects, note that individual properties of conflicting objects cannot be resolved separately (e.g. the volume property of one and the instance limiting property of the other). The XACT "Merge Conflict" dialog is designed more as a content validation and error checking mechanism: it is not meant to be a sophisticated merging tool. For that reason, sound designers and composers should minimize conflicts up front wherever possible; they should not rely on the Merge Conflict dialog to solve complicated object conflict scenarios.

Learning to Share with Shared Settings

Project merging is well and good for final content production, but there are some collaboration scenarios where project merging is not the best solution. First of all, content creators inevitably want to be able to continue to work on their content after a project has been merged. But after the projects are merged, they cannot easily be re-extracted into separate projects. Additionally, multiple content creators often need to work with overlapping data sets—for instance, there might be distance-related properties that all sound effects (which might span multiple sound designers' projects) should use. Or the game might have global categories for all sounds. In these scenarios, project merge is not going to be the ideal solution. A more desirable solution is to maintain shared objects in a single location where they can be edited, and then, when those objects are changed, the changes will be seen in all projects that use those objects. For this reason, XACT introduced the concept of importing and exporting shared settings in the June 2006 GDK and XDK releases. Shared settings correspond to all of the objects that would reside in the single, shared XACT global settings file (.xgs) at runtime. Specifically, shared settings can comprise all of the following objects:

• Categories

• Variables

• Runtime Parameter Control (RPC) Presets

• DSP Effect Path Presets

• Compression Presets (these settings actually end up being written to the wave banks that use them, but the presets themselves reside in the XACT project file and are thus "shared")

These settings can be exported from a project into a regular XACT project file at any time by clicking Export Shared Settings under the File menu. But more frequently, these settings will solely be imported by "client" projects rather than exporting back and forth. There are two generally recommended ways to manage working with shared settings:

1. A single shared settings project file, which all sound designers have access to.

2. One sound designer's project is considered the "master" project, and any requested changes to the shared settings must be communicated to her and performed in her project.

In a typical collaborative configuration for an XACT project (see Figure 2), a single shared settings file is used by three separate content creators, who can work independently, using the same or different global objects. The programmer then merges the three projects as part of the game's build process (typically using the xactbld.exe tool), which is used to create the actual content deployed in the title.

Figure 2.  Typical collaborative configuration for an XACT project

Shared settings can be synced as desired by clicking Import Shared Settings under the File menu, where you can specify any XACT project from which to read in the global settings. In contrast to the merge functionality (available by clicking Import Project under the File menu), only shared settings will be imported; wave banks and sound banks will not be brought into this project.

For convenience, the shared settings can be automatically read in on every project load. The Options command under the View menu displays a checkbox to enable this functionality:

The location of this project's shared settings file can be entered in the property frame for the project (which is displayed when the project node is selected in the project tree).

Figure 3.  Property frame entries for both the filename and path to the shared settings project.

The filename (and, unless the path is local or one of your frequently used "Network Places", the path as well) has to be manually typed in—though this is typically a one-time inconvenience. From then on, assuming the "Synchronize shared settings on project load" checkbox is ticked, whenever this project is loaded (or reloaded), it will attempt to bring in the shared settings, and display merge conflict information whenever the local settings vary from the shared settings.

Managing Updates to Shared Settings

Keeping shared settings in a separate file can help prevent inadvertent modification and subsequent conflicts during production. However, a well-defined process for making intentional updates to shared settings is still recommended. In addition to taking special care when editing content that multiple other pieces of content reference, content creators and programmers utilizing XACT shared settings projects (as well as all other XACT projects) should develop a good source management system, with history and versioning that will allow a title to track changes as they occur.

The content creator can edit a shared settings project file in several ways:

1. It can be manually opened and edited in the XACT authoring tool, just like any other XACT project. Again, if one content creator holds the "master" project (e.g. the shared settings live in a project that also has wave banks and sound banks), this is just a matter of opening her project, modifying the desired settings, and saving the project.

2. A new version of the shared settings can be exported with the intended modifications from one of the content creators' projects by clicking Export Shared Settings under the File menu. This file can then be checked in to replace the previous version. A few caveats here:

   1. Any time a new shared settings file is created, the sound designer should make sure they have the most recent shared settings (generally by performing an import of the existing shared settings project).

   2. No other sound designer should modify the shared settings file at the same time, to avoid the same kinds of overwrite merge issues discussed previously.

   3. Using a local project to update the shared settings file should only be performed if all of the global settings in this project came from the shared settings file. That is, if one sound designer has created an object like a compression preset or an RPC specific to their project, which is not intended for all sound designers to pick up, method 1 above should be used instead.

After shared settings are updated, all content creators should be notified to ensure that they import the new shared settings (either automatically the next time they open their project, or manually via the Import Shared Settings option).

Checking the Results

With resources now being shared across multiple projects, content creators editing those projects should develop a process for confirming that what they edited didn't "break the build." The process for editing and confirming that these edits did not break the build will be something along these lines:

1. Import shared settings into the project the content creator is going to work on. (As discussed, this can conveniently be performed automatically.)

2. Do some work, make some edits in the project.

3. Save the project locally.

4. Confirm that there are no content merge conflicts, by either:

   1. Running xactbld.exe, using the same script that the game uses. The tool alerts the user (and fails) if there are any conflicts.

   2. Import the shared settings again into the saved project. Conflicts would display the Merge Conflict dialog.

5. If there are any conflicts, either fix them in the local project or, if agreed and communicated with all other content creators, modify in the shared settings project.

6. Check in the project.

This process is analogous to the software development practice of test builds: developers code, build, and test their changes locally before they submit their changes to the main project repository. That way, developers can confirm that their changes will not adversely affect the work of others before they check in their changes.

Merge Conflict Gotchas

Shared setting import is intelligent enough to not complain about conflicts that don't impact any behavioral data (for instance, the saved "most recent" values for variables), but many other objects—such as runtime parameter controls and category volumes—can frequently cause unintended conflicts, which the Merge Conflict dialog can display in somewhat cryptic ways.

For instance, when working with runtime parameter controls, any slight adjustment that you make to a point on a curve will inevitably lead to a conflict during the next import, because there is no avenue for the fine tweaking needed to return the point to its exact previous position. Similarly, when auditioning content, if you make adjustments to category volumes, your adjustments will typically cause conflicts on import if the changes that you made are not returned to their previous positions. In both of these cases, you will typically want to select Merge to replace their edited values with the shared settings values.

Other potential difficulties with merges are the Distance and SpeedOfSound variables. There are known bugs where the maximum values for Distance and SpeedOfSound can become quite large in a project (generally upon project creation only). The content creator should ensure that the shared settings file has reasonable maximum values for these variables before that shared file is merged into other XACT projects and before creating runtime parameter controls that use the Distance variable. If not, scaling of RPC curves relating to distance may be inadvertently adjusted when a shared settings merge occurs.

Summary

XACT project merge and shared settings allow for a crucial component in typical large-scale game productions: collaborative production between multiple audio content creators. Despite these project collaboration techniques, there are other opportunities for data conflicts to arise, so well-defined processes need to be established for:

1. Updating the shared settings file: Ensure only one person modifies the file at a time, communicate all modifications to avoid later surprises, and use a good source control system with versioning and history to be able to back out unintended changes.

2. Updating projects when shared settings are modified: The option to automatically import shared settings whenever a project is opened is typically the most convenient way to achieve this.

3. Managing project merge for final asset build and delivery: Audio content creators should still ensure that naming conflicts between their own objects are avoided. And if "global" settings that are actually local to their project are used, ensure that conflicts won't arise with another content creator's settings.

Shared settings should be managed as much as possible outside of XACT, with good communication, policy, and "ownership" of all objects well defined. The job of the authoring tool is primarily to catch those situations where a miscommunication has occurred, and allow the content creators to correct it. Using processes and policies similar to software development "test builds" and other data management techniques, many artists should be able to work on a single project successfully in parallel.