Importing Another Mod

This page is a work in progress.

The modding documentation requires time to update and can only cover so much. Looking at other mods' source code is a great way to expand your skillset and learn new things. This page will cover how to import another mod into your Starter Project so you can look at it in the editor and tweak it.

Do not release modified versions of someone else’s mod unless you have explicit permission from them or the license file in their repository allows for it. It’s still their work, after all!

Packaged Mods versus Source Code

It’s important to understand why importing a mod to your project is not as simple as downloading the released mod and putting it in your project’s mods directory.

When a mod is packaged for release, it is compiled into a .pak file. A Pak is a compressed archive that contains all the mod’s code, assets, and other files. It’s one of the files download from ficsit.app and what gets install in your game.

The packaging process is like baking a cake. You can’t un-bake a cake, meaning that you can’t get all the original ingredients back. You can’t open a .pak file in the Unreal editor.

Although it is possible to extract some kinds of assets from a mod’s pak file, you’ll usually need the mod’s source code to be able to learn from it and modify it. Extracted .uasset files typically can’t be loaded in a project for similar reasons.

Find the Source Code

If a mod developer is sharing the mod’s source code, it is probably listed on the modpage on ficsit.app in the 'Source' link section. If you don’t see it there, consider asking them on the Discord. Many are happy to share it, and sometimes they simply forgot to link it there.

If your own mod isn’t stored in a git repo yet, you can learn how to do that here.

Download the Source Code

The next step is to download the mod’s source code and place it in your own project’s Mods directory.

You could their plugin download as a zip and extract it, but consider cloning the repository to make it easy to update your copy with future changes to the mod.

Regardless of if you extracted a zip or cloned, make sure that the name of folder containing the mod’s .uplugin file exactly matches the mod’s mod reference - the filename of the mod’s .uplugin file. Otherwise the editor will not properly identify the plugin.

Dependencies

Depending on how the mod is set up, you may need to download additional mods or tools to be able to build and use a mod in the editor. The exact steps to follow will vary depending on the mod, but this section will cover some common cases.

Look for text files in the root folder of the repo that might explain additional changes that need to be made to your project for the mod to work.

Other Mods

If the mod you’re trying to load has a dependency on another mod, you will also need to obtain the source code for the dependency mod and import it into your project.

You can find out what other mods a mod depends on by looking at the dependencies section of its .uplugin file.

This section lists other mods by their mod reference. You can learn more about this section on the Releasing Your Mod page.

An example of this is the PowerSuit Modules mod, which requires both the PowerSuit and MAMTips mods to be installed.

Note that a mod’s display name does not always match its mod reference. Furthermore, a dependency mod could be hidden for display on the mod repository. In this case, you can track down the mod page by entering the mod reference into a ficsit.app URL. For example, to find the mod page for the MAMTips mod, you can enter MAMTips into the URL like so: https://ficsit.app/mod/MAMTips. Note that the URL is case sensitive.

Header Edits

Although Access Transformers should be used instead where possible, some mods may still require you to manually edit the header files included with the starter project. Be careful, as these edits will take effect for every other mod you have in that starter project, and they will be erased when you update your starter project as the game updates.

If you find yourself having to make a header edit, make sure to leave a note about it somewhere you can find later so you can reapply it after updates and understand why you made it!

Asset Edits

Similar to header edits, a mod may require you to modify certain placeholder blueprint assets in your project to function correctly.

An example of this is MAM Enhancer, which modifies a field on a base-game widget to be Instance Editable so the mod can read the field. Without making this edit, the editor will not compile the mod. There is a note in the repository root that informs potential viewers of this requirement.

Non-Standard Placeholders

It is possible for a mod to require non-standard placeholder assets, to be created, or even a complete starter project, for a mod to work properly in the editor. If the mod references assets that your project lacks placeholders for, the editor will blank out these fields, potentially causing errors.

An example of this is the PowerSuit mod requiring a placeholder for the hoverpack arm animations to exist. Without this file present, the equipment item will be packaged with no arm animations, leading to improper behavior in-game.

Accidental References to Files from Another Mod

Even after making sure you downloaded and set up any dependency mods, you could still be missing some required files from another mod. This issue is more likely to be encountered when trying to package the mod from the editor, but it could still affect the C++ build process.

It’s easy for a dev that works on multiple mods to accidentally reference files in their own mod without realizing, and the possible errors that can stem from this are difficult for the dev to detect since they have those files in their editor.

If you see errors about missing files from another mod, you should contact the developer and let them know so they can fix the problem accordingly.

Purposefully Excluded Files

Some mod developers may chose to leave certain files out of their mod’s source code for various reasons, such as copyright or privacy. This issue is more likely to be encountered when trying to package the mod from the editor, but it could still affect the C++ build process.

If you encounter this issue, you should contact the mod developer and either ask them for a copy of the files or how to work around their absence.

Building in Visual Studio

Although not all mods will require you to rebuild C++ files, it’s good practice to do so anyways to avoid any potential issues. Make sure to follow the below steps before trying to build the project again.

Regenerate Visual Studio Files

By introducing another mod to the project, you have changed the project’s structure. As such, you will need to regenerate Visual Studio project files before you can proceed, otherwise Visual Studio will not notice the new mod.

Seemingly Ignored Access Transformers

Many mods make use of Access Transformers to gain additional access to the game’s code. Due to how this system works, Visual Studio may mistakenly ignore the access transformers of the mod you just imported, leading to errors when you try to build it. You can learn more about this issue, and how to correct, it here.

Build the Project

Build for Development Editor in Visual Studio, and once that succeeds, build for Shipping as well.

If the build fails, review the previous steps to make sure you have all required dependencies and have forced a rebuild of the access transformers. If it’s still failing, ask for help on the Discord and/or from the mod developer.

Loading the Mod in the Editor

Once you have successfully built the mod in Visual Studio you should be able to open the Unreal Editor and package the imported mod yourself with Alpakit. This is a good test of whether or not you have imported the mod’s files correctly.

Be aware that sometimes the presence of an improperly set-up mod can prevent the editor from packaging any other mods until the mod is removed or the issues are resolved. Follow the directions here if you need to disable mods while still keeping their files around.

Something is Still Wrong

If you get an error when trying to package the mod along the lines of "UATHelper: Package Mod Task (Windows): ERROR: System.IO.DirectoryNotFoundException: Could not find a part of the path", make sure that the name of the mod folder exactly matches the mod reference.

If you are still encountering issues, consider asking for help on the Discord and/or from the mod developer.