Safely Re-Organizing A C++ Project into Folders

Hey everyone,

If you’re like me, your project’s C++ Source folder might start to look a little messy as it grows. What begins as a few files can quickly become a flat, confusing list of dozens of headers and source files.

This guide is a step-by-step walkthrough on how to take that flat structure and organize it into clean, logical subfolders, just like you see in professional projects like Epic’s Lyra sample. The end result will be a much cleaner, more scalable project.

This process can seem intimidating, but if you follow these steps carefully, you can do it without breaking your project or corrupting your Blueprints. I just did it for my project, and I’m writing this guide to help others who are not C++ confident.


Step 0: Backup Your Project!

Before you do anything, please, please, backup your project. The safest way is to use a source control system like Perforce or Git and submit all your current work. If you don’t use source control, zip up your entire project folder as a backup. Do not skip this step!


Step 1: Close Everything

Make sure you have completely closed both Unreal Editor and your IDE (Visual Studio or Rider). This is critical to prevent file-locking issues.


Step 2: Create Your New Folder Structure

Go to your project’s Source/YourProjectName/ directory in Windows Explorer. Here, create the new folders you want to organize your files into. A good starting point is:

  • /AbilitySystem/

  • /Character/

  • /Components/

  • /Data/ (For item definitions, etc.)

  • /UI/

  • /Core/ (For your GameMode, PlayerController, etc.)


Step 3: Move Your Files

Now, simply drag and drop your existing .h and .cpp files from the root folder into their new, respective homes. Keep your main ProjectName.Build.cs, ProjectName.Target.cs, and ProjectName.h/.cpp files in the root.


Step 4: Regenerate Project Files (The Magic Step)

This is the most important step. Right-click on your .uproject file and select “Generate Visual Studio project files”.

This tells Unreal’s Build Tool to scan your Source folder, find the new locations of all your files, and update your Visual Studio solution to point to them. If you skip this, Visual Studio won’t know where to find your files and your build will fail.


Step 5: Configure Your Build.cs File

Now we need to tell the compiler about our new folder structure so it knows where to look for headers.

  1. Open your newly generated solution in Visual Studio.

  2. Find and open your YourProjectName.Build.cs file.

  3. Inside the main constructor, we’ll add a line to tell the build system to look in our main project folder for includes. This is the simple, Lyra-style approach.

Add the following line:

// In YourProjectName.Build.cs

// Add this line before the other module dependencies
PublicIncludePaths.Add("YourProjectName");

This tells the compiler that Source/YourProjectName/ is a primary “home base” for includes, allowing it to find files in your new subfolders.


Step 6: Fix Your #include Paths

When you try to build, you’ll now get errors like C1083: Cannot open include file. This is normal! It just means we need to update our #include statements to use the new paths.

For example, if your character class needs to include your item data asset:

  • Old Code: #include "ItemData.h"

  • New Code: #include "Data/ItemData.h"

You have to go through your files and update these paths. A great way to do this quickly is to use the “Find and Replace in Files” tool in Visual Studio (Ctrl + Shift + F).

A note, you don’t need to do this for cpp files that live in the same space as their headers.


Step 7: Rebuild Your Project

Once you’ve fixed all the include paths, do a full Rebuild of your project. I personally close everything again, and delete the generated folders (Binaries, Intermediate, Saved, DDC, Saved, .vs, .vsconfig, .sln).

You can also do it in Visual Studio, right click → Rebuild. I just have trust issues with VS.


Step 8: Verify in Unreal Editor

If the rebuild succeeds, you’re ready to test!

  1. Open the Unreal Editor.

  2. Open Key Blueprints: Open your main player character Blueprint and any others that inherit from your moved C++ classes.

  3. Compile and Save: Hit the Compile and then Save button on each one. If they save without errors, it means the engine has successfully re-linked them to their C++ parent.

  4. Playtest! Jump into your game and make sure everything still works as expected.


Bonus: Following “Include What You Use” (IWYU)

While you’re cleaning things up, it’s a good time to adopt the IWYU standard for faster compile times. The rules are simple:

  1. Matching Header First: In every .cpp file, make sure the very first #include is its own matching .h file.

  2. Be Specific: Instead of including giant headers like Engine/Engine.h, include only the specific headers you need (e.g., #include "GameFramework/Character.h").

  3. Forward Declare: In your .h files, use forward declarations (class UMyComponent;) for pointers instead of including the full header whenever possible.

That’s it! It looks like a lot of steps, but it’s a logical process that will leave you with a much more professional and manageable C++ codebase.