迁移指南

介绍如何将虚幻4项目平稳迁移到虚幻5中。

Windows
MacOS
Linux

你可以参照本指南,将虚幻引擎4项目迁移到 虚幻引擎5抢先体验版(UE5EA) 中。

虚幻引擎5 (UE5)在 虚幻引擎4 (UE4)的基础上引入了一系列改动、升级和新功能。尽管新引擎有了大量更新,但内置的转换流程仍能保证大部分内容可以自动完成迁移,无需用户执行任何操作。

要开始迁移,请在启动程序中打开UE5EA。或者,如果UE5EA已经在运行,请点击 文件(File)> 打开项目(Open Project) 菜单项。然后,选择你要升级的项目并点击 打开(OPEN)

Launcher.png

点击 打开副本(Open a Copy) 按钮。这样可以把项目升级为一个单独的副本,保留原项目不变。

ConversionOptions.png

当你需要把项目升级到UE5EA版时,我们推荐使用上文介绍的 打开副本(Open a Copy) 方法。更多选项(More Options) 中的 直接转换(Convert in-place)跳过转换(Skip conversion) 可能无法正常使用。

转换完成后,大部分项目都可以直接在UE5EA中构建和运行。不过,某些新功能或升级过的功能可能需要手动更新才能生效。最显著的系统改动(或新增部分)包括Nanite、Lumen和Chaos。假如项目涉及大量图形内容,那么需要你针对Nanite和Lumen手动做一些处理,才能让画面看起来和UE4中的相同。假如项目涉及大量物理效果,你需要做一些资产修改,以便用于Chaos系统。

在本文中,我们将介绍强制更新相关的内容。如果你要用到上文提到的这些功能,你需要执行这类更新才能成功将UE4项目升级为UE5。你还可以查看重要系统更改(该文介绍了哪些内容会停止维护或被替换),以此了解将来可能需要哪些改动。

本文关注的是UE5EA版本。UE5EA版主要是帮助开发者预览UE5的功能,探索次世代游戏的可能性。EA版还无法用于实际产品开发,所以我们不推荐大家把它用于现阶段的游戏开发。对于开发者来说,UE5EA版只适合用于开发游戏原型,用来尝鲜最新功能;开发者还需要做好将开发内容升级到UE5.0正式版(2022年发布)的准备。对于非游戏类开发者来说,我们首推UE4 4.27版本(预计今夏发布),然后在2022年改为UE5正式版。

必须执行的更新

下文介绍为了把项目从UE4升级到UE5所需的更新操作。其中有些操作是强制的,而有些则是可选的(推荐在UE5EA版中执行,未来版本中这些可选操作会变成强制操作)。

开发平台改动

使用Visual Studio编写C++代码的开发人员需要升级到Visual Studio 2019,这也是最新版UE4默认使用的Visual Studio IDE。UE5不支持Visual Studio 2017或Visual Studio 2015。

UE5EA版不支持32位平台,并且没有计划在未来添加针对32位平台的支持。

UE5EA对 目标平台名称 进行了标准化,因此开发人员将需要更新构建脚本,在某些情况下还需要更新 DeviceProfiles.ini 文件。这主要是影响直接运行它们的开发人员;使用 UAT 的开发人员将不需要进行更改。下表列出了目标平台名称的列表:

UE4目标平台

UE5EA目标平台

Windows

WindowsEditor

WindowsNoEditor

Windows

MacNoEditor

Mac

Mac

MacEditor

LinuxNoEditor

Linux

Linux

LinuxEditor

LinuxAArch64NoEditor

LinuxAArch64

关于XboxOne的XDK和GDK

在UE5EA中,Xbox One GDK 平台取代了 Xbox One XDK。请用以下操作更新项目:

  • 在自动构建脚本中把引用"XboxOne"平台更改成引用"XboxOneGDK"。

  • GDK.UseXDKCompatibleSave 能让产品加载XDK并保存游戏数据。如果你的产品已发布给零售客户,请设置此控制台变量。

内置的伤害和计分系统

UE5EA版把老版本中与"伤害"和"计分"相关的数据类型和代码都删除了。如果你的项目需要用到这些功能,你可以在UE5EA中手动实现它们,或者寻找其他替代方案,例如Gameplay技能系统。

C++对象的指针属性

以下内容仅适用于C++项目,尽管大多数C++项目都能在不改动的情况下通过编译。蓝图用户不需要采取任何操作。

UE5EA引入了 TObjectPtr,一种基于模板的64位指针系统,可选择性地用来取代编辑器版本(editor builds)中的原始对象指针(raw object pointer)。此系统添加了动态解析和访问追踪功能,并且它的效用和非编辑器版本中的原始指针完全相同。TObjectPtr 变量在传递给函数或保存为局部变量时,会自动转换为原始指针。尽管大多数涉及 TObjectPtr 的操作都会把 TObjectPtr 隐式转换成原始指针,但在涉及直接操作引擎类时,你可能需要在少数情况下手动改动。之前很多在 UPROPERTY 中采用原始指针的引擎类现在都改为使用 TObjectPtr。项目中与引擎类交互的地方可能需要少量代码更新,用 TObjectPtr 来取代最原始的指针。例如,AActorRootComponent 属性在UE4中是一个 USceneComponent* 指针,但在UE5EA中是 TObjectPtr<USceneComponent> 类型。少数情况下,你可能需要更新与 RootComponent 直接交互的代码。不过,调用 GetRootComponent 的地方会始终保持不变,因为它的返回类型仍然是 USceneComponent*

使用UE5EA进行编程开发时,我们建议对 UObject 指针属性和 UCLASS 以及 USTRUCT 中的容器类使用 TObjectPtr<T> 而非 T*。由于在非编辑器版本中,TObjectPtr 会转换成原始指针,这不会影响已发布产品的行为或性能,但会改善你在编辑器版本中的开发体验。请参照以下方法来使用新的指针系统:

  • 在调用容器函数的"Find"类函数时,请使用 TObjectPtr<T>*(而非 T**)来获取返回值。

  • 通过原始指针容器进行的基于范围的遍历可能已经使用了 auto* 作为迭代器变量类型。将它们改为 auto&。此外,我们还建议在新代码中使用 auto&const auto&,因为 TObjectPtr 可以缓存已解析的对象地址,从而为之后的访问操作节约时间。

  • 当你需要原始指针但隐式转换不可用时,对你的 TObjectPtr 调用 ToRawPtrGet。常见情况包括三值操作,以及再在 const_cast 内部。在将参数传递给函数委托时,将并行委托函数声明为传递函数,取代具有 TObjectPtr 参数的原始指针。下面的示例展示了一个传递委托函数:

    // Original function signature, using raw pointers, which we will use in most cases:

    static bool MyFunction(UObject* FirstParameter);

    // In rare cases where implicit conversion is not available, use this pass-through function.
    // Pass-through function signature, using TObjectPtr:

    static bool MyFunction(TObjectPtr FirstParameter);

    return ShouldShowResetToDefault(FirstParameter.Get());

在大多数情况下,例如将参数传递给函数或者用局部变量保存数据,TObjectPtr 会自动保存为原始指针类型。只有少部分情况下(例如上文描述的),你才需要执行少数代码改动。大多数项目不需要。

可选的转换工具

UE5EA包含 UnrealObjectPtrTool —— 一个能将引擎可见的原始指针属性自动转换为 TObjectPtr 的系统。你可以在IDE的解决方案目录中的 Engine/UE5/Programs/UnrealObjectPtrTool/ 部分中找到该程序。源代码位于 Engine/Source/Programs/UnrealObjectPtrTool/ 中。

这个可选工具旨在方便你把项目中的原始指针转换成 TObjectPtr。它将更新类中的 UPROPERTY 变量和头文件中的结构体定义,但不会对你的源代码进行上文提及的所需的更改;你仍然需要手动调整,并确保你的项目在使用 UnrealObjectPtrTool 之前完成编译。

要使用 UnrealObjectPtrTool,请按照以下步骤进行操作:

  1. 在UE5EA中编译、烘焙和运行你的项目(包括编辑器版本和游戏版本)。

  2. 识别并记录 Unreal Header Tool(UHT) 的日志文件在编辑器构建中的路径。此文件在编译过程中生成。我们将此路径称为 UHT_LOG_PATH

  3. 创建一个空更改列表,用来存储 UnrealObjectPtrTool 修改的头文件。记录更改列表ID;我们将此ID称为 UPGRADE_CL

  4. 编译 UnrealObjectPtrTool 可执行文件。在ushell中:.build program UnrealObjectPtrTool.

  5. 运行UnrealObjectPtrTool可执行文件。在ushell中:

    .run program UnrealObjectPtrTool -- UHT_LOG_PATH -SCCCommand="p4 edit -c UPGRADE_CL {filenames}"
  6. 验证你的工作区是否使用修改后的文件按照你在步骤1中的方式进行了编译、烘焙和运行。

PhysX和Chaos Physics系统

UE5使用 Chaos Physics 引擎进行物理模拟,取代了默认的 PhysX。虽然UE5抢先体验版仍然保留了PhysX,但将在后续的版本中删除。Chaos Physics下的物理模拟的行为方式与PhysX不同,开发人员要进行调整才能看到一致的行为。

对于任何默认创建的新项目,物理模拟的更新率(tick rate)将有所不同。可以通过项目设置(Project Settings)中的异步物理更新(Tick Async Physics)来更改更新率。这个新功能将在自己的线程上模拟物理,而不是在游戏线程上模拟。

  • 在新改动中,物理模拟将以固定频率运行,从而提高确定性。

  • 由于具有固定的更新速率,网络物理模拟同步将更加容易,因为客户端和服务器系统以相同的间隔运行。

  • 由于不在游戏线程上运行,游戏线程中的输入指令(input)发送给物理系统后,可能会在一段延迟后,物理系统才会响应输入操作。开发人员必须考虑这种延迟,以避免编写严重依赖物理模拟的项目时,发生不可预测的行为。在物理线程上的C++回调函数中运行物理相关的游戏逻辑代码能够减轻这种问题,但需要修改项目代码才能使用这种方法。

虽然PhysX最终将被移除出UE5,但抢先体验版用户在必要时仍然可以通过源代码编译的方式启用PhysX。