Rename, Merge or Split Mods

Main article: Guide

If you have ever tried to rename a mod, merge multiple mods into one, or split one mod into multiple, you will probably have noticed that there is no built-in editor support for performing these operations. The way the dev kit remaps file paths and hides mods other than the one being worked on further complicates this task. However, all of these operations are possible by carefully following the processes described here.

General Information

These are some things to you should understand before attempting to perform any mod renaming, merging or splitting.

Locating Your Mod's Source Assets

You will need to know where your source files are for your mod. Mods are stored within the dev kit installation directory under Games/ConanSandbox/Content/Mods. If you have the dev kit running, you can quickly locate the source files by pressing the "Conan Exiles Dev Kit" button in the toolbar, then pressing the "Active mod folder" button in the dialog that opens to open the folder in Windows explorer.

Backup Your Mods!

Before attempting to perform any of these actions, it is very important that you backup your mod(s). Any mistake or missed step along the way might leave you with broken assets which could be difficult to recover.

If you are using a version control system, you will not need to make an explicit backup since you can always revert back to an earlier working version. However, feel free to make one anyways. It doesn't hurt anything.

Creating a Backup

Note: Before creating a backup, it is recommended that you close the dev kit if it is running to verify that any pending changes have been saved.

Using Windows Explorer (or any program you choose), copy the entire "Mods" directory to another location. Be careful to copy it and not move it! You can optionally only copy specific mods if you do not want to copy all of them.

Restoring from Backup

If you break a mod and need to restore it from your backup, just follow these simple steps while the editor is not running:

1. Delete the broken mod folder from the Mods directory.
2. Copy the mod folder from your backup to the Mods directory.

Running the Editor with Dev Kit Mode Disabled

Normally, when you run the dev kit, it runs the editor in a special mode where mod paths get remapped, inactive mods are hidden, editing assets creates appropriate override assets in the mod folder, and there are tools for building and deploying mods. All of these features are great (and required) when you are working on mod content, but they get in the way of certain asset move/rename operations we need to perform when renaming, merging or splitting mods.

Fortunately for us, we can run the editor without all of those features simply by removing a parameter from the command line when launching it. If you are used to running the dev kit from the Epic Games launcher, go ahead and forget about that for now. We will be doing it a bit differently.

Step 1: Locate the dev kit installation directory

This directory will have been set when you initially installed the dev kit. Open it in Windows Explorer.

Step 2: Make a copy of RunDevKit.bat

Note: The file name may appear as simply RunDevKit without the ".bat" extension if your Explorer is not configured to show file extensions.

Make a copy of the file RunDevKit.bat in the dev kit installation directory. Keep it in the same location. You can call it whatever you want, but we will call it RunEditor.bat to denote that we are running the editor without the dev kit features.

Step 3: Edit the copied file

Right-click on RunEditor.bat (or whatever you called it in the previous step) and choose "Edit" to open it in notepad. Here you will find the command line used to launch the dev kit. We will modify it slightly by removing -ModDevKit. Do not make any other changes. Save the file and close Notepad.

Step 4: Running

You can now double-click your new RunEditor.bat file to run the editor with dev kit mode disabled. To run it normally, run the normal RunDevKit.bat or run from the Epic Games launcher.

Note: When launching with dev kit mode disabled, you will get a warning dialog about a missing GraniteSDK environment variable. Just press OK and the editor will continue to load. Once loaded, you may see the log appear with some additional warnings. Go ahead and ignore those as well. Some things won't be working in this mode, but the thing we care about (moving assets) will work fine.

IMPORTANT

Do not edit any assets when running with dev kit mode disabled. Also ignore any "reimport assets" messages that appear. Bad things can happen to your dev kit installation and/or your mods if you start making changes. You should only run in this mode when specifically required to move assets in the manner described later in this document.

Understanding Path Remapping

In order to understand what you are doing when renaming, merging or splitting mods, it helps to understand a little bit about how the dev kit remaps asset paths. In your mod's source directory, outside of the editor, you will notice two folders there: Content and Local. Each of these serves a different purpose and is treated differently.

Content directory

This directory is used for mod assets that will replace standard assets. The paths for these assets are remapped to match the asset they are replacing. In the editor, you will not see any difference between an asset replaced by your mod and one that is not. Simply opening and saving an asset is all that it takes to create a replacement asset in your mod.

For example, this on your file system

Content/Mods/MyCoolMod/Content/Systems/AI/NewAI/HumanAIController.uasset

would be here in the editor

Content/Systems/AI/NewAI/HumanAIController.uasset

Local directory

This directory contains assets that your mod adds rather than replaces. The paths for these assets are remapped such that the Local directory itself is omitted from the path.

For example, this on your file system

Content/Mods/MyCoolMod/Local/MyCoolModController.uasset

would be here in the editor

Content/Mods/MyCoolMod/MyCoolModController.uasset

Assets know where they are

It is important to understand that the path to an asset in Unreal is part of that asset. It knows where it is, and other assets also know where it is. For this reason, an asset cannot simply be moved on the filesystem. It has to be moved in the editor so that it is properly updated with its new path information and so that assets referencing it are updated also (or redirectors are put in place, but that is a whole topic of its own).

In the Conan dev kit, assets believe they are at their remapped location. They have no knowledge of their physical location on disk. This is useful to understand when we get into the step-by-step processes later in this document.

Renaming a Mod

So, you want to change the name of your existing mod? Read the important stuff in the "General Information" section above, then follow these instructions. Make sure to follow them precisely or you may end up breaking your mod. (Good thing you made a backup first, right?)

Part A: Outside of the Editor

Make sure the editor is closed before you start.

In your mod's source directory, we need to move everything out of the Local folder so that the real paths of the assets match the remapped paths used in the dev kit. In Windows explorer, this can be done by selecting everything inside of the Local folder, cutting it, and then pasting it one level up in the root folder for the mod.

(If you happen to have a folder named Content inside of Local because you put one there, then you will need to rename or temporarily remove the mod's main Content directory before moving the contents of Local to avoid a conflict.)

Part B: Inside the Editor

Once your Local assets have been moved, you will want to run the editor with dev kit mode disabled as described earlier in this document.

1. Once the editor is open, use the Content Browser to navigate to Content/Mods.
2. Create a new folder with the new name you want to use for your mod.
3. Navigate into your existing mod folder.
4. If you do not already have it, open the Sources Panel in the Content Browser by pressing the small button to the left of the search box. This will display a tree view of all of the folders in the project.
5. Move everything except for the Content directory from your existing mod folder to the new one by dragging it from its current location to the new location in the Sources Panel. It is important that you do not touch the Content directory of your mod, or anything in it, at all.
6. Once the moves are complete, close the editor.

Part C: Outside of the Editor Again

Now that you have moved your assets to your new mod folder, you will need to go into that folder on your filesystem and do the following things.

1. Create a Local folder and move everything into it that you previously had moved out of Local at the old location.
2. Move the Content folder (and everything in it) from the old mod location to the new one.
3. Move modinfo.json from the old mod location to the new one (it may appear as just "modinfo" without the ".json" extension if you have file extensions hidden).
4. Open modinfo.json in a text editor, such as notepad, and change the name property from your old mod name to your new mod name.

(If you renamed/moved the mod's main content directory in Part A, you should restore it now.)

Tip: You can optionally move the active.txt file to your new mod location to make it the active mod next time the dev kit starts up.

Part D: Into the Dev Kit

Now you need to run the dev kit the normal way, with dev kit mode enabled. If necessary, make sure to switch it to your new mod from the dropdown next to the "Conan Exiles Dev Kit" button in the toolbar and let it restart. Now, just some final steps in the editor:

1. If you have modified any standard game assets to refer to one or more of your mod assets, you may need to manually fix up those references now.
2. Make sure things look right and build and test your mod. If all went well, hopefully the only issues you might have to deal with are any broken references you missed in the previous step.

Merging Mods

This section describes moving the content of one mod into another mod resulting in a single mod with all of the features of the original two mods. Read the important stuff in the "General Information" section above, then follow these instructions. Make sure to follow them precisely or you may end up breaking your mod. (Good thing you made a backup first, right?)

Note: In this section, we refer to the mod being merged into as the target and the mod that is merging in as the source.

Part A: Resolve File Conflicts

Before you can merge one mod into another, you need to make sure they do not touch any of the same assets. If they do not, you can skip this part.

• If both mods touch the same file in the Content directory, you will need to manually merge them later.
  1. Make a record of any changes made to the file in the source mod.
     • If it is a blueprint, take screenshots of everything you did to the file in the source mod. You can diff the asset against the unmodded asset in the editor to see what you changed.
       1. While running the editor with dev kit mode disabled, type the file name into the content browser filter. You will see both versions (the unmodded one and the modded one).
       2. Select the unmodded version, then hold Ctrl and select the modded version to add it to the selection.
       3. With both selected, right-click one and choose "Diff Selected" from the context menu to open a diff.
  2. Delete the conflicting file from the source mod's directory. You will need to apply the changes from that file manually near the end of this process.
• If both mods have a file with the same path in the Local directory, you will need to rename the source mod's file.
  1. While running the dev kit (dev kit mode enabled) with the source mod active, rename the asset so that it no longer conflicts with an asset in the target mod.

Part B: Merge Content Directory

This part is fairly straightforward. In your filesystem, with the editor closed, copy/move everything from the Content directory of the source mod to the Content directory of the target mod. There should be no conflicting files after completing part A above.

Part C: Merge Local Directory

This part is a bit complicated. It is important to follow the steps exactly.

Step 1: Outside of the editor

Make sure the editor is closed before you start. This step is performed on your filesystem.

In the source mod's directory (we do not need to touch the target mod right now), we need to move everything out of the Local folder so that the real paths of the assets match the remapped paths used in the dev kit. In Windows explorer, this can be done by selecting everything inside of the Local folder, cutting it, and then pasting it one level up in the root folder for the mod.

(If you happen to have a folder named Content inside of Local because you put one there, then you will need to rename or temporarily remove the mod's main Content directory before moving the contents of Local to avoid a conflict.)

Step 2: Inside of the editor

Once your Local assets have been moved, you will want to run the editor with dev kit mode disabled as described earlier in this document.

1. Once the editor is open, use the Content Browser to navigate to Content/Mods.
2. Navigate into your source mod's folder.
3. If you do not already have it, open the Sources Panel in the Content Browser by pressing the small button to the left of the search box. This will display a tree view of all of the folders in the project.
4. Move everything except for the Content directory from your source mod folder to your target mod folder by dragging it from its current location to the new location in the Sources Panel. It is important that you do not touch the Content directory of your mods, or anything in them, at all.
5. Once the moves are complete, close the editor.

Step 3: Outside of the editor again

Now that you have moved your assets to your target mod folder, you should now go into that folder on your filesystem. Take all of the assets that you just moved over from the source mod in the editor and move them into the target mod's Local directory.

(If you renamed/moved the mod's main content directory in Step 1, you should restore it now.)

Part D: Apply Manual Changes

If you had any conflicting files in your Content directory that you removed during Part A, now is the time to reapply those changes. You do not need to do anything here for files that were renamed in the Local directory, as those changes should already be accounted for.

1. Run the dev kit (dev kit mode enabled) with the target mod active, and locate each of the conflicting assets.
2. For each asset, reapply changes from the source mod.

Part E: Cleanup

Run the dev kit (dev kit mode enabled) with the target mod active. You no longer need anything from the source mod, and are free to delete it if you wish (but hold onto the backup you made just in case).

1. Move/rename any local mod assets if their name or location no longer makes sense in the merged mod.
2. Build and test your mod. Make sure everything works and looks right.

Splitting a Mod

This section describes moving a feature or set of features out of an existing mod into a new mod created specifically for that feature set. Read the important stuff in the "General Information" section above, then follow these instructions. Make sure to follow them precisely or you may end up breaking your mod. (Good thing you made a backup first, right?)

Part A: Separate Features

Before you can start the process of splitting up a mod, you need to fist make sure that the features for each mod are distinct and do not need to touch the same files. Do all of this in the dev kit (dev kit mode enabled) with your original mod active.

1. Any changes to standard game assets (things that end up in your mods Content directory) have to go to one mod or the other, so figure out where each one needs to go.
   • You could split it up so that both mods touch the same file to do their own things, but then a person would not be able to run both mods together because one would override the other.
2. Any added assets (things that go in your mod's Local directory) also need to be split up by feature. For example, you might need a separate mod controller for each mod.
3. Once things are split appropriately, make a list of all of the assets that need to move to the new mod, separated based on whether they are in the Content or Local directory on the file system.

Part B: Create New Mod

While running the dev kit (dev kit mode enabled), create the new mod. Be sure to name it correctly. Once complete, close the editor.

Part C: Move Content Directory Assets

With the editor closed, go to the original mod's source directory on your filesystem. Move the desired assets from the Content directory of the original mod to the Content directory of the new mod. Be sure to keep them in the same relative location in the new mod. They won't work if they are in the wrong place!

Part D: Move Local Directory Assets

Moving the local assets is a bit more involved. Be sure to follow the steps precisely.

Step 1: Outside of the editor

Make sure the editor is closed before you start. This step is performed on your filesystem.

In the original mod's directory, we need to move everything out of the Local folder so that the real paths of the assets match the remapped paths used in the dev kit. In Windows explorer, this can be done by selecting everything inside of the Local folder, cutting it, and then pasting it one level up in the root folder for the mod.

(If you happen to have a folder named Content inside of Local because you put one there, then you will need to rename or temporarily remove the mod's main Content directory before moving the contents of Local to avoid a conflict.)

Step 2: Inside of the editor

Once your Local assets have been moved, you will want to run the editor with dev kit mode disabled as described earlier in this document.

1. Once the editor is open, use the Content Browser to navigate to Content/Mods.
2. Navigate into your original mod's folder.
3. If you do not already have it, open the Sources Panel in the Content Browser by pressing the small button to the left of the search box. This will display a tree view of all of the folders in the project.
4. Move the desired assets from your original mod to your new mod by dragging them from their current location to their new location in the Sources Panel. Make folders in the new mod as needed. It is important that you do not place anything inside of the Local folder in the new mod and that you do not touch the Content directory of your mods, or anything in them, at all.
5. Once the moves are complete, close the editor.

Step 3: Outside of the editor again

Now that you have moved your assets to your new mod folder, you should now go into that folder on your filesystem. Take all of the assets that you just moved over from the original mod in the editor and move them into the new mod's Local directory (create the Local directory if it is not there).

(If you renamed/moved the mod's main content directory in Step 1, you should restore it now.)

Part E: Cleanup

Run the dev kit (dev kit mode enabled) with the original mod active and do the following.

1. Move/rename any local mod assets if their name or location no longer makes sense.
2. Build and test your mod. Make sure everything works and looks right.

Repeat these steps with the new mod active.