Rename Your Unreal Engine 4 Project (BP and C++)

June 2, 2020

Renaming a project seems like it should be a simple thing, but it's fraught with pitfalls. If you do it wrong, you can accidentally nuke your project. This article will walk you through the discrete steps needed to rename your project. Stray from them with caution.

For purposes of this article, we will be renaming a project from Original to Final.

As always, before making a big change like this, it's a good idea to back up your project. And of course, make sure that your project is not open in the Editor while renaming.

Need to rename your project but don't have time to read to the end? We wrote a free tool that renames your projects for you. Enjoy.

Blueprint-Only Projects

Blueprint-only projects are a breeze to rename.

Rename Project File

Navigate to your project folder and rename the .uproject file.

Original.uproject -> Final.uproject

Update Engine Config

Open up DefaultEngine.ini, located in your project's Config folder. Update (or add, if it doesn't exist) the URL header with a GameName entry.

[URL]
GameName=Original -> GameName=Final

Rename Project Folder

Rename the project folder. This is not strictly necessary, but will help to keep your naming consistent.

Code Projects

You should be especially cautious when renaming a project that includes C++. When a C++ class is renamed, Blueprints derived from that class do not automatically detect the rename. If you do not set up a manual redirect, the Blueprint will be unable to find the old class and will effectively break. Absent version control, your Blueprint is toast. Now consider that renaming a project will rename every single class in your project, and you can imagine how easy it is to destroy a project.

Rename and Clean Up Project File

Navigate to your project folder and rename the .uproject file.

Original.uproject -> Final.uproject

Then open up Final.uproject with a text editor (not by double-clicking) and rename all instances of Original to Final. In a small project, you should only have to rename the Module name.

"Modules": [
  {
    "Name": "Original" -> "Final"
    ...
  }
]

Rename and Clean Up Target Files

Navigate to your project's Source subfolder and rename the two .target files (one for the executable target and one for the Editor target).

Original.Target.cs -> Final.Target.cs
OriginalEditor.Target.cs -> FinalEditor.Target.cs

Open both target files in a text editor and replace all instances of Original with Final.

public class OriginalEditorTarget -> FinalEditorTarget : TargetRules
{
  public OriginalEditorTarget -> FinalEditorTarget(TargetInfo Target) : base(Target)
  {
    ...
    ExtraModuleNames.AddRange(new string[] {"Original" -> "Final"});
  }
}

Rename Source Subfolder

Your project's Source folder will have a subfolder with the name of your project. Rename it.

Source/Original -> Source/Final

Rename and Clean Up Build File

Within Source/Final, rename the primary game module's .build file.

Original.Build.cs -> Final.Build.cs

Open the renamed build file in a text editor and replace all instances of Original with Final.

public class Original -> Final : ModuleRules
{
	public Original -> Final(ReadOnlyTargetRules Target) : base(Target)
	{
    ...
  }
}

Rename and Clean Up Game Module Files

There should be a header (.h) and source (.cpp) file with your project's name in the Source/Final folder. Rename both to Final.

Original.h -> Final.h
Original.cpp -> Final.cpp

In the source file, update the header file include and the IMPLEMENT_PRIMARY_GAME_MODULE macro.

#include "Original.h" -> "Final.h"
...
IMPLEMENT_PRIMARY_GAME_MODULE
(
  FDefaultGameModuleImpl,
  Original -> Final,
  "Original" -> "Final"
)

Clean Up Config Files

Open the project's Config folder, and go through each configuration file to replace all instances of Original with Final.

For example:

GlobalDefaultGameMode=/Script/Original.OldNameGameMode -> GlobalDefaultGameMode=/Script/Final.OldNameGameMode

Update Engine Config

Open up DefaultEngine.ini, located in your project's Config folder. Update (or add, if it doesn't exist) the URL header with a GameName entry.

[URL]
GameName=Original -> GameName=Final

Create Redirect

This step is crucial. Add a game name redirect to DefaultEngine.ini under the [/Script/Engine.Engine] header. Add the header if it does not already exist.

[/Script/Engine.Engine]
+ActiveGameNameRedirects=(OldGameName="/Script/Original", NewGameName="/Script/Final")

Be careful when renaming a project that has already been renamed once. For example, if you change from Original -> Final -> Final2, the following will not work:

// breaks!
[/Script/Engine.Engine]
+ActiveGameNameRedirects=(OldGameName="/Script/Original", NewGameName="/Script/Final")
+ActiveGameNameRedirects=(OldGameName="/Script/Final", NewGameName="/Script/Final2")

The Engine does not follow the chain of redirects, and Blueprints relying on a class from Original will not know how to find Final2. Instead, make sure all previous redirects point to the new game name.

[/Script/Engine.Engine]
+ActiveGameNameRedirects=(OldGameName="/Script/Original", NewGameName="/Script/Final2")
+ActiveGameNameRedirects=(OldGameName="/Script/Final", NewGameName="/Script/Final2")

Rename PROJECT_API References

Go through files in your primary game module (i.e. the ones in Source/Final) and update any ORIGINAL_API references in the header files to FINAL_API.

struct ORIGINAL_API FSomeStruct -> struct FINAL_API FSomeStruct 

Rename Project Folder

Rename the project folder. This is not strictly necessary, but will help to keep your naming consistent.

Regenerate Project Files

Delete the Saved, Intermediate, and Binaries folders in your project folder. Then right-click Final.uproject and select Generate Visual Studio Project files. Once it completes, double-click the Final.uproject to open the project, and click Yes when it prompts you to rebuild missing modules. If you run into any build errors, open up Final.sln and build to see if you missed anything.

Make Project Appear In Epic Games Launcher

Once you rename your project, it will likely disappear from the Epic Games Launcher. To make it show up again, simply launch the Engine and choose the option to Browse... for a project. Navigate to your renamed project, open it, and the project should now appear in the Launcher.

References:

  1. AnswerHub
  2. World of Level Design


© Mowgl33 2020.