适用于虚幻引擎的 Unity 版本控制（前身为 Plastic SCM）插件

release

这是适用于虚幻引擎的 **Unity 版本控制（前身为 Plastic SCM） 插件**（UE 4.11 到 4.27，以及 UE 5.0 到 5.4）。

它现在 在虚幻引擎市场上作为代码插件发布，支持在 Windows 上的引擎版本 5.1 到 5.3。 虚幻引擎市场上的 Unity 版本控制

一般来说，市场和 GitHub 上的插件版本将始终是最新的版本。如果出现错误并且需要快速修复某些内容，我们可以更容易地通过应用修补程序来修补它们。

但是，您当然仍然可以在 Unreal 中使用“Plastic SCM”的引擎内集成。

此插件并非旨在替代 桌面客户端 或 命令行界面“cm”。它是一种补充工具，可以提高您在编辑器中使用资产的日常工作效率。

它跟踪资产的状态，最重要的是锁定，将常见的源代码控制任务（包括更新、分支和合并）引入编辑器，并提供蓝图的视觉差异。它还有助于将现有虚幻项目导入源代码控制，这是一个简单的操作，并带有相应的 *ignore.conf* 文件。由于虚幻编辑器不管理 C++ 源代码，只管理资产，因此该插件对于技术设计师、关卡设计师和一般艺术家特别有用。

目录

用户指南

插件设置

引擎内版本的插件

在引擎中集成“Plastic SCM”的版本有助于发现性，也是开始使用 Unity 版本控制的最简单方法。但是，集成的版本始终落后于 Github 和市场上的最新版本。

  • UE4.24 到 4.27 附带了此插件的旧版本 1.4.6
  • UE5.0 附带了相同的过时版本 1.4.6，在 UE5 中总体上表现不佳，尤其是在 OFPA 上
  • UE5.1 附带了版本 1.6.2，支持新的“查看变更列表”窗口
  • UE5.2 附带了版本 1.8.0，支持重命名后的“查看更改”窗口中的“搁置”
  • UE5.3 附带了相同的版本 1.8.0
  • UE5.4 附带了版本 1.9.0，其中包含一个新的“查看分支”窗口，用于创建、切换到和合并分支。

从虚幻引擎市场安装

一般来说，市场和 GitHub 上的插件版本将始终是最新的版本。如果出现错误并且需要快速修复某些内容，我们可以更容易地通过应用修补程序来修补它们。

在虚幻引擎市场中，Unity 版本控制插件支持引擎版本 5.1 到 5.3

  1. 点击市场页面上的“免费”或“加入购物车”按钮，并完成结帐流程。*
    "Free" and "Add to cart" buttons
  2. 点击“在启动器中打开”按钮
    "Open in Launcher" button
  3. 点击“安装到引擎”按钮，选择您项目的虚幻编辑器版本，然后下载并安装文件。
    "Install to Engine" button
  4. 在您的项目中，导航到“编辑 -> 插件”，在“已安装”插件中，勾选以启用“Unity 版本控制”，然后重新启动虚幻编辑器
    Enable the plugin in the Plugins Manager
  5. 导航到“版本控制 -> 连接到版本控制”，对于“提供商”，选择“UnityVersionControl”
    Source Control Connect

从 Github 的发行版安装

release

  1. 下载针对您的 UE5 版本（分别为 UE4）的 最新二进制发行版 UE5PlasticPlugin-x.x.x.zip。
  2. 或者
    1. 将 ZIP 的内容直接解压缩到您的项目文件夹的根目录中。这将在您的项目中创建一个“Plugins\UEPlasticPlugin”子目录。这是在特定项目上使用 Unity 版本控制并通过将其添加到源代码控制来与其他团队成员共享插件的方法。一些用户报告称他们还必须从“Engine\Plugins\Developer\PlasticSourceControl”中删除集成的插件，以避免冲突。这仅在某些我尚未确定的特定用例中需要（例如在 CI/CD 或 Unix 操作系统上）。
    2. 将 ZIP 的内容解压缩到 UEX.Y 的 Engine\ 目录中，以用于所有项目（例如“C:\Program Files\Epic Games\5.1\Engine”）。这将在“Plugins”子目录中创建一个“UEPlasticPlugin”文件夹。然后，从“Engine\Plugins\Developer\PlasticSourceControl”中删除集成的插件，以避免冲突。这是在机器上为所有虚幻引擎项目启用 Unity 版本控制的方法。
  3. 然后，启动您的虚幻项目，点击“版本控制”图标“连接到源”，选择“Plastic SCM”。

从源代码构建

从源代码构建使您能够在功能发布之前对其进行测试、调试问题并做出贡献。如果您有自己的虚幻引擎分支，则需要这样做。

如果您的项目已经是 C++ 项目，您只需要重新生成 Visual Studio 项目文件（以下第 4 步），插件将在您下次编译项目时重新构建。

否则，如果您想为蓝图项目重新构建插件

  1. 您需要 Visual Studio 2015 或 2017，并支持 C++ 语言（免费的社区版就可以了）。
  2. 启动虚幻引擎编辑器，创建一个新的 C++ **基本代码** 项目（没有入门内容），例如 ProjectName。这应该启动 Visual Studio、构建游戏项目并将其打开到编辑器中。
  3. 关闭编辑器，然后使用文件浏览器，在您项目的根目录中创建一个新的 **Plugins** 目录。
  4. 将插件的源代码克隆到此Plugins目录（例如Plugins\UEPlasticPlugin）。
  5. 右键单击项目的.uproject文件，生成 Visual Studio 项目文件。
  6. 在 Visual Studio 中，重新加载全部并以开发编辑器模式构建解决方案。就是这样，插件已构建（生成的 dll 文件位于Plugins\UEPlasticPlugin\Binaries\Win64中）。

要发布和重新分发插件，请将Plugins文件夹压缩。但在此之前，请删除Intermediate、Screenshots和.git文件夹，以及可选的Plugins\UEPlasticPlugin\Binaries\Win64中较大的 *.pdb 文件。

项目设置

首先使用Unity 版本控制 GUI 保存您的连接凭据

启用源代码控制

启动 Unreal 项目，查看右下角的源代码控制菜单
Source Control Connect

启动 Unreal 项目，单击源代码控制图标“连接到源代码”
Source Control Connect

然后选择“Plastic SCM”插件
Source Control Connect - Select Provider

直接从 Unreal 创建新的工作区和存储库

源代码控制登录窗口，要创建新的工作区/新的存储库，请单击“初始化工作区”（云存储库示例）
Source Control Login window - create a new workspace on cloud

或在运行在本地的服务器上使用 ip:port
Source Control Login window - create a new workspace on localhost

这会创建一个合适的 ignore.conf 文件，将所有相关文件添加到源代码控制中（.uproject、Config 和 Content 子目录），并且可以在最后自动执行初始提交。

在接受源代码控制设置之前，请等待此操作成功，以免锁定 UI 并影响初始化！
Source Control Login window - checking files in source control

源代码控制设置

Source Control Settings

可以使用源代码控制菜单更改源代码控制设置，这些设置会保存在本地 Saved\Config\WindowsEditor\SourceControlSettings.ini 中。

  • BinaryPath：指向 Unity 版本控制命令行工具“cm”二进制文件的路径。如果 cli 在 PATH 中，则默认值是合适的。如果需要，可以更改为 cm 可执行文件的绝对路径。
  • UpdateStatusAtStartup：在编辑器启动时触发异步“更新状态”操作。在大型项目中可能需要相当长的时间，在此期间没有源代码控制状态可用。
  • UpdateStatusOtherBranches：启用更新状态以检测其他分支上的最新更改，以便显示“在其他分支中更改”警告和图标。
  • EnableVerboseLogs：将 LogSourceControl 默认详细级别覆盖为详细（除非已设置为 VeryVerbose）。
添加 ignore.conf 文件

如果您在 Unity 版本控制中有一个项目，但在工作区的根目录下没有 ignore.conf 文件，可以使用“源代码控制”->“更改源代码控制设置...”->“添加 ignore.conf 文件”按钮创建一个标准的 ignore.conf 文件。
Source Control Login window - Add a ignore.conf file

ignore.conf

生成的 ignore.conf 的内容，用作起点，但要根据项目的具体需要进行调整

Binaries
Build
DerivedDataCache
Intermediate
Saved
Script
enc_temp_folder
.idea
.vscode
.vs
.vsconfig
*.VC.db
*.opensdf
*.opendb
*.sdf
*.sln
*.suo
*.code-workspace
*.xcodeproj
*.xcworkspace
共享设置

要与团队共享此设置，请将此文件复制并重命名为 Config\DefaultSourceControlSettings.ini，将其添加到源代码控制中并提交。

最少的实用设置应该是选择合适的提供程序，但是如果与默认设置不同，设置一些设置可能会有用

[SourceControl.SourceControlSettings]
Provider=Plastic SCM

[PlasticSourceControl.PlasticSourceControlSettings]
BinaryPath=cm
UpdateStatusAtStartup=False
UpdateStatusOtherBranches=True
EnableVerboseLogs=False

项目设置

源代码控制

虚幻引擎允许您配置与项目相关的设置。

  • 在还原时应删除新文件（默认情况下为真）
    • 如果启用，当您还原添加到项目中的文件时，它将从磁盘中删除，而不是保留为未跟踪状态（私有）。这是在搁置文件并还原本地更改时的预期行为。
  • 启用不受控制的变更列表（默认情况下为真）

Project Settings - Source Control

源代码控制 - Unity 版本控制

该插件允许您配置与项目相关的设置。

Project Settings - Source Control - Unity Version Control

目前有 3 个设置可用

  • 用户名到显示名称
    • 对于此字典中的每个条目，编辑器将用您指定的显示值替换键中的用户名。
  • 在用户名中隐藏电子邮件域名（默认情况下为真）
    • 此设置切换用户名中域名名的可见性（如果用户名是电子邮件）。
  • 在更改时提示签出（默认情况下为真）
    • 取消选中此设置将使编辑器认为所有文件都已签出。在这种情况下，您在修改资产时不会收到任何通知，并且在保存这些更改时不会显示“签出资产”对话框。这模仿了 Git 的工作方式，即允许用户执行更改，而无需担心签出项目。注意：变更列表目前不支持本地更改的资产（即未签出的资产）。
  • 限制历史记录中的修订数量（默认情况下为 50）
    • 如果设置了非空值，则限制向 Unity 版本控制请求显示在“历史记录”窗口中的最大修订数量。
    • 需要Unity 版本控制 11.0.16.7608，该版本添加了对历史记录 --limit 的支持

编辑器首选项

源代码控制

虚幻引擎允许您配置编辑器行为。尤其是

  • 用于差异文本的工具
    • 配置比较非蓝图资产（例如材质）修订版本所需的外部差异工具
  • 在修改资产时提示签出
    • 在对资产进行更改后立即触发“N 个文件需要签出”通知，其中包含签出资产的链接（甚至无需保存）。
  • 在修改资产时自动签出
    • 在对资产进行更改后立即签出资产（甚至无需保存）。不会显示“签出”通知。
  • 在修改时添加新文件
    • 在保存“私有”资产时，将它们自动添加到源代码控制中。
  • 使用全局设置
    • 在所有项目之间共享源代码控制设置 ini 文件。

Editor Preferences - Source Control

在编辑器中工作

虚幻文档

Epic Games 的官方文档

Plastic SCM 论坛

状态图标

New Unsaved Private/Not in source controlled Added to Source Control Controlled/Unchanged

  1. 新建，未保存的资产（尚未存在于磁盘上）。
  2. 私有，资产不在源代码控制中。
  3. 已添加到源代码控制中。
  4. 源代码已控制，但未签出或本地更改

Changed Locally but not Checked-Out Checked-Out Redirector added by a Move Moved/Renamed

  1. 本地已更改，但未签出，或私有，即未受源代码控制
  2. 已签出，专门用于防止其他人进行修改（如果服务器上启用了锁定）。
  3. 通过移动添加的重定向器
  4. 已移动或重命名

Checked-Out/Locked by someone else Not up-to-date/new revision in repository Newer change in another branch Merge Conflict

  1. 在其他位置被锁定，由其他人或在另一个工作区中锁定（如果服务器上启用了锁定）。
  2. 不在头部修订版，资产已使用同一分支上的更新修订版提交
  3. 在另一个分支中更改，资产已在另一个分支的更新变更集中更改
  4. 合并冲突，资产已在两个独立的分支中更改，并且正在等待合并解决

修订控制菜单

虚幻引擎 4 源代码控制菜单

源代码控制状态工具提示，当将鼠标悬停在工具栏中的源代码控制图标上时
Source Control Status Tooltip

源代码控制顶部菜单，扩展了 Unity 版本控制特有的命令
Source Control Top Menu

虚幻引擎 5 修订控制菜单

(UE5.1) 源代码控制菜单和状态工具提示，扩展了 Unity 版本控制特有的命令
Source Control Menu

(UE5.2+) 修订控制菜单和状态工具提示，扩展了 Unity 版本控制特有的命令
Revision Control Menu

每个资产编辑器还提供一些修订控制操作，通常用于提交内容
Asset Tools Menu

蓝图编辑器还提供一个工具栏下拉菜单，用于与以前修订版的视觉差异
Blueprint Toolbar Diff drop-down

修订控制窗口

使用内容浏览器上下文修订控制子菜单，可以调用特定操作和窗口
Content Browser Context Menu

提交文件

提交文件到修订控制窗口，直接签入选定的资产（另请参阅下面的变更列表）。
Submit Files to Revision Control

查看变更列表

变更列表是虚幻引擎 5.0 中按主题将签出文件分组的新方法，以便以连贯的批次提交它们。UE5.0 包括验证检查，以确保变更列表之外没有缺少的依赖项，并且所有资产都在提交之前保存在磁盘上。
Changelist Window

文件历史记录

文件历史记录窗口，用于查看资产的更改日志
History of a file

蓝图差异

蓝图不同修订版的视觉差异
Blueprint Visual Diff

材质差异

材质的文本差异
Material Diff

重定向器

启用源代码控制后，虚幻引擎会在重命名或移动资产时创建一个重定向器，以便依赖其旧名称/位置的其他开发人员仍然可以使用引用它的其他资产。

这意味着，您最终将提交两个文件，即使默认情况下它们不会显示在内容浏览器中。

您可以使用专用过滤器在内容浏览器中显示它们
Source Control - Show Redirectors

您还可以使用上下文菜单“修复文件夹中的重定向器”递归地删除它们
Source Control - Show Redirectors

检测其他分支上的更改

如果您使用多个分支，无论是用于发布和修补程序，还是用于任务或功能，都可以启用一个选项来检查所有其他分支中的更改。

启用“更新状态”以同时检查历史记录，以检测其他分支中的更改
Source Control Settings

当资产已签出并在其他位置被锁定时，内容浏览器中的工具提示
Asset checked-out by someone else

当资产在另一个分支中修改时，内容浏览器中的工具提示
Asset modified in another branch

当资产在另一个分支中具有保留的智能锁时，内容浏览器中的工具提示
Retained Lock in another branch

尝试签出已在另一个分支中修改的资产时的警告
Warning on checkout for an asset modified in another branch

尝试修改已在另一个分支中修改的资产时的警告
Warning on modification for an asset modified in another branch

分支

该插件现在全面支持分支，提供了一个新的窗口来列出和过滤分支，并能够在虚幻编辑器中创建、切换和合并分支，根据需要重新加载资产和当前关卡。

要打开它，请使用“查看分支”菜单项在“版本控制”菜单中，或单击状态栏中当前分支的名称。

查看分支窗口
View Branches window

有关任务分支的讨论，请参阅下面的工作流程部分。

创建新的子分支
Create Branch Dialog

重命名现有分支
Rename Branch Dialog

将分支合并到当前分支
Merge Branch Dialog

删除所选分支
Delete Branches Dialog

智能锁

认识智能锁，这是一种减少 Unity 版本控制合并冲突的新方法

该插件现在完全支持智能锁，提供了一个新窗口来列出和过滤它们，并能够选择性地释放或删除它们。

要打开它，请使用“查看锁”菜单项在“版本控制”菜单中。

查看锁窗口
View Locks window

智能锁管理员上下文菜单，用于配置锁定规则或解锁资产
Smart Locks admin context menu

蓝图上的合并冲突

如果您在不依赖于独占签出（文件锁）的情况下使用具有二进制资产的分支（请参阅下面的工作流程），您将遇到二进制资产上的合并冲突情况。您必须在 Unity 版本控制 GUI 中触发解决，但随后跳过它而不保存更改，以便让编辑器向您展示一个可视化差异。

分支资源管理器显示待合并的资产冲突
Merged branch with a pending conflict resolution

内容浏览器中的相应图标（仅在 Unity 版本控制中触发解决后显示）
Merge Conflict

右键单击有冲突的资产以打开合并工具（只是一个具有 3 路可视化差异的冲突解决器，没有合并）
Merge context menu

蓝图属性冲突的可视化差异
Merge of Blueprint properties

蓝图事件图冲突的可视化差异
Merge of Blueprint Event Graph

工作流程

主线

使用虚幻引擎二进制资产最常见的工作流程是 Perforce 教授的：它主要依赖于一个主分支（流）供所有人使用，并且对整个 Content/ 子目录进行独占签出（锁定），以防止对 uasset 或 umap 文件进行合并冲突。

此典型工作流程将与使用 Gluon GUI 配置的部分模式工作区配合得最好。原因是部分工作区使您无需在签入资产之前更新工作区。

  1. 使用 Gluon GUI 更新工作区（获取最新版本），同时关闭虚幻引擎编辑器（因为编辑器正在锁定资产，但也可能锁定源代码控制中的 .exe & .dll 文件）
  2. 启动编辑器，进行修改并签出资产
  3. 然后签入（提交）资产，可以在编辑器中进行，也可以在关闭编辑器后从 GUI 中进行（关闭的好处是您可以确保所有内容都已保存）
  4. 需要时，关闭编辑器并再次更新工作区

如果您尝试使用完整工作区（使用 Unity 版本控制 GUI 而不是 Gluon），您通常需要在能够签入之前更新工作区。

任务分支

当在一个主分支（无论使用何种源代码控制）中共同工作时，处理二进制资产通常效果最佳。这是因为二进制文件无法合并，并且因为它们增加了在分支之间切换的成本（时间/带宽）。

但是，使用 Unity 版本控制，您可以使用易于创建和合并的分支。将它们用于代码将使您能够利用这些分支上的内置代码审查。并且与智能锁和完整的编辑器内分支支持相结合，您现在也可以安全地将它们用于二进制资产！

请注意，一些工作室一直使用任务分支来处理资产，并将它们包含在代码审查中。Unity 版本控制锁扩展到所有分支，防止两个人在同一个分支上同时处理同一个资产，无论他们使用的是哪个分支。该插件还提供完整的分支支持并警告用户如果资产在另一个分支中已更改.

要使用分支，您还需要在从一个分支切换到另一个分支之前以及在将一个分支合并到另一个分支之前关闭编辑器

  1. 使用编辑器内的分支窗口从主分支创建子分支
  2. 立即切换到它，更新工作区并重新加载资产
  3. 进行修改并签出资产
  4. 然后签入资产（请记住保存所有内容，工具栏现在有一个按钮来跟踪未保存的资产数量）
  5. 从分支创建代码审查
  6. 从主分支创建新的任务分支或返回主分支以合并分支

该插件还利用了编辑器中的可视化差异合并冲突解决工具，但这很痛苦，并且目前（截至 1.5.0 和 UE5.0）无法按预期工作

Unity 版本控制设置

保存连接凭据

该插件与当前需要存储您的凭据的命令行界面“cm”一起使用。在 Unreal 中启用 Unity 版本控制之前，请使用桌面客户端或 Gluon GUI 输入并保存您的凭据。

配置虚幻资产的锁定（独占签出）

管理员指南 - 第 7 章：配置独占签出（锁定）

二进制资产应被锁定以进行独占访问，以避免合并冲突。

要锁定整个Content目录上的所有资产，您需要在服务器目录（例如C:\Program Files\PlasticSCM5\server）中放置一个lock.conf，其内容如下

rep:<repname> [br:[<destination_branch>]] [excluded_branches:<exclusion_pattern>�]
/Content

例如，一个针对特定存储库的特定规则集

rep:UE5PlasticPluginDev
/Content

或具有用于锁定的多个目标分支

rep:UE5PlasticPluginDev br:/main /main/release excluded_branches:/main/experiments
/Content

或使用文件扩展名而不是路径

rep:UE5PlasticPluginDev
*.uasset
*.umap

更通用的配置将应用于服务器上的所有存储库

rep: *
/Content

但请注意，此默认全局规则不会与任何其他特定存储库规则（合并）一起使用，而是会被它们完全替换（“覆盖”）。

在 Unity 版本控制云中，您只需像这样设置锁定规则

/Content

从 Unity 版本控制 GUI 配置蓝图的可视化差异

在“首选项 -> 差异工具”中，为 uasset 添加一个新的配置，并将其向上移动到现有$binary之前
Diff tools

命令行需要对 UnrealEditor.exe 的引号路径、对您的“.uproject”文件的引号路径、-diff，然后是源文件和目标文件变量也用引号引起来

"C:\Program Files\Epic Games\UE_5.0\Engine\Binaries\Win64\UnrealEditor.exe" "C:\wkspaces\ProjectName\ProjectName.uproject" -diff "@sourcefile" "@destinationfile"

或用于虚幻引擎 4

"C:\Program Files\Epic Games\UE_4.27\Engine\Binaries\Win64\UE4Editor.exe" "C:\wkspaces\ProjectName\ProjectName.uproject" -diff "@sourcefile" "@destinationfile"

任何资产的文本差异

要为任何 uasset（不仅仅是蓝图）配置文本差异，请改用此命令

"C:\Program Files\Epic Games\UE_5.0\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "C:\wkspaces\ProjectName\ProjectName.uproject" -NoShaderCompile -run="DiffAssets" %1 %2 DiffCmd="C:\Program Files\PlasticSCM5\client\mergetool.exe -s={1} -d={2}"

支持

已知问题

  • 合并冲突：“接受目标”使 UE4 和 UE5 编辑器崩溃（与 Perforce 和 Git 插件相同）
  • 无法通过插件解决来自 cherry-pick 或 range-merge 的合并冲突：使用 Unity 版本控制 GUI
  • 错误：编辑器无法处理重命名/移动资产的可视化差异

不支持的功能

有些是 Epic Games 内部使用，仅与 Perforce 相关联

  • 标签：获取标签（用于完整引擎在 Perforce 下崩溃时）
  • 注释：责备（用于完整引擎在 Perforce 下崩溃时）

启用调试日志

在虚幻引擎中启用详细日志

要帮助诊断与插件或编辑器相关的任何问题，请在源代码控制设置中切换详细日志。

虚幻引擎日志文件位于<ProjectName>/Save/Logs/ProjectName.log。

为 Unity 版本控制启用日志记录

要帮助诊断与底层 Unity 版本控制“cm”命令行界面相关的任何问题，请为 Unity 版本控制启用日志记录.

cm 日志文件通常位于<LOCALAPPDATA>\plastic4\logs\cm.log.txt。

Unity logo - Unity 游戏引擎 Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.