Migration Guide

Migrate your Unreal Engine 4 projects to Unreal Engine 5 Early Access quickly and smoothly.

Windows
MacOS
Linux

Follow this guide to upgrade your Unreal Engine 4 projects to Unreal Engine 5 Early Access (UE5EA).

Unreal Engine 5 (UE5) introduces a series of changes, upgrades, and new features to the systems that made up Unreal Engine 4 (UE4). Although there have been significant changes to the engine, the built-in conversion process smoothly handles most of the work involved in migration without requiring any user action.

To begin, launch UE5 Early Access from the Epic Games Launcher. Or, if you already have UE5 Early Access running, select File > Open Project from the main menu. Then, select the project you want to upgrade and click OPEN.

Launcher.png

Click the Open a Copy button to upgrade a separate copy of your project, leaving the original unchanged.

ConversionOptions.png

When you convert a project to UE5 Early Access, we highly recommend using the Open a Copy workflow described above. The Convert in-place and Skip conversion options (available by clicking More Options) may not work as expected.

Once the conversion process is complete, most projects will be ready to build and run in Unreal Engine 5 Early Access without further action. However, certain new or upgraded features benefit from, or even require, some manual updates to operate properly in UE5 and take advantage of its full capabilities. Among the largest systemic changes are Nanite, Lumen, and Chaos. Nanite and Lumen will require a bit of work to get graphics-centric projects looking the same as they did in UE4, and heavily physics-based projects that have not already switched to Chaos will need some configuration and asset modification.

On this page, we will cover mandatory updates. If you are using these features, you will need to perform the updates described here in order to bring your UE4 projects into UE5 successfully. You can also read about noteworthy system changes, including system deprecations and replacements, to learn about changes that may be required in the future, or that can help you get the most out of UE5.

This guide focuses on UE5EA, which aims specifically at developers who are interested in exploring UE5's features and capabilities as they prototype next-generation games. This Early Access build is not considered production-ready, so we do not recommend it for teams working on live games or games in late stages of development. UE5EA is best suited for game development projects in pre-production or prototyping phases who want to work with the most advanced tools available, and are prepared to make the conversion to UE5 5.0 in 2022. For non-game developers, we recommend UE4 4.27, scheduled for release this summer, before moving to UE5 5.0 in 2022.

Mandatory Updates

The following sections describe changes that you may need to make to your UE4 project in order to bring it into UE5EA. Some of these changes are mandatory, while others are optional but recommended in UE5EA, and will become mandatory in future versions of UE5.

Development Platform Changes

Developers writing C++ code in Visual Studio should switch to Visual Studio 2019 if they are not already using it; this is also the default Visual Studio IDE for the latest version of UE4. UE5EA does not support Visual Studio 2017 or Visual Studio 2015.

UE5EA does not support 32-bit platforms, and there are no plans to add 32-bit platform support in the future.

UE5EA standardizes Target Platform Names, and developers will need to update build scripts and, in some cases, DeviceProfiles.ini files. This primarily affects developers who run them directly; developers who use UAT should not need to make changes. The following table contains the list of changed Target Platform Names:

UE4 Target Platform Name

UE5EA Target Platform Name

Windows

WindowsEditor

WindowsNoEditor

Windows

MacNoEditor

Mac

Mac

MacEditor

LinuxNoEditor

Linux

Linux

LinuxEditor

LinuxAArch64NoEditor

LinuxAArch64

XDK and GDK for XboxOne

The Xbox One GDK platform replaces Xbox One XDK in UE5EA. Take the following actions to update your project:

  • Update your automated build scripts to change references to the 窶弭boxOne窶・platform to 窶弭boxOneGDK窶・

  • The GDK.UseXDKCompatibleSave CVar enables the product to load XDK save game data. Set this CVar if your product is already published to retail customers.

Built-In Damage and Score Concepts

UE5EA does not include the built-in data types and code functionality for the damage and scoring models that existed in previous versions of the Unreal Engine. If your project used these, you can recreate them in UE5EA, or look into other solutions, such as the Gameplay Ability System.

C++ Object Pointer Properties

The following section only applies to projects using C++ code, although most C++ projects will compile without needing these modifications. Blueprints Visual Scripting users do not need to take any action.

UE5EA introduces TObjectPtr, a template-based, 64-bit pointer system, as an optional replacement for raw object pointers in editor builds. This system adds dynamic resolution and access tracking in editor builds, while performing identically to raw pointers in non-editor builds. TObjectPtr variables also convert automatically to raw pointers when passed to functions or stored in local variables. Many engine classes that once featured raw pointers in UPROPERTY variables now use TObjectPtr. While most interactions with TObjectPtr types will implicitly convert to raw pointers, there are some rare cases where direct interactions with engine class member variables need to change from raw pointer semantics to TObjectPtr semantics. For example, the RootComponent property in AActor was a USceneComponent* in UE4, but is a TObjectPtr<USceneComponent> in UE5EA; in some rare cases, you may need to update direct interactions with RootComponent, though calls to GetRootComponent, which still has USceneComponent* return type, can always remain as they are.

Although it is optional, we recommend using TObjectPtr<T> over T* for UObject pointer properties and container classes found in UCLASS and USTRUCT types. Since TObjectPtr converts to raw pointers for non-editor builds, this will not impact the behavior or performance of a shipped product, but may improve your experience when developing in editor builds. Use the following methods to adapt your programming style to this new pointer system:

  • When calling the "Find" family of container functions, use TObjectPtr<T>* instead of T** to capture the return value.

  • Range-based iteration through raw pointer containers might have used auto* as the iterator variable type. Change these to auto&amp;. We also recommend using auto&amp; or const auto&amp; in new code, since TObjectPtr can cache resolved object addresses, saving time on future access attempts.

  • Call ToRawPtr or Get on your TObjectPtr when you need a raw pointer and implicit conversion is not available. Common cases include ternary operations, and inside of const_cast. When passing parameters to function delegates, declare a parallel delegate function as a pass-through, replacing raw pointers with TObjectPtr parameters. The following example shows a passthrough delegate function:

    // 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<UObject> FirstParameter);
    
    // Pass-through function body (in the source file):
    bool UMyClass::MyFunction(TObjectPtr<UObject> FirstParameter)
    {
        return ShouldShowResetToDefault(FirstParameter.Get());
    }

In most cases, such as when passing parameters to functions or storing data in local variables, TObjectPtr automatically converts to raw pointer types. There are a few rare cases, such as those described above, where you will have to perform minor code modifications, but most projects will not need to do this.

Optional Conversion Tool

UE5EA includes UnrealObjectPtrTool, a program that automatically converts engine-visible raw pointer properties to the TObjectPtr system. You can find it in the Engine/UE5/Programs/UnrealObjectPtrTool/ section of the solution hierachy in your code IDE. The source code resides in Engine/Source/Programs/UnrealObjectPtrTool/.

This optional program's purpose is to expedite the process of converting your code from raw pointers to the TObjectPtr system. It will update UPROPERTY variables in class and struct definitions within your header files, but will not make all of the necessary changes to your source code as described above; you will still need to make those adjustments manually and ensure that your project compiles before using UnrealObjectPtrTool.

To use UnrealObjectPtrTool, follow these steps:

  1. Compile, cook, and run your project in UE5EA. This includes both editor and game builds.

  2. Identify and record the path to the Unreal Header Tool (UHT) log file from your editor build. This file is a byproduct of the compilation process. We will refer to this path as UHT_LOG_PATH.

  3. Create an empty changelist to hold the header files that UnrealObjectPtrTool modifies. Record the changelist ID; we will refer to this ID as UPGRADE_CL.

  4. Build the UnrealObjectPtrTool executable. In ushell: .build program UnrealObjectPtrTool.

  5. Run UnrealObjectPtrTool executable. In ushell:

    .run program UnrealObjectPtrTool -- UHT_LOG_PATH -SCCCommand="p4 edit -c UPGRADE_CL {filenames}"
  6. Verify that your workspace compiles, cooks, and runs, as you did in step 1, with the modified files.

PhysX and Chaos Physics Systems

UE5 uses the Chaos Physics engine for physical simulation, replacing PhysX as the default. Although PhysX still exists in UE5 Early Access, it will be removed in a later release. Physics simulation under Chaos Physics behaves differently from PhysX, requiring developers to make adjustments in order to see consistent behavior.

The physics tick rate will change for any newly created projects by default. The tick rate change will be accessible from Tick Async Physics within Project Settings. This new feature will simulate Physics on its own thread instead of on the Game Thread.

  • This change improves determinism by running physical simulation updates at a fixed rate.

  • As a result of having a fixed update rate, networked physics simulation is easier to keep synchronized because client and server systems run at the same interval.

  • No longer running on the Game Thread means that there is a potential delay between input to the physics system from the Game Thread and the physics system's reaction to that input. Developers must account for this delay to avoid unpredictable behavior in projects where gameplay logic relies heavily on physics simulation. Running Physics-heavy gameplay code in C++ callbacks which execute on the Physics Thread can mitigate this, but will require modifying project code to use this approach.

Although PhysX will eventually be removed from UE5, UE5EA users can still compile from source with PhysX enabled if necessary.