Wiki

Unreal Engine 插件

面向 Unreal Engine 的 uVersion 插件：编辑器内原生版本控制、Blueprint 差异比较、Project Health 审计，以及最常拦下一次提交的两条规则。

前提条件

Unreal 项目必须位于 uVersion 工作区「之内」 这是激活的条件，而编辑器里任何地方都没有写明。插件会从项目开始向上查找 .uversion/ 文件夹；如果找不到，且此前也没有保存过认证令牌，它就完全不会激活，Unreal 也就没有任何版本控制。这不是故障：正是它阻止插件强行介入那些并非用 uVersion 进行版本管理的项目。请从 desktop 客户端克隆出的文件夹中打开项目，而不是从放在别处的副本中打开。

实践中 desktop 客户端是必需的 uVersion 服务器默认是自签名的。而 Unreal 编辑器并不知道该拿一个自签名证书怎么办：它没有指纹存储，也没有人能替它确认某个证书。结果就是，在 HTTPS 服务器上，从 Unreal 直接发起的连接会在 TLS 阶段失败，编辑器随即显示一条提示，要求启动 desktop 客户端。登录表单在 Revision Control Login 窗口中确实存在，但它跨不过这道墙：在自签名服务器上填写它不会有任何结果。只有一种搭配可行：desktop 客户端正在运行，你已在其中登录，插件经由它工作。与其花上一个小时，不如现在就知道这一点。

安装

uVersion 插件以预编译的二进制形式分发，由 desktop 客户端管理。无需你自行编译，也没有需要处理的源文件。 它从不纳入版本管理：它不会随仓库一起到来，也不应被提交进仓库。每台机器都安装与其 Unreal 版本和其系统相匹配的二进制文件。

支持的 Unreal 版本：5.6 及以上。

1. 在 desktop 客户端中打开工作区

安装 uVersion desktop 客户端，登录，然后打开包含 Unreal 项目的工作区。一切都在客户端中进行：没有要下载的压缩包，也不用手动解压到项目里。

2. 让客户端检测项目

客户端会在工作区根目录下（只要埋得不超过三层深）查找你的 .uproject（描述一个 Unreal 项目的文件）。一旦找到，工作区标签页顶部就会出现一条 Unreal 栏，并把与你的 Unreal 版本相匹配的插件放入 Plugins/uVersion/。左侧的标记显示插件的状态和版本号：更新也在那里查看。

desktop 客户端的 Unreal 栏：左侧是绿色的 Plugin 1.0.5 标记，随后是 Open Editor、Compile、Package、Publish Build、Sync 和 Status 按钮。

3. 在 Unreal 中打开项目

插件立即生效。无需在编辑器的 Plugins 窗口中勾选任何东西，也无需重启：如果它不见了，那是因为客户端还没把它放进来，而不是它还有待启用。

之后：更新

desktop 客户端会在打开项目时以及之后定期检查新版本。请注意，自动检查在两种情况下做的事并不一样：

插件缺失：会不经询问直接安装。这正是让首次启动无感的原因。
插件已存在但已过时（新版本，或 Unreal 版本变更）：客户端只会提醒你。它绝不会自行替换已安装的插件。此时 Unreal 面板的标记会变为 Update ready。

要应用更新：关闭 Unreal 编辑器，然后点击该标记。已加载的插件无法在磁盘上被替换；如果编辑器仍开着，标记会显示 Restart UE。

首次连接

正常情况下，没有什么需要连接。只要插件在项目周围检测到 uVersion 工作区，或检测到已保存的令牌，它就会自行选择为版本控制提供程序。你的凭据会从 desktop 客户端沿用，无需重新输入。打开项目即可。

下面三个步骤仅在自动选择没有发生时才需要。

1. 打开 Revision Control 菜单

它位于编辑器状态栏的右下角，而不在顶部菜单中。它向上弹出，包含 Unreal 的各项操作，其中有 Submit Content，还有一个带我们 Audit Project (Project Health) 条目的 uVersion 分区。选择 Connect to Revision Control。

2. 在 Provider 列表中选择 uVersion

Revision Control Login 窗口随即打开。展开 Provider，选择 uVersion。当工作区被识别时，窗口会以绿色自行说明（Automatically configured from workspace），而 Workspace、Server URL 和 Username 字段已经填好：无需输入任何内容。

Unreal 的 Revision Control Login 窗口：展开的 Provider 列表中已选中 uVersion，绿色的自动配置提示，以及 Accept Settings 按钮。

3. 用 Accept Settings 确认

窗口底部的 Accept Settings 按钮会应用该选择并关闭窗口。此时状态栏会显示 Connected to，其后是仓库名和你的用户名。该选择会被记住：以后再打开项目就不会再经过这一步。

检出一个资产，然后提交

从编辑器出发、针对一个内容文件的完整流程。而代码永远不从这里出发：见代码经由 desktop 客户端。

1. 动手前先看看资产的状态

Content Browser 的每个缩略图都带有一个标记，说明该资产处于什么状态：由你检出、由他人检出，或相对服务器已过时。工具提示会给出完整句子，例如 File is out of date, sync to get the latest version。这种情况下请先同步（右键、Revision Control、Sync）：在一个过时的版本上开始工作，就是在为冲突做准备。

Content Browser 中一个带黄色标记的资产缩略图，及其提示该文件已过时、需要同步的工具提示。

2. 检出该资产

右键点击资产，Revision Control 子菜单，然后 Check Out。一切都在这里： Sync、Check Out、Check In、History、Diff Against Depot、 Revert，与任何其他 Unreal 提供程序一样。美术人员没有任何新东西要学。

实践中你往往什么都不用做：只要你修改一个资产，插件就会自行在服务器端加锁，无需手动 checkout。

Unreal 的 Content Browser：右键点击一个资产，带 Sync、Check Out、Mark For Add、Check In、History、Diff Against Depot 和 Revert 的 Revision Control 子菜单，以及缩略图上的状态图标。

3. 提交前先比较

Diff Against Depot 会打开编辑器标准的可视化比较工具，Blueprint 也不例外：两个修订版并排显示，新增、删除或修改的节点会被框出。可从 History 对历史记录中的任何提交使用。

Blueprint Diff 窗口：同一个 Blueprint 的两个修订版并排显示，新增的节点以绿色框出。

4. 提交

右键、Revision Control、对所选项 Check In，或用状态栏菜单里的 Submit Content 一次性全部发送。窗口会列出相关文件， 包括删除项，并要求填写说明。提交时，插件会清理你重命名遗留的 redirector，并运行已启用的校验规则：一条处于 error 的规则会中止提交并指出出错的文件。

Unreal 的提交窗口：待提交文件列表及其勾选框、变更说明输入框，以及 Submit 按钮。

插件在 Unreal 中的功能

Project Health：审计项目

状态栏的 Revision Control 菜单中有一个 Audit Project (Project Health) 条目。它会遍历项目的资产注册表， 不加载任何一个资产，并生成一份健康报告：命名、文件夹结构、依赖、孤立内容、成本。它可离线工作（报告写入 Saved/uVersionAudit 下），并在你连接时发送给服务器，从而填充 desktop 客户端的 Project Health 标签页。

redirector 清理

当你重命名或移动一个资产时，Unreal 会在其身后留下一个 redirector：一个小小的转发文件，把旧路径指向新路径，好让那些引用旧名的资产继续工作。它们很快堆积起来，最终让目录树难以阅读。插件会检测它们，并在 checkin 时清理，同时更新所有受影响资产中的引用。

checkin 前校验

插件能对提交的文件运行一系列检查：Blueprint 编译、命名规范、纹理大小、导入设置、缺失依赖、循环依赖、孤立资产、重复、材质复杂度。共九条规则。一条处于 error 的规则会拦下提交，一条处于 warning 的规则则在确认后放行。

九条规则出厂即为停用 在一个全新的仓库上，它们全都以非激活状态创建：在管理员从 Admin 面板的 Rules 标签页逐条启用之前，不会运行任何检查。如果你以为某次提交会被拒绝，它却一声不响地通过了，那就先去那里查看。

启动时的对账

项目打开时，插件会把你的资产状态与服务器进行比较。它会遍历 Content/ 以及项目各插件的 Content/，并自动检出磁盘上所有可写、而尚未被检出的资产。其用意是保护你：一个你已经开始修改的文件，不会在两次会话之间被队友抢走。

需要知道的后果：你可能在不知情的情况下持有锁 这种自动检出是静默进行的，而且uVersion 的锁永不过期：它会一直持有，直到通过 checkin、通过 revert，或经由管理员的强制解锁被显式交还。没有任何超时会释放它。因此，只要在一个散落着若干可写文件的项目上打开编辑器，就足以在没有任何提示的情况下，为整个团队锁住这些文件。请养成查看 desktop 客户端 Pending 标签页、My Pending Changes 列表的习惯，并交还你不再处理的东西。

代码经由 desktop 客户端，而非经由 Unreal

插件拒绝提交代码文件：.cpp、.h、 .hpp、.c 和 .cs。该尝试会停在一个指出出错文件的阻断窗口上。这不是缺陷：desktop 客户端会在发送前编译，并发布你队友在同步时取得的编辑器二进制文件。一次从编辑器发出的代码提交会同时错过这两者，并会让整个团队的二进制分发陷入停顿。

因此，请从 desktop 客户端提交你的代码。而内容文件则完全可以从 Unreal 出发提交。

陷阱：只要检出了一个代码文件，也会拦下你对「内容」的提交 这条规则并不止于你所提交的文件。只要你持有某个代码文件的检出，哪怕只有一个，哪怕你根本没碰过它，哪怕它并不在你的提交里，来自 Unreal 的任何 checkin 都会被拒绝，包括一次纯粹的 .uasset 提交。消息会告诉你先从 desktop 客户端提交代码。

这是最常见的拦截，而且它偏偏会落在一个不写代码的人身上：只要有一个源文件在磁盘上被变为可写，启动时的对账就会自行把它检出。原因是实实在在的：一个针对未提交代码保存下来的资产，会弄坏所有同步它的人，因为他们的二进制里没有该资产所依赖的代码。

解除办法：打开 desktop 客户端的 Pending 标签页、 My Pending Changes 列表，找出代码文件，如果你改过它们就做 Checkin Selected，如果你没碰过就做 Revert。之后你的内容提交便会正常发出。可能需要几秒钟，等编辑器刷新它对锁的视图。

desktop 客户端的 Pending 标签页：My Pending Changes 列表中两个 .h 文件与一个 .uasset 并列，每项都带 Revert 按钮，下方是 Other Users' Locks 分区。

常见问题

没有 uVersion 菜单：编辑器忽略版本控制

项目多半不在一个 uVersion 工作区里。请检查克隆出的文件夹根目录下是否存在 .uversion/ 文件夹，以及你确实是从那个文件夹打开项目，而不是从放在别处的副本打开。

« Failed to connect to source control »

请检查 desktop 客户端是否正在运行，以及你是否已在其中登录：正是它持有你的凭据，也懂得如何与一个自签名服务器对话。如果工作区的所有者账号没有在客户端登录，插件就会拒绝以另一个身份工作，这是刻意的。

我没碰过任何代码，提交却被拒绝

你持有某个代码文件的检出。见代码经由 desktop 客户端。

我想要一个别人已锁定的资产

这不从 Unreal 发起：插件没有请求释放的功能。请通过 desktop 客户端，Pending 标签页，Other Users' Locks 分区，点击该文件行上的 Request Release 按钮。持有者会以 Production 看板中一张卡片的形式收到这个请求。

插件无法更新

这是预期行为：自动检查会安装缺失的插件，但对于更新它只会发出提示。关闭 Unreal 编辑器（已加载的插件无法被替换），然后点击 desktop 客户端 Unreal 栏中的 Update ready 标记来应用它。

某条校验规则从不触发

九条规则出厂即为停用。管理员必须从 Admin 面板的 Rules 标签页按项目启用它们。