Disclaimer: We strongly advise you to use the “migration” feature from UE if possible.
As a developper, we often need to use an old project as a template for a new one. Unfortunately, we can’t just copy/paste the project folder and simply rename the .uproject file with the new project name… Renaming a whole UE project is not an easy task. Also, when we work a lot with C++ files, we have to deal with source files renaming too.
In this short tutorial, we present how to manually perform the whole conversion of an UE 4.25 project named ASTRES3D into AVIG. Sometimes it’s the only way to perform the conversion, especially if you have a lot of C++ code in your project (except plugins), as the C++ code will be broken after the Unreal migration.
We’ll try to list here steps to follow in order to successfully rename a project, including the C++ files.
But, you need to know if you have blueprints using your C++ functions and classes, every reference will be broken by renaming your project.
Step 0. Close Unreal Engine
As we will delete and edit some files loaded by UE4 when a project is opened, we must start by closing UE4.
Step 1. Cleanup the project
As you know, Unreal creates a lot of temporary and cache files. The very first step is to remove all these folders in order to force Unreal to recreate these folders and files with the new project name.
Delete .vs, Binaries, Build, Intermediate, Saved folders and the .sln file. If you have a VCS, don’t remove its configuration files but you’ll certainly need to check it once the project renaming is done.
Step 2. Rename the .uproject
The second step is obviously to rename the .uproject file and the old module name in it (only if you have C++ source files in your project).
In our case, we rename ASTRES3D.uproject into AVIG.uproject and then open it with a text editor and change the project name in “Modules” section.
Step 3. Change the project name into DefaultGame.ini
Next, we have to edit the project name in the configuration file. The DefaultGame.ini is located in the Config folder.
We edit this file with a text editor and change the configuration line with our new project name :
Step 4. Rename and edit C++ source files
This step is really annoying… We’ll have to change the module name of our project. Lets move to the “Sources” folder to do it.
When dealing with an UE project using C++ code, Unreal will create a module with the name of your project. In our case we have an “ASTRES3D” module with ASTRES3D.Target.cs and ASTRES3DEditor.Target.cs. Of course, depending on the project complexity, we can have more targets or more modules.
Step 4.1. *Editor.Target.cs file
We rename ASTRES3DEditor.Target.cs to AVIGEditor.Target.cs
Then, we edit the file with text editor and change all references to ASTRES3D to AVIG. In our case we have the class name, the constructor name and the module name.
Step 4.2. *Target.cs file
We rename ASTRES3D.Target.cs to AVIG.Target.cs
Then, we edit the file with a text editor and change all the references to ASTRES3D to AVIG. In our case we have the class name, the constructor name and the module name.
Step 4.3. Rename the module and its related sources
- We rename the ASTRES3D folder to AVIG
- We browse to the AVIG folder and rename these files :
ASTRES3D.Build.cs, ASTRES3D.cpp, ASTRES3D.h, ASTRES3DGameMode.cpp, ASTRES3DGameMode.h, and any other file containing the project name in its filename.
AVIG.Build.cs, AVIG.cpp, AVIG.h, AVIGGameMode.cpp, AVIGGameMode.h
- Then we have to manually edit these files and also change the class names and the constructor names to match our new project name.
- Finally, we have to edit ALL your source files (.cpp and .h) to replace the preprocessor macro named YOURPROJECTNAME_API by NEWPROJECTNAME_API. In our case ASTRES3D_API is renamed into AVIG_API. This step can be automatized by opening the sources files in Visual Studio and replacing all “ASTRES3D_API” by “AVIG_API” using the replace in files feature.
Step 5. Rebuild the Visual Studio project files and launch the project
We do a right click on the .uproject and select generate visual studio project files. Once done we can start the project by double clicking on the .uproject file.
The first start will take a while because Unreal will have to recreate all its temporary files.
This concludes this small tutorial on how to manually change the name of a project. As stated in the introduction, when possible we should prefer the “migration” feature provided by Unreal, but for the cases it’s not possible, this tutorial shows how it can still be done.