How to properly reorganize your Unreal Engine project structure

Managing and reorganizing assets in Unreal Engine (especially if you come from Unity) is fragile, risky and often leads to bad surprises. However, while your projects grows, you come to the point where your old structure was not sufficient and you need to reorganize. This article includes some tips that will prevent panic attacks when managing your assets in Unreal.

What are Redirectors

Unreal Engine references assets via file paths. It’s the same like Blender or Maya are doing it. Unity is a bit smarter and uses a unique ID, but that’s another topic.

So once you move an asset (e.g. a tree) that is referenced somewhere, Unreal creates a redirector file at original location with the original file name, that points to the new file location of the tree. The level that imported the tree, will look at the redirector (that’s the old file path) and this redirector tells the level, where the original tree asset is.

If redirectors would not exist, everything would be immediately broken once you move a file. This is also what happens exactly when you would move a file in Windows explorer and not in the Unreal Asset Manager. Windows Explorer does not create any redirector files.

How to fix redirectors

To prevent having an overload of redirector files in your project, you can fix redirectors, which means to check all files that reference an asset and to change the file path to the new one, after you renamed or moved a file.

Unreal Engine has a command in the Asset Browser called “Fix Up Redirectors”. It traverses all uassets and umaps in your folder, fixes the file paths in all asset references and deletes redirector files.

If it always worked perfectly for you, then great. If not, follow these tips to eliminate bad surprises:

Tips for reorganizing your Unreal Engine project structure

1. Use version control

Use Anchorpoint, Perforce, Plastic SCM or Git (but don’t use the Unreal Engine Git plugin) when working with Unreal. It provides you a safety net, which comes in handy when reorganizing the project structure.

The workflow will look like this

1. Create a version (or a commit)
2. Move files
3. Fix redirectors
4. Test if everything works
5. Commit again

If something breaks, you can revert all your files of that project to a previous state where it was working.

2. Keep everyone involved

On larger projects, it's highly likely that someone may have dependencies checked out, which can make fixing redirectors unsafe. Additionally, it's essential to communicate that restructuring a project impacts all team members, requiring significant coordination. This involves announcing the intent and timing of the restructuring, specifying individual responsibilities like checking in files and adding local content to the project, and explaining potential risks like longer sync times and broken references in local files. Lastly, be sure to highlight that moving files should always involve updating any references in code or .ini files to avoid breaking the build.

3. Never move folders, only move files

Also don’t rename folders. This will create a huge overhead of everything inside that folder. The better approach is:

1. Create a new folder
2. Move all the files in there
3. Fix redirectors
4. Delete the old folder
5. Commit to version control

4. Don’t move or rename anything in Windows Explorer

For obvious reasons, because Windows Explorer cannot create redirector files. So everything will break.

5. Stick to a style guide, when setting up your new folder and naming structure

This GitHub page from Michael Allar is a good reference and provides a deep explanation why to do certain things. It takes a while to read but it’s worth it. Sticking to these guides in the future, will prevent the need for reorganizing files.

6. Reorganize your project in granular steps

Especially if your project is big, moving all files at once without fixing redirectors, testing and committing to version control, you will mess things up.

Move only a small set of files, then fix redirectors, then test if all the references work, then commit to version control. After that, move on with the other files

7. Don’t create assets with the same name before fixing redirectors

When you rename an asset from “tree” to “bonsai” and create a new asset in the same folder called “tree” it will create an error, because a file with the name “tree” (the redirector, which got created after the rename) already exists. So fix all redirectors before you create the “tree” asset.

How to Use Version Control When Reorganizing Projects

Once you have moved your files, fixed all redirectors, and tested if everything works as it should, then it's the right time to commit (or submit) everything to version control. In this example, we will use Anchorpoint, which is based on Git.

For each file you move, you will see a deleted file (the old file location) and a new file (the new file location). This is also true for renaming files. The "Fix up redirectors" command in Unreal is modifying files that are referencing your moved file. That's why these files show up in your changed files as modified (with a yellow pencil icon).

If everything is correct, just enter a message explaining why you have done it and press "Push".

If Your File Reorganization Broke Something

Go to Anchorpoint, select all files, and choose "Revert". This will reset all the files that you selected to the previous state.

Frequently Asked Questions

What are redirectors used for?

Unreal Engine's file referencing system is based on file paths, not UUIDs like Unity. When you move a file, Unreal creates a redirector pointing to it's new location. For example, if you open a level that was unaware of the file move (because it was closed), it will import the redirector, which will then import the correct asset. Without redirectors, you would end up with broken file links.

What is the correct folder structure in Unreal Engine?

There is no right answer to this because it depends on the project. Allar's style guide is a good example of an Unreal Engine project structure.

Why is version control important?

Version control is a backup system in case something goes wrong. Changing the file structure in an Unreal project is a fragile operation, and a version control system will make sure you don't destroy your project.