14. 使用源代码控制

源代码控制（也称为版本控制）是一种管理和跟踪对文件集合所做更改的方法。Perforce、SVN 和 Team Foundation Server 等源代码控制系统有很多用途，从回滚到项目的早期版本到促进用户之间的协作，并广泛应用于整个游戏行业。

FMOD Studio 与几个最常见的源代码控制系统集成，并且可以通过脚本支持额外的源代码控制系统集成。本章介绍如何使用这些集成。

本章假定您已经在计算机上安装了源代码控制系统并且可以访问带有源代码控制存储库的服务器。如果尚未安装源代码控制软件或获得对存储库的访问权限，请查阅源代码控制软件的文档以了解如何操作。

有关创建自己的源代码控制集成脚本的示例，请参阅 FMOD 安装的“脚本”文件夹中的 perforce.sc.js 和 svn.sc.js 示例脚本，以及脚本一章。

14.1 将项目添加到存储库

在为 FMOD Studio 项目利用 FMOD Studio 的源代码控制集成之前，必须将项目添加到源代码控制存储库。

一个 FMOD Studio 项目只需添加到存储库一次。可通过 FMOD Studio 或外部程序添加。如果项目已经在源代码控制存储库中，则可跳过本教程，直接开始获取项目的本地副本，如本章的获取项目的本地副本一节所述。

在将 FMOD Studio 项目添加到存储库之前，请确保其资源文件夹和已构建数据库输出目录属性设置正确。

• 对于一个项目的所有用户来说，已构建数据库输出目录是相同的，因此应该设置为所有协作者都同意的相对路径或绝对路径后期可以更改事件库构建目录，但这样做将更改所有用户的设置。
• 如果团队中的任何成员希望使用 FMOD Studio 项目文件夹之外的资源文件夹，则团队的所有成员都应该使用 FMOD Studio 项目文件夹之外的资源文件夹。这是为了防止项目文件夹的资源子目录中的文件膨胀存储库中项目的大小。每个用户都可以设置不同的相对路径或绝对路径来设置其资源文件夹，只要每个路径都在 FMOD Studio 项目文件夹之外即可。

将打开的 FMOD Studio 项目添加到存储库:

1.单击“编辑 > 首选项...”
2.选择源代码管理选项卡
3.从“集成类型”下拉列表中选择源代码管理解决方案

可以使用 P4V、Helix、Helix Core 或 tortoiseSVN 等外部工具将项目添加到存储库。如果这样做，请务必从存储库中排除以下文件:

• FMOD Studio 项目的文件夹“.user”、“.cache”和“.unsaved”子目录（如果存在）。这些文件夹仅在需要时创建，因此并非存在于所有 FMOD Studio 项目中。它们也可能从视图中隐藏，具体取决于操作系统的设置。
• 如果决定不包含 FMOD Studio 项目的已构建事件库文件。在获取本地项目后，可在本地构建事件库文件。
• 如果决定不包括 FMOD Studio 项目的资源。资源必须存在于 FMOD Studio 项目已知的位置才能使用，例如单独的文件夹。

未能从存储库中排除这些文件将不必要地增加服务器上项目的大小，并可能导致用户设置丢失、项目验证错误和其他错误。

14.1.1 将项目添加到 Perforce 存储库

只要项目位于本地磁盘上现有的 Perforce 工作区内，就可以完全通过 FMOD Studio 将项目添加到 Perforce 存储库。

1. 打开首选项对话框并单击源代码管理选项卡。

   

2. 单击“集成类型”下拉菜单，然后选择“Perforce”。

   

3. 根据需要输入服务器、主机、用户和密码详细信息。

   如果可能，现有的 Perforce 环境设置可用于自动填写服务器和用户字段。这不包括 Perforce 密码。

   或者，可以手动填写详细信息。

   大多数工作区不需要特定的主机。输入所需主机的名称，否则留空。

   如果 Perforce 服务器的 IP 地址、端口、主机、用户名或密码未知，请联系 Perforce 管理员。

4. 从“客户端工作区”下拉列表中选择保存 FMOD Studio 项目的工作区。

   输入所需的详细信息后片刻，“客户端工作区”下拉菜单中会出现可用工作区列表。

   更新列表可能需要几秒钟，具体取决于网络速度。

5.决定资源和/或已构建事件库是否要包含在存储库中。

![启用资源和已建项目库源代码控制集成复选框](images/ perforceAssetAndBankInclusionCheckboxes.png)

默认情况下，包括资源和已构建事件库。将项目的资源包括在存储库中允许这些资源从源代码控制中受益，但也会增加存储库的大小。如果团队计划将其资源存储在共享网络驱动器或类似的共享位置，则禁用资源的源代码控制集成可能会很有用。

1. 关闭首选项对话框。

2. 选择“文件 > 源代码管理 > 同步最新、合并和提交...”

   

   同步和合并项目是不可撤销的。单击“是”将自动保存项目并清除撤消堆栈，就像关闭并重新打开 FMOD Studio 一样。这是在提交项目之前撤消或更改的最后机会。

   如果确定要提交更改，请单击“是”。

8.提交项目。

片刻之后，出现提交对话框。“更改”选项卡显示要提交的项目的每个元素的列表。在对话框的底部是一个标记为“在此处输入描述”的字段和一个标记为“提交”的灰色按钮。

![提交对话框](images/submitDialog.png)

“更改”选项卡显示将要提交到存储库的所有内容。在这种情况下，这意味着整个项目。

“挂起”选项卡可用于排除提交项目的特定部分。第一次将项目提交到存储库时，不需要使用该选项卡。有关“挂起”选项卡的信息，请参阅本章的[提交更改](using-source-control.html#committing-changes)部分。

无论在“在此处输入描述”字段中键入什么，都将用作 Perforce 中更改列表的描述。最佳做法是编写一个简单易懂的描述，无需其他上下文即可理解。

9.单击“在此处输入描述”字段并键入“将 FMOD Studio 项目添加到存储库”。

10.单击提交按钮。

出现一个进度对话框，并开始填充。一旦达到 100%，就会消失。根据项目的大小和网络的速度，可能需要几分钟才能完全填满。

该项目现已添加到 Perforce 存储库。

14.1.2 将项目添加到 SVN 存储库

目前无法通过 FMOD Studio 将项目添加到 SVN 服务器。相反，这需要通过命令行或用户界面（如 tortoiseSVN）手动完成。请参阅所选的 SVN 解决方案的文档，了解如何执行此操作。

确认项目已经添加到 SVN 服务器后，项目就可以进行加载。

14.2 获取项目的本地副本

将项目添加到存储库后，计算机上需要有该项目的本地副本才能对其进行处理。

获取源代码管理存储库中已有项目本地副本的最简单方法是使用 FMOD Studio 的“文件 > 源代码管理 > 浏览项目...”菜单项，并按照以下特定于集成的说明进行操作。

请注意，只需要在所使用的每台计算机上使用“文件 > 源代码管理 > 浏览项目...”一次即可打开项目。这是因为以这种方式打开项目会自动创建该项目的本地副本，随后可以通过选择“文件 > 打开...”来打开该副本。使用“文件 > 打开...”打开项目比使用“文件 > 源代码控制 > 浏览项目...”打开项目稍快。

此外，也可使用外部工具（例如 P4V 或 tortiseSVN）获取项目的本地副本。如果这样做，将需要手动设置本地副本的源代码控制设置。有关如何使用外部工具获取源代码管理存储库中文件夹本地副本的详细信息，请参阅该工具的文档。

14.2.1 从存储库获取项目的本地副本

在创建本地副本之前，如果使用的是 Perforce，那么将需要一个用于存储项目的存储库的本地工作区。如果还没有本地 Perforce 工作空间并且不知道如何创建，请咨询 Perforce 管理员。一旦拥有本地 Perforce 工作区，就可以使用 FMOD Studio 在相应的 Perforce 库中制作任何 FMOD Studio 项目的本地副本。

如果使用的是 SVN，则不需要在接下来的步骤之前进行任何设置。

1. 选择“文件 > 源代码管理 > 浏览项目”

   打开对话框出现。从集成下拉菜单中选择您选择的源代码控制解决方案，默认设置为 Perforce。用于输入连接设置属性的字段显示在下拉菜单下方。

   
   

   服务器和用户字段可能已经填写。FMOD Studio 自动检测打开的 Perforce 连接，并在可能的情况下使用这些连接的详细信息来填写这些字段。尽管如此，FMOD Studio 无法检测到您的 Perforce 密码，如果您使用多个打开的 Perforce 连接，则可能无法选择您想要的连接。

2. 在服务器和用户字段中输入想要连接的服务器和想要连接的用户。

   如果您不知道源代码控制服务器的 IP 地址和端口，请向网络管理员询问。

3. 如果源代码管理服务器需要密码，请在“密码（可选）”字段中输入密码。

   一些源代码控制服务器不需要密码，但大多数都需要。 如果不知道所连接的用户的密码，请联系源代码管理系统管理员。

4. 如果使用 Perforce，并且工作区位于本地计算机上，请将主机字段留空。如果工作区位于您正在使用的机器以外的机器上，请输入该机器的 I.P. 地址和侦听端口到主机字段。

   输入完连接详细信息后，可以继续操作。

5. 单击对话框底部的“查找”按钮。

   当 FMOD Studio 搜索源代码控制库时，会出现一个进度对话框。片刻之后，对话框会显示一个浏览器，其中填充了该库中的项目。

   

   此浏览器可用于选择要创建本地副本并加载的特定 FMOD Studio 项目。如果想要的项目没有显示在浏览器中，则可能不在 Perforce 仓库中，或不在与本地工作区对应的仓库的某个部分。

6. 选择要为其创建本地副本的 FMOD Studio 项目，然后单击对话框底部的“打开”按钮。

   使用 Perforce 时，FMOD Studio 在本地工作区中创建所选项目的本地副本，然后加载该项目。

   使用 SVN 时，FMOD Studio 会提示选择项目要保存到的本地位置，然后加载项目。

这样，就创建并加载了 FMOD Studio 项目的本地副本。项目的源代码控制设置已自动设置，因此您将能够开始处理项目并立即提交所做的更改。

状态栏更新以显示“在线”图标。只要有效连接可用，此图标就会出现在状态栏中。如果有效连接不可用，可能是因为源代码控制设置不正确或与远程存储库的连接已丢失，则会显示“离线”图标。

将来，您将能够按照本章下面的加载项目部分所述加载项目。

此外，也可通过 P4V 或 SVN GUI 应用程序（如 TortoiseSVN）向 P4/SVN 命令行发出 p4 sync 或类似命令来获取项目文件夹的本地副本。如果项目已正确添加到存储库，以这种方式获取项目的本地副本与通过“浏览项目...”获取项目的不同之处仅在于这样做不会自动设置项目的源代码控制设置。

14.3 加载项目

加载使用源代码管理的 FMOD Studio 项目与加载任何其他 FMOD Studio 项目没有什么不同: 选择“文件 > 打开...”，然后使用随后出现的对话框导航到并选择要加载的 FMOD Studio 项目。如果您正在使用的机器上没有 FMOD Studio 项目的本地副本，请参阅获取项目的本地副本部分。

加载项目后，选择“文件 > 源代码管理 > 同步最新并合并项目...”以从源代码管理存储库中获取对该项目的所有最新更改。

14.4 同步项目

当多人使用源代码控制协作同一 FMOD Studio 项目时，您可能会注意到该项目的某些元素标有虚影图标。

这些图标表示其他用户正在编辑的项目元素。

定期将项目的本地副本与源代码控制存储库中的版本同步非常重要。这可确保本地版本是可用的最新版本，并包括所有最近的更改和添加。

要同步整个项目，请选择“文件 > 源代码管理 > 同步最新并合并项目...”这将从源代码控制存储库中获取项目的最新版本。

此外，还可通过右键单击要同步的项目并从右键菜单的源代码管理集成特定子菜单中选择“同步选择”来同步单个事件、资源、总线、VCA、参数和效果。

14.5 提交更改

在对使用源代码控制的项目进行更改后，有必要提交这些更改，以便将它们包含在源代码控制存储库中。

已更改但尚未提交到源代码控制存储库的项目元素标有复选标记图标。同样，已添加到项目但尚未提交的元素用加号图标标记。

请注意，提交更改会自动保存项目。

提交对现有项目所做的更改:

1. 选择“文件 > 源代码管理 > 同步最新、合并并提交...”

   出现一个对话框，警告同步和合并项目操作不可撤销，选择继续将保存项目。

2. 单击“是”。

   

   进度条对话框显示项目的保存进度，随后是第二个进度条对话框，显示正在准备提交更改的项目。

   保存和准备完成后，将出现提交对话框。该对话框有两个选项卡，“更改”和“挂起”。在“更改”选项卡下是一个项目元素列表，其中包含要提交的更改。

   

   如果还不想将项目中的任何元素的更改提交到存储库，则可将其拖到“挂起”选项卡上来避免提交。“挂起”选项卡上的元素不被提交，但将保持标记为已更改并可以稍后提交。如果对挂起的元素改变主意，只需切换到“挂起”选项卡并将其拖到“更改”选项卡上即可。

   

   请注意，将项目的某些元素拖到挂起选项卡或更改选项卡上会自动导致一些相关元素也移动到该选项卡。这表明这些元素都存储在磁盘上的同一个文件中，因此不能单独提交或挂起。

   一旦决定好哪些项目元素要挂起，哪些要提交，就可以将更改的文件发送到存储库了。

3. 单击“在此处输入说明”字段，然后输入所做更改的适当说明。

   无论在“此处输入描述”字段中键入什么，都将用作源代码控制存储库中更改的描述。最佳做法是编写一个简单易懂的描述，无需其他上下文即可理解。

4. 单击“提交”按钮。

   提交对话框关闭，并在将更改提交到存储库时出现一个进度对话框。片刻之后，进度对话框消失。

这样，文件就会提交到存储库，并在下次选择“文件 > 源代码管理 > 同步最新和合并项目...”时可供协作处理项目的每个人使用。

14.5.1 解决冲突

如果提交的任何已更改元素也已被其他人更改，则会出现冲突解决对话框。

此对话框列出了自上次同步项目以来其他用户已更改的项目的所有元素。要完成提交更改，必须解决每个冲突。

要解决冲突，请右键单击元素并从右键文菜单中选择“接受他人的更改”、“接受自己的更改”、“合并”或“还原”。

• 选择“接受自己的更改”意味着当您单击接受按钮时，您所更改的元素版本将提交到您的源代码控制存储库，而他们对该元素的更改将被丢弃。

• 选择“接受他人的更改”意味着当您单击接受按钮时，他们的已更改元素版本将保留在您的源代码控制存储库中，而您的版本将被丢弃。请注意，以这种方式丢弃的更改无法恢复。

• 选择“合并”意味着当您单击接受按钮时，FMOD Studio 将同时应用您的更改和其他用户对元素的更改，只要这些更改相互兼容即可。如果您的任何更改与其他用户所做的更改不兼容，则您的更改将被提交到源代码控制存储库，而他们的更改将被丢弃，除非他们的更改是要删除项目的某个部分，而在这种情况下，您的更改将被丢弃。请注意，如果您的任何更改以这种方式被丢弃，丢弃后将无法恢复。例如，如果您和其他用户向同一事件添加了新的音频轨道，则更改是兼容的，两个新的音频轨道将出现在您的源代码控制存储库中。如果您和其他用户都将特定事件的主轨道音量设置为不同的值，则选择“合并”会将源代码管理存储库中的音量设置为您指定的值。最后，如果您的更改是设置特定音轨的推子音量，而其他用户的更改是删除该音轨，则选择“合并”会导致源代码控制存储库中的音轨被删除。

• 选择“还原”会立即丢弃您的已更改元素版本。这类似于选择“接受他人的更改”，但是您更改的版本会立即被丢弃，而不是在单击接受按钮时被丢弃。请注意，以这种方式丢弃的更改无法恢复。

解决冲突的方法没有一种固定的正确方式。如果不确定选择哪个选项，请咨询您团队的其他成员。

14.6 还原更改

如果您对 FMOD Studio 项目进行了更改，但不想保留这些更改，则可以“还原”该项目。

还原使项目的本地副本与最近提交到源代码控制存储库的版本相同。这有效地撤消了自上次同步项目以来对项目所做的所有更改，即使在进行这些更改后退出并重新打开 FMOD Studio 也是如此。

如果项目的资源存储在项目文件夹的资源子目录中，并且为资源启用了源代码管理集成，则还原项目会撤消对项目资源所做的更改。

如果项目的内置事件库存储在项目文件夹的构建子目录中，并且为已构建事件库启用了源代码控制集成，则还原项目会撤消对项目已构建事件库的更改。

要还原项目，请选择“文件 > 源代码管理...> 还原项目...”右键单击事件浏览器、资源浏览器，收发浏览器，参数浏览器，或效果浏览器。

有关还原项目的单个元素而不是整个项目的信息，请参阅本章的提交更改部分。

14.7 离线工作

有时需要在项目的源代码控制存储库不可用的情况下处理 FMOD Studio 项目，原因可能是要在网络停机或在没有互联网连接的情况下工作。

即使 FMOD Studio 无法连接到项目源代码控制存储库使用的服务器，仍然可以自由编辑 FMOD Studio 项目，但无法同步项目或提交更改，其他用户编辑的项目元素也不会标有虚像图标。

此外，如果在 FMOD Studio 未连接到项目的源代码控制存储库时尝试保存项目，系统将提示您禁用源代码控制并使文件可写。

这样禁用源代码控制意味着，在手动重新启用该项目的源代码控制之前，您将无法同步项目或提交更改到源代码控制存储库。

要重新启用已禁用源代码控制的项目，请打开首选项对话框的源代码控制选项卡，并输入源代码控制设置，就好像准备将项目添加到源代码控制存储库中一样。（有关如何将项目添加到源代码控制存储库的信息，请参阅本章的将项目添加到存储库 section of this chapter.)关闭首选项对话框后，选择“文件 > 源代码管理 > 识别本地更改...”以自动检测自上次同步和提交项目以来所做的更改。下次提交更改时，以这种方式检测到的更改将包含在提交对话框的更改选项卡中。

14.8 故障排除

受源代码控制的 FMOD Studio 项目有时可能会出现验证错误、内容过时或丢失或其他问题。以下方法可用于识别或修复这些问题。

如果遇到这些故障排除方法无法解决的问题，请通过QA 论坛联系 FMOD 支持并提供问题描述。

14.8.1 还原本地更改

还原项目(如本章还原更改部分所述）可消除 FMOD Studio 项目的本地副本中的问题，但前提是这些问题在签入源代码控制存储库的项目版本中不存在。当然，还原更改会有效地撤消该更改，因此仅当 FMOD Studio 项目的本地版本可挽救时才应使用此解决方案。

14.8.2 项目验证

当多个用户编辑项目的相关元素时，不同的更改将合并到包含所有更改的项目的单个版本中。此合并过程偶尔会导致项目包含称为“项目无效”的轻微不一致。

要检测并修复项目无效性，请选择“文件 > 验证项目...”

如果包含无效的项目版本已提交到源代码控制存储库，则团队成员应按照同步项目部分，如上所述选择“文件 > 验证项目...”，然后按照提交更改一节中所述，将更改提交到源代码管理存储库中。然后，您团队的所有其他成员应将项目的本地版本同步到源代码控制存储库中的版本。此过程可确保清除源代码控制存储库中的项目版本的无效性，并确保在项目上进行协作的每个人都使用该版本作为进行进一步更改和添加的基础。

14.8.3 删除隐藏文件夹

FMOD Studio 项目文件夹可能包含 .cache、.user 和 .unsaved 子文件夹，用于存储缓存的构建数据、用户设置和工作数据，使 FMOD Studio 能够更高效地运行并可根据需要自定义其界面。这些子文件夹不包含任何影响游戏行为的数据，因此 FMOD Studio 不会将这些文件夹提交到源代码控制存储库。

但如果它们以某种方式错误地提交到源代码控制存储库，则可能会导致同步和提交更改花费的时间比必要的时间更长，磁盘上的项目大小增加，以及在同步项目时用户设置被覆盖。

如果 FMOD Studio 项目的 .cache、.user 和 .unsaved 子文件夹已包含在源代码控制存储库中，则从源代码控制存储库中删除该文件夹应该会提高性能。

如果 .cache、.user 和 .unsaved 子文件夹在删除后重新出现在源代码控制存储库中，则可能意味着您的团队使用的外部工具(例如 P4V 或 tortoiseSVN）已经配置为将这些文件夹中的文件提交到存储库中。如果是这样，请让源代码管理管理员重新配置该工具。

14.8.4 使用 SVN 时的连接缓慢问题

在某些情况下，SVN 集成可能会很慢。在启用 SVN 集成的情况下，这可能是诸如保存对单个事件的更改等耗时一分钟的任务。这是因为 SVN 集成使用 SVN 命令行导致的。SVN 命令行中的任何缓慢都会对集成性能产生重大影响。

如果项目已经在 SVN 中并已签出，则可执行快速测试以验证 SVN 命令行的性能。为此，请打开终端 (Mac)或命令提示符 (Windows)并输入以下命令:

<path to svn executable> info -r HEAD "<path to project>/Metadata/Workspace.xml" "<path to project>/Metadata/Mixer.xml"

如果 SVN 服务器和项目设置正确，上述命令会在不到一秒左右的时间内显示 2 个文件的输出。每个文件的输出显示之间不应有停顿。

如果输出缓慢，则说明 SVN 服务器和项目设置不太理想。检查这两个文件的输出，看看其中是否有 "Repository Root" 字段。如果该字段显示服务器的域名(例如 svn://mysvnserver）而不是 IPv4(例如 svn://192.168.1.123）或 IPv6 地址(例如 svn://[fe80:: e9db:5127:a77a:3c50])那么问题可能是由于域名解析和解析时首选 IPv4 的 SVN 服务器造成的。

根据您的网络和机器设置，域名可能会解析为 IPv4 或 IPv6 地址。如果解析为 IPv6 地址并且未在 svnserve 命令上启用 --prefer-ipv6 选项，则会显着降低性能。要解决此问题，请在 svnserve 命令上启用 --prefer-ipv6 选项，或使用 svn relocate 命令将项目的存储库根 URL 从域名更改为服务器的 IPv4 地址。

例如，如果 SVN 服务器作为服务启动，则启用 IPv6 选项如下所示:

"C:\Program Files\TortoiseSVN\bin\svnserve.exe" --prefer-ipv6 --service -r E:\SVN\Repository

如果 SVN 更喜欢 IPv4，则重新定位 SVN 项目的现有本地副本:

"C:\Program Files\TortoiseSVN\bin\svn.exe" relocate svn://mysvnserver svn://192.168.1.123 E:/MyProject