Mod-support for your Unreal Engine Game
Introduction
I will be running you through the process of setting up a mod (or “User Generated Content”) for your Unreal Engine 4 game. I’ve created a sample FPS project with a simple mod included, it’s available for download on GitHub. As a base I used the Blueprint FPS Template. The mod changes the weapon behavior by shooting three balls in an arc instead of one. The Mod source contains a gamemode, map and custom player character.
Mods are handled as Plugins by the engine, so I recommend reading up on how plugins are handled by the editor before moving on.
This guide and the mod sample on Github were built using UE 4.9 Preview 4. There are some issues with cooking & packaging in earlier releases.
Warning: This procedure is intended for early adopters only! The pipeline may change and will receive improvements as it’s still work-in-progress.
The Project
The full example project is available for download on GitHub. It’s based on the FPS Blueprint Template with a ./Plugins/MyFirstMod folder containing our custom content.
Creating the mod
To create a mod, you must create a Plugin. As mods (or UGC – “User Generated Content”) are handled as Plugins by the engine. Below is the folder layout for ModSampleGame. The ./Plugins/MyFirstMod/ contains a /Content/ folder and a .uplugin descriptor file. The descriptor is loaded by the editor and can be hand-edited using any text editor. The /Saved/ folder is created by the cooking process.
Plugin Descriptor
The contents of the descriptor can be edited manually, here is an example of its contents:
{
"FileVersion" : 3,
"FriendlyName" : "MyFirstMod",
"Version" : 1,
"VersionName" : "1.0",
"CreatedBy" : "Tom Looman",
"CreatedByURL" : "https://www.tomlooman.com",
"EngineVersion" : "4.9.0",
"Description" : "My First Mod",
"Category" : "User Mod",
"EnabledByDefault" : true,
"Modules" :
[
],
"CanContainContent" : true
}
You can use this example and paste it into a new .uplugin file for creating your own mods.
Plugin Content
To view and edit UGC or mod content, make sure you enable “Show Plugin Content” in your Content Browser under “View Options” in the bottom right corner. In the sample project from GitHub you should see MyFirstMod as one of the listed Plugins.
Setup Launcher Profiles
To open the launcher (for packaging of the game and mod) go to Window -> Project Launcher. At the bottom of the Project Launcher window click the “+” symbol to create your new custom profile. We will need two profiles, one for the base game build, and another for our user mod.
Important note: As of right now the profiles don’t ship with the project files, but are stored in AppData/Local/UnrealEngine/4.9/Saved/Launcher/. Please use the guide below to setup the profiles.
Full Game Profile
First we must create a base game build. Mod creators would not need this profile, this is only intended for the developer of the game.
The project is set to “ModSampleGame”, using the default AnyProject works just fine too. The “Do you wish to build?” is checked and build configuration for this example is set to “Development” for testing purposes. Normally you’d want to set this to Shipping, however we need to have console commands available to try out our mod. Please keep this in mind for your own project profiles.
First set the cooking dropdown to “By the book” to enable the other options for the Cooking category. For this example we only cook for WindowsNoEditor, using the “en”-culture. We’re making a game release so we check “Create a release version of the game for distribution” with the release name of “1.0”. Please make sure the other checkboxes match from the image below.
We don’t need to deploy and/or remotely store our package:
Now you have setup your full game profile, make sure to add an appropriate name such as “FullGame Release v1.0” with an accurate description. We won’t be running the profile just yet as we will first setup our MyFirstMod profile.
MyFirstMod Profile
This profile is only slightly different from the full game profile. With “build dlc” enabled instead of a new game release. Each mod would have a different profile to package its contents.
The first part is equal to the FullGame:
As you can see, there are some changes to the Cook options below. The “build dlc” is a little confusingly labeled as it’s looking for content in the /Plugins/ folder. Make sure you enter the name for the mod to build, this must be the same as the folder name of your /Plugins/<ModName>, in the case in our example MyFirstMod. The option “Include engine content” must be disabled. We only want to include whatever is inside our mod folder, if you need engine content you should copy over the content to the Plugins/ModName/ folder instead.
The third section is the same as the full game, we do not copy to any repository and don’t deploy to a device.
Cooking your first mod
First cook our FullGame profile, and repeat the process for the MyFirstMod profile by pressing the Launch key for both, pressing “Done” after the run completes, and repeating for the second profile.
FullGame cook is located at: ModSampleGame/Saved/StagedBuilds/ You can move this anywhere on your disk.
MyFirstMod is located at: ModSampleGame/Plugins/MyFirstMod/Saved/StagedBuilds/WindowsNoEditor/ModSampleGame/Content/Paks/
You can rename the .pak file of the mod so we can move it to our full game ModSampleGame/Content/Paks/ folder. For an example see the included packaged project source from GitHub: PackagedSampleGame/ModSampleGame/Content/Paks/
Loading a mod
By default additional .pak files are automatically loaded by the game when placed in the /Content/Paks/ folder of your cooked game. You can use a sub-folders (for example “./Content/Paks/Mods/”) to organize your custom content. They will still be loaded automatically. In the example below I manually renamed the generated .pak file from the MyFirstMod profile to “MyFirstMod.pak”.
To test if our mod was loaded successfully, open the console window using Tilde (~) and type “open modexamplemap” you should now be respawned into our custom level, with our custom player that fires three projectiles instead of one when firing the weapon using the left-mouse button.
Done!
Now you’ve seen the process of setting up your first mod for an Unreal Engine 4 game! The pipeline is still a work in progress and will be smoothed out in upcoming engine releases. Now you have a basic pipeline to get you started for UGC support in your own project.
Please leave your feedback! We’re in the process of improving the pipeline and adding more features to make modding with Unreal Engine 4 as awesome as it can be, leave your comments.
Hello, I wanted to know if there was a tutorial for modding for a game that you don’t have have game source project. We are looking at this pipeline for modding our game
There isn’t much available, but Epic recently published additional resources on modding – check out the recent live stream for more details.
That was a good tutorial! I was able to create one DLC and it works, but when I analyzed the pak file from the game using the UnrealPak.exe -test, I found out my plugin is being cooked inside the BaseGamePakFile:
LogPakFile: Display: “PluginStudy/Plugins/MyDLC/Config/FilterPlugin .ini” OK.
LogPakFile: Display: “PluginStudy/Plugins/MyDLC/MyDLCExported uplugin” OK.
LogPakFile: Display: “PluginStudy/Plugins/PluginStudy.upluginmanifest” OK.
How can i avoid this to happen on 4.19.2 and still makes my game find and load the DLC?
there are other titles i am also working on and that is … well cannot say don’t want to spoil that suprise.but it is a very scary zombie like game but just diffirent i can say ….
How can I iterate through scenes in my DLCs? I couldn’t find them with ObjectLibrary->LoadAssetDataFromPath…
I am using 4.17.2, built from source, on Win64. I followed every single step exactly as detailed (with minor differences from engine versions to account for). No matter what I do, when I cook the DLC/plugin, I get this (wth?):
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/MAP_Testing.umap is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/stonetexturelowdetail_Mat.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/stonetexturelowdetail.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/metall003-new_Mat.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/metall003-new.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Plugins/AscTestMod/Content/MAP_Testing_BuiltData.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Player/Weapon/Pri/Coil/weapon_primary_helix_cannon_Sprite.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Player/Weapon/Pri/Coil/weapon_primary_helix_cannon.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Player/Weapon/Pri/Coil/BLP_Player_Weapon_Pri_Coil.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Enemy/Machine/SecureGage/AscMapKit_Enemy_Machine_SecureGage_TEX.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Enemy/Machine/SecureGage/AscMapKit_Enemy_Machine_SecureGage_MAT.uasset is being referenced by DLC!
LogCook: Error: Engine or Game content C:/Dev/AscentroidMapKit/Content/AscentroidMapKit/Enemy/Machine/SecureGage/AscMapKit_Enemy_Machine_SecureGage.uasset is being referenced by DLC!
That sounds counter intuitive! I haven’t been working on mod-support since several releases, I am afraid they may have changed up the required config settings..
One thing you could look into is the RoboRecall which supports modding and is available including source code through the Modding tab on the Unreal Engine launcher. It’s a valuable resource as they even have some custom editor windows on baking out mod content!
– Tom
Oh cool, thanks Tom! I’ll check it out!
I get the same error with 4.18.2 :-(
Hello Tom, Thanks for your tutorial, i want to ask a question in case that we have two or more .pak file, how we can manage mounting order ? (I know in launcher it’ll replace _p.pak and it’s included previous .pak)…
For example : I’ve separated textures, materials and meshes .pak file, i want to mount them in order of textures first and then materials and finally meshes.
Thank you again
Hello！
How to dynamically load the specified content in the PAK (as in a blueprint, material, and the name of the image from the PAK).
Can you give me a demo code?
My email address is 3217142879@qq.com
Thanks to you!
Afaik loading content from a pak file works in exactly the same way as loading content from the original game itself
Great article, thanks! Tom, I’m looking for a way to load maps (and content) from pak files at run-time, in mobile devices. Do you think this approach could be used to achieve that?
You could load maps at runtime from separate .pak files yes. I remember UE3 had a feature to automatically download new map files during load screens, I don’t know if this exists for UE4 as well unfortunately.
– Tom
ok,i found the answer from office,4.11,4.12 could build dlc, 4.13 works fine
thank you for this tutorial
i have a problem,my pak file could not load by game autoly,
i tried to put your pak file to Content\Paks directory.your file was loaded.i guess there must be something i missed
could you help me?
Interesting article. Do you have any plans for writing a tutorial about authoring and delivering DLC content on Steam and Android ?
Thanks
Not in the foreseeable future I’m afraid. Perhaps when I get far enough into a project to tackle those issues myself :)
– Tom
Awesome article, thank you! As I understand, we have to:
1. Enable plugin before build game;
2. Restrict maps by adding [AllMaps] section to DefaultEngine.ini.
for this approach to work.
Is there any way do the same thing when game builds without knowledge of any plugin, and plugin builds later so dlc pak-file goes to end-user who already have basic game build? I’ve downloaded your example, and ModSampleGame-WindowsNoEditor.pak contains reference to MyFirstMod.uplugin. Does it means that we can’t build DLCs after game release was shipped?
Hi Alex,
Hmm that must be an issue on the packaging end I bet, you should absolutely be able to do DLC/plugins later, not sure why it maintained that reference to the .uplugin (may be a side-effect of it loading by default? I’m not sure). One recommendation I have heard (for DLC) is to keep all DLC content in your base game (maintained with updates) and only use DLC pak’s to ‘unlock’ that content, it’s the easier way to prevent a build hell with maintaining tons of builds and patches for different DLCs etc. as it all becomes one.
– Tom
HI,what should i do if i meet this error? RunUAT.bat ERROR: AutomationTool was unable to run successfully.Please help me ,thanks!
The cooker is one big mystery sometimes. That error doesn’t give a lot of into to go on, double check all your settings in the cooker profile first.
If this keeps happening your best bet it to take this to AnswerHub https://answers.unrealengine.com/ including the log output of the cooker.
You should check Engine\Programs\AutomationTool\Saved\Logs\ directory, there are usually more info about potential problems with AutiomationTool.
Look at any errors logged before and google those.
In the code you can use something like this:
TArray<TSharedRef > Plugins = IPluginManager::Get().GetDiscoveredPlugins();
for (int32 i = 0; i < Plugins.Num(); i++)
{
const TSharedRef &Plugin = Plugins[i];
const FPluginDescriptor& PluginDescriptor = Plugin->GetDescriptor();
if (PluginDescriptor.Category == TEXT(“User Mod”))
but there is another question, how to find cooked levels in a plugin? So far I think it is impossible without external mod descriptor.
Interesting thanks! Although that is very prone to user error since categories are not enforced by the engine. I’m following up with the team at Epic to improve the pipeline, I’ll forward these two issues as well.
Cheers,
Tom
It would be nice if engine has ability to create mod plugins with predefined settings same as you wrote in this tutorial.
This can be achieved in a SNewPluginWizard, the SNewPluginWizard can be expanded with new FPluginTemplateDescription.
Tom, is there a way to list the mods in game. Such as map or enabling a mod via UMG.
I am investigating how we can find all loaded content plugins (mods) so we can display them through UMG. Hopefully I have something by the end of next week.
– Tom
Excellent resource!, Is this Mod-Sample also compatible with UE-4.8 or only for 4.9? :)
There was a cooking issue holding me back in 4.8, so I can only recommend trying this with 4.9.
– Tom
Amazing! Thank you for sharing.