How to properly reorganize your Unreal Engine project structure
Learn how to manage assets and how to reorganize files and folders in Unreal Engine. Handle file paths, fix redirectors, and reorganize projects efficiently. Use version control to revert back to the working state when something breaks.
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
- Create a version (or a commit)
- Move files
- Fix redirectors
- Test if everything works
- 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:
- Create a new folder
- Move all the files in there
- Fix redirectors
- Delete the old folder
- 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.
Tutorials and Development Updates
Anchorpoint for indie development - Midheimur
How the team behind the Midheimur project creates beautiful landscapes for a game about Slavic history.
Anchorpoint for indie game development - Nightmare Studios
How Nightmare Studios uses Unreal Engine 5 and clever marketing tricks to build and release their first indie game.