June 2, 2020
Renaming a project seems like it should be a simple thing, but the process is 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 are a breeze to rename.
Navigate to your project folder and rename the .uproject file.
Original.uproject -> Final.uproject
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 the project folder. This is not strictly necessary, but will help to keep your naming consistent.
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.
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"
...
}
]
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"});
}
}
Your project's Source folder will have a subfolder with the name of your project. Rename it.
Source/Original -> Source/Final
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)
{
...
}
}
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"
)
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
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
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")
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 the project folder. This is not strictly necessary, but will help to keep your naming consistent.
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.
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: