UE4工程升级UE5教程及注意事项

原文链接：https://mp.weixin.qq.com/s/vSVu0VsNub0J62Nz7vM6cA
虚幻引擎5迁移指南 | 虚幻引擎5.3文档 (unrealengine.com)
官方教程应该是从英文直接翻译过来的，过多词汇没修改，本篇重新整理修改一下，供各位参考。

本教程介绍，如何将虚幻引擎4(UE4)项目升级到虚幻引擎5(UE5)，并总结了注意事项。

虚幻引擎5?（UE5）内置的转换流程能够保证大部分内容可以自动完成从UE4项目的升级

————————————————————————————

一、升级到UE5

前言: 4.20-4.26 先升级到4.27，再升级UE5更保险

一、直接UE5打开原始工程

打开UE5.X，找到要升级工程，直接打开。

二、新增一个副本，进行升级UE5

点击打开副本（Open a Copy）?按钮。这样把项目升级为一个单独的副本，保留原项目不变。

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

（如果项目涉及大量物理效果，为了支持Chaos系统，可能需要做一些资产修改）

在本文将介绍强制更新和其他值得注意的系统更新，如系统的废弃和迭代情况。如果你要用到这些功能，请按照强制更新?中的说明执行更新，以便将UE4项目成功升级为UE5。在?其他变化?小节中描述的更新不一定会影响你的项目，但也请注意。

三、不同版本的转换说明

对于不同虚幻引擎创建的项目将如何进行转换，请参考下表：

四、资产兼容性

在UE4旧版资产可以在新UE5版本中打开。

UE5中保存的资产不能在旧版UE4中打开。

注：官方没有写全，其实还有两个方法：

1.导出GLTF?格式

2.导出USD 格式使用NVIDIA Omniverse 的USD格式，从高版本到低版本使用

————————————————————————————

二、必须执行的更新

下面介绍为了把项目从UE4升级到UE5所需的更新操作。其中有些操作是强制的

1.开发平台改动

如果你需要使用Visual Studio编写C++代码，你必须升级到Visual Studio 2019。这也是最新版UE4默认使用的Visual Studio IDE。UE5不支持Visual Studio 2017或Visual Studio 2015。

UE5版不支持32位平台。

UE5对?目标平台名称（Target Platform Names）?进行了标准化。开发人员必须更新构建脚本，在某些情况下还需要更新?DeviceProfiles.ini?文件。如果你使用?UAT，你就不需要进行更改。

新名称"目标平台名称"如下：

2.PhysX和Chaos Physics系统

UE5使用?Chaos Physics?引擎进行物理模拟，取代了默认的?PhysX。

UE5仍然保留了PhysX，但将在后续的版本中删除。

Chaos Physics下的物理模拟的行为方式与PhysX不同，开发人员要进行调整才能看到一致的行为。

对于任何默认创建的新项目，物理模拟的更新率（tick rate）将有变化。

可以通过项目设置（菜单：编辑?>?项目设置）中的异步物理更新（Tick Async Physics）来更改更新率。这个新功能将在自己的线程上模拟物理，而不是在游戏线程上模拟。

在新改动中，物理模拟将以固定频率运行，从而提高确定性。由于具有固定的更新速率，网络物理模拟同步将更加容易，因为客户端和服务器系统以相同的间隔运行。

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

3.用于调试着色器的控制台变量

UE5发布后，用于调试着色器的控制台变量有部分改动。

如果你的项目在配置文件中使用了这些变量，你需要在将项目迁移到UE5时更新它们，以便继续将之前生成的数据用于着色器调试。

下面为控制台变量的说明：

具体请看UE5的着色器调试说明文档https://docs.unrealengine.com/5.3/zh-CN/shader-debugging-workflows-unreal-engine/

其他改动

4.C++对象的指针属性

（非编程人员可以跳过此部分）

UE5引入了?TObjectPtr，一种基于模板的64位指针系统，可选择性地用来取代编辑器版本（editor builds）中的原始对象指针（raw object pointer）。此系统添加了动态解析和访问追踪功能，并且它的效用和非编辑器版本中的原始指针完全相同。

TObjectPtr?变量在传递给函数或保存为局部变量时，会自动转换为原始指针。尽管大多数涉及?TObjectPtr?的操作都会把?TObjectPtr?隐式转换成原始指针，但在涉及直接操作引擎类时，你可能需要在少数情况下手动改动。

之前UE4项目中在?UPROPERTY?中采用原始指针的引擎类现在都改为使用?TObjectPtr。项目中与引擎类交互的地方可能需要少量代码更新，用?TObjectPtr?来取代最原始的指针。例如，AActor?的?RootComponent?属性在UE4中是一个?USceneComponent*?指针，但在UE5中是?TObjectPtr<USceneComponent>?类型。少数情况下，你可能需要更新与?RootComponent?直接交互的代码。不过，调用?GetRootComponent?的地方会始终保持不变，因为它的返回类型仍然是?USceneComponent*?。

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

请参照以下方法来使用新的指针系统：

§?在调用容器函数的"Find"类函数时，请使用?TObjectPtr<T>*（而非?T**）来获取返回值。

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

§?当你需要原始指针但隐式转换不可用时，对你的?TObjectPtr?调用?ToRawPtr?或?Get。常见情况包括三值操作，以及再在?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(TObjectPtrFirstParameter);

return?ShouldShowResetToDefault(FirstParameter.Get());

可选的转换工具

UE5提供了?UnrealObjectPtrTool?——?一个能将引擎可见的原始指针属性自动转换为?TObjectPtr?的系统。你可以在IDE的解决方案目录中的?UE5/Programs/UnrealObjectPtrTool/?部分中找到该程序。源代码位于?Engine/Source/Programs/UnrealObjectPtrTool/?中。可执行文件位于?Engine/Binaries/Win64?目录中。根据你的操作系统或开发环境，可执行文件可能位于你的?Engine/Binaries/OS?目录中，其中OS表示你的操作系统。

———————————————————————————————————————————

要使用UnrealObjectPtrTool，请按照以下步骤进行操作：

1.在?Engine\Programs\UnrealHeaderTool\Config?目录中找到你的?DefaultEngine.ini?UHT配置文件。

2.在你的DefaultEngine.ini文件中，修改以下脚本：

NonEngineNativePointerMemberBehavior=AllowAndLog

3.重新构建你的项目，确保所有代码都被UHT解析。

4.你的UHT日志可能会被命名为Log_UHT.txt或UnrealHeaderTool.log，具体取决于你的项目的编译方式。你可以打开下列其中一个目录：

C:\Users\USERNAME\AppData\Local\UnrealBuildTool\Log_UHT.txt

C:\Users\USERNAME\AppData\Local\UnrealHeaderTool\Saved\Logs\UnrealHeaderTool.log

Engine\Programs\UnrealBuildTool\Log_UHT.txt

5.在Visual Studio解决方案中编译UnrealObjectPtrTool。

只有在通过源代码运行引擎时才需要这个步骤，否则，当你通过Epic Games启动程序安装引擎时，UnrealObjectPtrTool会被预编译。

6.运行UnrealObjectPtrTool可执行程序：

UnrealObjectPtrTool.exe?<UHT_LOG_PATH>?-SCCCommand="p4 edit -c UPGRADE_CL {filenames}"

———————————————————————————————————————————

5.渲染

下面的默认设置再UE5中完全改变，并可能会影响升级后项目的视觉效果：

• ?屏幕空间全局光照（Screen Space Global Illumination）：?屏幕空间全局光照（测试版）?的项目设置和相关的控制台变量?r.SSGI.Enable?已被删除。如果要重新启用屏幕空间全局光照作为项目的默认全局光照方法，请点击?项目设置（Project Settings）?>（引擎）渲染（(Engine) Rendering）?>?全局光照属性（Global Illumination properties），将?动态全局光照方法?设置为?屏幕空间（测试版）。如果要在后处理体积上重新启用屏幕空间全局光照，请进入体积的属性并找到?全局光照?类别，然后将?方法?字段设置为?屏幕空间（测试版）**。

• 基于Lumen硬件光线追踪的光线追踪支持：?独立的光追功能在虚幻引擎5中已经被废弃了。不过，引擎计算这些光照效果的能力并未被取消，因为Lumen涵盖了这些光照功能。被删除的是在虚幻引擎4中开发的独立的光线追踪系统。这些功能在工作时相互独立，也就是说，它们无法保证对引擎的相同功能提供一致的支持。Lumen将为其硬件光线追踪路径中的反射和全局光照添加全新的光线追踪功能的实现。随着UE5的不断完善，Lumen的光线追踪功能将继续改进，提供更广泛的支持，并与引擎的其他功能不断协同。

  • 光线追踪反射、全局光照，和阴影已被划分为各自独立的功能，可以独立启用。这些功能中的每一个都可以在?项目设置（Project Settings）?>?渲染（Rendering）?中找到，并且需要启用?支持硬件光线追踪（Support Hardware Ray Tracing）?来使用它们。

    • ?在全局光照（Global Illumination）部分，选择?动态全局光照方法（Dynamic Global Illumination Method）?作为首选项。

    • 在反射（Reflections）部分，选择?反射方法?作为首选项。

    • 在硬件光线追踪（Hardware Ray Tracing）部分，勾选?光线追踪阴影?复选框。

  • 反射和全局光照也可以使用后处理体积来设置（在全局光照和反射方法中选择）。

• 生成网格距离场：?Lumen的?软件光线追踪**功能主要依靠?有向距离场（Signed Distance Fields）?来表示网格体。所有?距离场?的?默认体素密度?已从0.1增加到0.2。这对于让Lumen实现较好的软件追踪效果是必要的，但它大大增加了距离场的内存占用。要调整该属性，请点击?项目设置?>（引擎）渲染，你能找到?生成网格距离场（Generate Mesh Distance Fields）?复选框和?距离场体素密度（Distance Field Voxel Density）**?属性。改变这个设置后，你可能需要重新启动编辑器以使其生效。

————————————————————————————

三、删除内容

Nanite?已经取消了?硬件曲面细分?的大部分用例。硬件曲面细分已在UE5中删除。对于Nanite不支持的用例，用户可能需要在必要时提高其资产分辨率。

Lumen?取代了?光线传播体积（Light Propagation Volumes）?和?距离场全局光照（Distance-Field Global Illumination）（DFGI）。

• • 与光线传播体积相比，Lumen提供了更多功能，其品质要好很多并且在积极开发中，尽管Lumen的基础性能开销更高。

  • DFGI是一个实验性功能；开发者应该使用Lumen而不是DFGI来实现动态全局光照。

  • ?随着时间的推移，Lumen全局光照和反射将取代大多数具有类似或更高品质效果的光线追踪功能。

老版色调映射器（Legacy Tonemapper）?在UE4中已被废弃，在UE5中将彻底删除。开发人员无需任何操作。

————————————————————————————

四、废弃内容

1.粒子系统

• Cascade?将在UE5 5.0中被废弃，并在后续版本中删除。建议使用?Niagara。
• （官方没有讲到，在UE4.26/4.27中有一键转换cascade粒子到Niagara粒子的工具，在plugins中打开 cascade to niagara converter）
• 
• 光线追踪?的部分功能将被废弃，反射和全局光照将直接整合到Lumen中。

2.世界构建内容

删减内容：世界合成（World Composition）

世界分区（World Partition）?是UE5用来处理大型、流送场景的系统。UE4使用的?世界合成（World Composition）?系统仍然在，但已被废弃，今后不会有升级、修复或其他支持。世界合成将在未来的UE5版本中被移除。

修改方法：

要将你的地图升级到世界分区系统，在项目中使用WorldPartitionConvertCommandlet，并提供要转换的每张地图的名称，一次一个。

例如，如果要转换?QAGame?项目中的?/Game/Maps/Tools/Landscape/TM_WorldComp_P?中的?TM_WorldComp_P?地图，请在运行编辑器时添加以下命令行：

QAGame?-run=WorldPartitionConvertCommandletTM_WorldComp_P?-ConversionSuffix?-SCCProvider=None

这会把TM_WorldComp_P?地图转换为使用世界分区系统。

-ConversionSuffix?会让转换后的地图保存为?TM_WorldComp_P_WP，而不是覆盖原始地图。

由于?-SCCProvider=None?选项，这个命令在运行时不会与项目的源码控制提供者产生交互。

此过程还将生成一个?TM_WorldComp_P.ini?文件，其中包含用于转换地图的设置，以及用于未来可能的转换的设置。

转换过程会基于现有的World Composition数据建立运行时网格（用于世界分区系统），并将地图中的Actor分配给相应的网格中。

3.工具

删除内容：

1）全新的几何体编辑工具将取代实验性的老版本可编辑网格体插件。

2）影片渲染队列（Movie Render Queue）?将取代?影片场景捕获（Movie Scene Capture）。

3）VR关卡编辑?将被剥离，只支持VR预览，但UE5将继续支持虚拟制片堪景。

4）镜头录制器（Take Recorder）?将取代?Sequence录制器（Sequence Recorder）。镜头录制器包含Sequence录制器提供的所有功能。

5）摄像机动画序列（Camera Animation Sequences）?将取代?摄像机动画（Camera Anims）。

6）删除插件相关：UE5还删除了与被删除插件相关的?编辑器功能包。这些插件的用户要确保不在其项目中引用被删除的内容。

7）彻底删除Matinee，使用Sequencer?取代?。Matinee已被废弃，但在UE4中仍然存在。（UE4中也有一键转换工具）

8）控制绑定

????????Space?被重命名为?Null。

????????Gizmos?被重新命名为?Shapes。

????????基于当前内容设置初始变换（Set Initial Transform from Current）?现改为?基于当前内容设置偏移变换（Set Offset Transform from Current）。

9）数据类型

????????集合（Collections）?现在被?数组（Arrays）?所取代。

????????变换约束（Transform Constraint）?节点已被废弃，并被单独的?点（Point）、旋转（Rotation）?和?父约束（Parent Contraint）?节点所取代。

????????新的父约束（Parent Constraint）?节点可以用来代替?投射到新父节点（Project to New Parent）?和?设置变换（Set Transform）?节点。

????????使用空间切换（Space Switching）?来代替?父切换约束（Parent Switch Constraint）。

????????Bezier数据类型（Bezier Data Type）?已被?Splines插件（Splines plugin）?取代。

????????ControlRigHierarchyModifier?不再能用于Python，它已被替换为用于查询绑定元素的?RigHierarchy?和用于编写绑定元素的?RigHierarchyController。

????????ControlRigBlueprint?不再拥有?控制器（Controller）属性。要访问主?RigVMController，请使用函数：ControlRigBlueprint.get_controller()。

????????映射不会在构造脚本中处理，而是在控制绑定组件的预初始化（Pre-Initialize）?中处理。

10）音频

????????虚幻音频混合器（Unreal Audio Mixer）?将在UE5 5.0中取代被废弃的?老版音频后端（Legacy Audio Backends）。用户不需要采取任何操作。

????????Sound Cue将被?MetaSounds?所取代，但仍可使用

????????声音类混合（Sound Class Mix）将被?调制（Modulation）和?子混合（Submix）?系统所取代，后者现在已经可用。

????????这个地方写错了，Audio Volumes继续使用，没有被取代音频体积参数 | 虚幻引擎5.3文档 (unrealengine.com)Audio Volume Actors in Unreal Engine | Unreal Engine 5.3 Documentation音频体积参数 | 虚幻引擎5.3文档 (unrealengine.com)

§ Audio Volumes音频体积将被目前正在开发的新系统所取代，该系统将在UE5 5.0中使用。

11）Gameplay框架

????????蓝图原生化?在UE5中将不再存在。采用了这一功能的项目不会出现任何变化，也不需要接受任何修改，就能正常运行，尽管性能可能会受到影响。如果发生这种情况，开发人员需要采取其他优化方法。

12）网络

????????AES、RSA和RSA密钥AES加密处理程序?将从UE5 5.0开始废弃，并在UE5的未来版本中删除。目前只使用DTLS。

????????§?AES GCM将在UE5 5.0之后继续使用，但在UE5的未来版本中将被删除。用户无需因为此变化而修改他们的项目。

13）核心

????????Zen Loader?将取代?事件驱动加载器（Event-Driven Loader）。由于大多数用户不直接与事件驱动加载器对接，这一变化在项目迁移时无需任何操作。

14）统计系统Stats System

????????Unreal Insights?将取代?统计系统(Stats System),统计系统将保留在UE5 ，但最终会被移除

————————————————————————————

以上就是虚幻引擎4(UE4)项目升级到虚幻引擎5(UE5)的总结以及注意事项，当然实际开发中仍然会遇到各种各样的问题，还是要多看日志查百度google查论坛。