So, you've embarked on developing a new plugin in Unreal Engine. Often, the meticulous art of naming takes a backseat during the initial stages of development, where focus is primarily on functionality, architecture, and coding. However, there comes a point when preparing the plugin for distribution demands attention to its name.
Many of us make the mistake of assigning placeholder names like “MyUnrealPlugin” or something technical such as “UE5_MeshOptimizationLibrary” during the early phases. The issue with these names is twofold: firstly, they lack aesthetic appeal, and secondly, they run afoul of Epic’s Trademark License Agreement by incorporating terms like “Unreal” or “UE” in your brand or product name.
Recognizing this issue, you find yourself at a crossroads, deciding to rebrand the plugin into something more sophisticated and commercially appealing.
UE plugins can fall into three categories: 'code only,' 'content only' (comprising assets without C++ code files), or a combination of both. To illustrate this concept in a practical case study, let's consider the HYPE plugin. HYPE encompasses both code and assets, including textures, materials, UI widgets, and general-purpose blueprints. Notably, the HYPE plugin was formerly known as 'UVP.'
When undergoing a name change for a plugin, such as in the case of HYPE, the initial step involves renaming the C++ module entry point files. These files must share the same name as the plugin itself. Additionally, it is crucial to rename the plugin project and update related build files, including:
UVP.plugin
UVP.Build.cs
UVPEditor.Build.cs – this one exists only if there is ‘editor only’ code.
Don’t forget also to rename the root directory in Source folder. In our case we had:
UVP
UVPEditor
Which was modified to:
Hype
HypeEditor
To rename the rest of C++ files is up to you. One thing you have to change in each class and that’s DLL export macro which looks like this:
class UVP_API AUVPGameMode : public AGameModeBase
where UVP_API in our cases becomes HYPE_API.
At this point, the C++ project should be ready for building. However, this is not the end of the story. You see, all blueprint class assets, including widgets, store path references to their parent class (which may be a C++ class in your plugin), other blueprints used by the class, the parent class path, and the class's asset path. This asset path, based on my assumption, is used at runtime to instantiate the blueprint.
For example, if you have code that loads a blueprint class:
And you fix the path to reflect the new root name – in our case ‘Hype’:
The class is destined to fail loading because, at this point, the class referencing is broken. To update the references to the new path in the plugin assets, you must open the editor. However, it is not going to work, as the editor would most likely crash during startup due to logic similar to the aforementioned issue, which attempts to load blueprints during class construction.
So, what's the solution? One approach is to comment out all the code responsible for blueprint loading and instantiation in the plugin's C++ code. While I haven’t reached this stage, and I'm not certain it will completely resolve the editor crash, I suspect that the plugin's instantiated blueprint classes in the editor, such as actor blueprints, might also encounter issues.
Fortunately, Epic has foreseen such scenarios and introduced a solution known as Core Redirects. Core Redirects allow us to 'virtualize' the modified path, tricking the UE editor into 'believing' that the new path is the old one. Here's how it works:
Open DefaultEngine.ini of your project and add the following lines at the top:
Launch the editor. If the above setup in DefaultEngine.ini is correct this part should work flawlessly.
Right click plugin ‘Content’ folder and select ‘Resave All’. This will re-save all the assets including blueprints updating all the data paths.
Remove all the CoreRedirects stuff from DefaultEngine.ini.
That's all, folks.