Skip to main content

Workflow

:::warning Work on a copy Always migrate a copy of the 4.27 project, or a project under version control. UEAPM changes files in place. :::

Blueprint-only project​

  1. Copy the 4.27 project folder.
  2. Open the copy with Unreal Engine 5.8. The engine converts the project when asked.
  3. Enable UEAPM (Edit > Plugins) and restart the editor.
  4. Open Window > Absolute Project Migrator and run the migration (see The panel).

C++ project​

A 4.27 C++ project usually does not compile on 5.8 as is, and an editor cannot open a project whose modules do not build. UEAPM solves this in two passes.

1. File-copy steps from any 5.8 project​

The project and cpp steps only edit files, so they can run from any 5.8 project that has UEAPM, pointed at your game with -target:

& "C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
    "D:\Host\Host.uproject" -run=UeapmMigrate -target="D:\MyGame\MyGame.uproject" -steps=project,cpp

Or with the bundled script:

powershell -File Tools\migrate_headless.ps1 -Project D:\Host\Host.uproject -Target D:\MyGame\MyGame.uproject -Steps project,cpp

The report is written into the target project (D:\MyGame\Saved\UEAPM\).

2. Build​

The C++ step prints the exact build command in its Notes section, for example:

& "C:\Program Files\Epic Games\UE_5.8\Engine\Build\BatchFiles\Build.bat" MyGameEditor Win64 Development `
    -Project="D:\MyGame\MyGame.uproject" -WaitMutex

If the build fails, check the C++ section of the report: items that need a human decision are listed with file:line and a suggestion. See also the FAQ.

3. Open the project​

Install UEAPM into <Project>/Plugins/ (see Installation), build again, and open the project in the editor. Then run the remaining steps from the panel.

The panel​

Window > Absolute Project Migrator opens the migration panel:

  • one checkbox per step (Enhanced Input is unchecked by default, see Enhanced Input);
  • Dry run: runs only the Analyze and Verify phases, nothing is modified;
  • Run: runs the selected steps in order;
  • Open report: opens the last MigrationReport.md.

:::tip Dry run first Start with a dry run. The report tells you what would change and what would stay open, before anything is modified. :::

Restart required​

Some steps enable an engine plugin (for example Chaos Vehicles when the project used PhysX Vehicles). A new plugin is loaded only after the editor restarts, so the step marks restart required and the runner stops before the next step, with an explicit entry in the report. Restart the editor and click Run again: the finished steps find nothing left to do and the migration continues.

Backups​

Every file UEAPM modifies is copied once, before the first change, to:

<Project>/Saved/UEAPM/Backup/<relative path>

The first backup is never overwritten by later runs, so it always holds the original file.

Reruns are safe​

Every step is idempotent: running it again after it finished finds nothing left to do. You can rerun the whole migration after fixing items by hand, and the new report shows what is still open. Every run is also kept in Saved/UEAPM/History/ (see The report).