HOW UNREAL THINKS · READING SOURCE CODE

Public/Private/Classes: why module boundaries are enforced by the compiler

You've already seen the Public and Private folders inside almost every engine module and, most likely, decided they're just a team convention — "here's where we put things we can share, here's what's internal." This isn't a guess, it's literal mechanics: UnrealBuildTool physically does not add the contents of Private to the list of paths the compiler sees when building any other module. Not "it's not done" — it's "impossible" through the normal pipeline.

A slower, hands-on version of this same material

Here, modules are examined from the perspective of reading other people's engine code. The "Unreal C++ Fundamentals" stage in Learning approaches the same Public/Private boundary from the other side — there, you write your first module and your first Build.cs with your own hands, before recognizing that same structure in the engine source.

01What is it?

Every engine module (Engine, CoreUObject, Renderer, your own game module) is physically laid out across the directories Source/<Module>/Public, Source/<Module>/Private and, in some older modules, also Source/<Module>/Classes.

This isn't archival file organization "for tidiness" — it's the literal entry point to the UnrealBuildTool (UBT) algorithm, which decides, when building any module, which physical directories the compiler is even allowed to take headers from for #include. Here's why it's built this way, rather than as "we just agreed on it."

02Why does it exist?

The problem

Imagine the Renderer module — it draws the frame: traverses the scene, builds draw lists, works with GPU commands. Inside, it surely has a header like SceneRendering.h, which describes the FSceneRenderer class with fields and methods that no one outside the module needs to know about — that's the internal implementation detail of this specific rendering implementation.

Stop for a minute

Your game module depends on Engine, and Engine ultimately depends on Renderer — dependencies in Unreal are transitive. Does that mean #include "SceneRendering.h" should compile directly in your gameplay code, just because somewhere deep in the dependency graph that link exists? Think about what would happen to the engine if the answer were "yes, it compiles."

The reason

If any header from any transitively linked module were accessible from everywhere, Epic would have no way to change the internal structure of FSceneRenderer between engine versions without breaking an unpredictable number of third-party projects that accidentally (or deliberately) pulled that header into themselves. A module would cease to be a module in the engineering sense — a unit that can be changed from the inside without touching the contract on the outside — and would turn into one flat pile of thousands of headers with no real boundaries.

⚠ What exactly breaks without a physical boundary
  • Encapsulation becomes a nice wish — "don't include this header" works as long as everyone on the team remembers it and code review enforces it; it doesn't work when the team is fifty people, and dozens of Epic engineers are changing the engine simultaneously.
  • Refactoring a module's internals becomes unpredictably dangerous — you can't rename a private field of FSceneRenderer without grepping the entire source tree for "what if someone used this," because there's no formal guarantee that no one did.
  • Compile times grow unnecessarily — every header transitively accessible from everywhere is a potential extra #include in someone else's .cpp, which means extra preprocessor and compiler work on every rebuild.

03What problem does it solve?

The division into Public/Private turns "please don't include this" into a physical, compiler-level restriction: a header lying in Private simply does not resolve via #include from another module through the normal, standard build path — not because someone forbade it, but because the compiler has no way to know where to look for it.

04How it works

Constraints the solution had to satisfy

The mechanism had to require nothing from the developer beyond normal file work (no special access attributes, which simply don't exist in C++ at the header level), work identically for all engine modules and any third-party plugin without exceptions, and create no runtime overhead — this entire boundary must exist only at build time, not in the compiled binary.

The solution: include paths are formed by directories, not by access rights

C++ has no built-in notion of a "module" with header visibility control (actual C++20 modules are a separate, recent language feature, and Unreal Build Tool was built independently of them, at the preprocessor level). So the boundary had to be built not with language facilities, but with build-system facilities: which directories are physically passed to the compiler as -I (header search paths) when building a specific module.

Here's what actually happens inside UnrealBuildTool (UEBuildModuleCPP.cs) when forming paths for a module:

For EACH module being built in the project:

  Source/MyModule/Classes/**  ─┐
  Source/MyModule/Public/**   ─┼─► added to PublicIncludePaths
                                 │    THIS module publishes these paths
                                 │    to EVERYONE that depends on it
                                 │
  Source/MyModule/Private/**  ─┴─► added ONLY to the module's own
                                     include paths for compiling the files
                                     of MyModule itself — not published outward

Another module depending on MyModule via Build.cs:
  receives only the PublicIncludePaths of MyModule in its -I list
  (Public + Classes) — Private is physically absent from its header
  search path list during its own compilation
Let's look into the engine source: what this looks like in UnrealBuildTool code

A real fragment of the AddDefaultIncludePaths() method (Programs/UnrealBuildTool/Configuration/UEBuildModuleCPP.cs):

UEBuildModuleCPP.csC#
// Add the 'classes' directory, if it exists
if (ModuleDir.TryGetDirectory("Classes", out DirectoryItem? ClassesDirectory) && ClassesDirectory.ContainsFiles(SearchOption.AllDirectories))
{
    PublicIncludePaths.Add(ClassesDirectory.Location);
}

// Add all the public directories
if (ModuleDir.TryGetDirectory("Public", out DirectoryItem? PublicDirectory) && PublicDirectory.ContainsFiles(SearchOption.AllDirectories))
{
    PublicIncludePaths.Add(PublicDirectory.Location);
    /* ... */
}

Notice — Classes and Public literally go into the same list, PublicIncludePaths. This isn't a naming coincidence: Classes is a legacy from early engine versions (before the explicit Public/Private split existed), where all headers with UCLASS() historically lived in that directory. New modules (for example, EnhancedInput) are created today without Classes at all — only Public/Private — but old ones, like Engine, still keep a significant portion of gameplay classes there (Engine/Classes/GameFramework/Actor.h — yes, the Actor.h you know physically lives exactly there). To the compiler, there's no difference: both directories are equally public.

Symmetrically for Private: in the same file, the directory is added to the list of paths visible only when compiling files inside the module itself — not to the list passed to consuming modules.

The second level of the boundary: the module dependency must be declared at all

A header being public is a necessary, but not the only, condition. Even a completely public header of another module does not resolve via #include until your module has declared a dependency on it in .Build.cs — via PublicDependencyModuleNames or PrivateDependencyModuleNames.

MyGame.Build.csC#
public class MyGame : ModuleRules
{
    public MyGame(ReadOnlyTargetRules Target) : base(Target)
    {
        PublicDependencyModuleNames.AddRange(new string[] {
            "Core", "CoreUObject", "Engine", "InputCore"
        });
    }
}

This exact line is the reason #include "GameFramework/Actor.h" works in your game module: Actor.h lies in Engine/Classes, the Classes directory is published by the Engine module as part of PublicIncludePaths, and your module has explicitly declared a dependency on Engine. Three conditions came together simultaneously — not just one of them.

Actor.h lies in a Public-like directory (Classes)Without this, the header wouldn't land in anyone's PublicIncludePaths at all — no dependency would save it.
The Engine module publishes this directory to other modulesIt publishes automatically, simply by virtue of the file being in Classes/Public — Epic doesn't mark each header individually as public.
MyGame.Build.cs explicitly declares a dependency on EngineWithout this line, your module's compiler never receives the path to Engine headers in its -I list at all, even though Actor.h lies in a fully public directory.

Hence the answer to the original Renderer example: even if a specific internal header somehow ended up physically in the Public directory of the Renderer module — which Epic deliberately doesn't do, precisely for the sake of this boundary — your game module still couldn't include it without an explicit dependency on Renderer in its own Build.cs, and such a dependency almost never makes sense for gameplay code and doesn't appear in template projects.

Public vs Private module dependency — not just about headers, but about what your consumers see

The difference between PublicDependencyModuleNames and PrivateDependencyModuleNames is not "the same thing, but for modules instead of files" — it's a direct extension of the same idea one level up: if module A declares a dependency on B as public, then any module C that depends on A automatically gains access to B's public headers — the dependency leaks outward. If A declares a dependency on B as private, C learns nothing about B's existence — A used B internally, but isn't obliged to "lend" that link to everyone who depends on A.

💡 Senior Thoughts

If a type from another module appears in your module's public header — that dependency must be Public in Build.cs, otherwise consumers simply won't find the header. If the type is only used inside .cpp files — the dependency should be Private: any extra Public dependency leaks across the entire project graph and sooner or later turns into someone else's inexplicable extra include, added "just in case," which nobody remembers the reason for anymore.

05When it matters to think about this — and when it doesn't

Thinking about the Public/Private boundary matters when…It's not so critical when…
You're designing a new module or plugin of your own and deciding where to put a new header You're writing ordinary game code inside a single module (for example, the standard Source/MyGame) — there, everything that isn't in Classes/Public is automatically private relative to other modules, so there's almost nothing to actively think about
You're reading engine source and trying to understand why some headers include freely, while others get "file not found" from the compiler The project consists of a single game module with no plugins — this entire boundary concerns interaction BETWEEN modules; within a single module, files see each other without restriction anyway

How this can be abused

The physical UBT boundary is not cryptographic protection: nothing stops a developer from manually appending the path to someone else's Private directory in Build.cs via PrivateIncludePaths.Add(...) with an absolute or relative path and forcefully including another module's internal header. It compiles. That is precisely the abuse: such code silently breaks on the next engine update, because the internal header's author legally (by API convention) is not obliged to maintain backward compatibility for code that "shouldn't have gotten there" — and it got there.

06Common mistakes

Beginner mistake: trying to fix "file not found" by adding an include path instead of a dependency in Build.cs

Upon seeing the compiler error "cannot open source file," the typical first impulse is to manually write the path to the needed header via PublicIncludePaths.Add(...) in your own Build.cs. It sometimes even works (the header is found), but leaves the module without an explicitly declared dependency — which means without a guarantee that the needed module will even be built and linked before yours, and without the right to legitimately use functions from its .cpp files (the header alone doesn't satisfy the linker). The correct first step is always to add the module itself to PublicDependencyModuleNames/PrivateDependencyModuleNames, not to include its directory directly.

Middle-developer mistake: throwing everything into Public "just in case, so you don't have to move it later"

Putting a new header into Public by default, even when it's needed only inside two .cpp files of the same module, seems safe — but every extra public header expands the list of things that theoretically any other module in the project could include, and therefore the list of things you can no longer quietly rename or delete during refactoring without checking the whole project. The rule is simple: a header is public only if at least one real consumer outside the module already exists or is guaranteed to appear — not "just in case."

How a senior reasons: a module boundary is the same architectural tool as a class's public/private method

The difference between a module's Public/Private header and a C++ class's public/private method is only a matter of scale. Both exist for one and the same purpose: to give the author the right to change internal structure without asking permission from all consumers, as long as the external contract (the public interface) isn't violated. A developer who freely juggles Public/Private inside a class, but has never thought about the same choice at the module level, applies encapsulation only halfway.

07Practice

Try it yourself
You have a plugin with two modules: InventoryCore (inventory logic, no UI) and InventoryUI (widgets that use types from InventoryCore). Inside InventoryCore there's FInventorySlot — a public slot structure that the UI module must see — and FInventorySortHelper — a private class for internal sorting that should be visible to no one outside. Before reading the breakdown, solve it yourself: in which directories should these two headers physically live, and what type (Public/Private) should the InventoryUI dependency on InventoryCore be in its Build.cs.
Show the expected reasoning

FInventorySlot.h — in InventoryCore/Public/: it's part of the module's contract, and it must be visible to any consumer, including InventoryUI.

FInventorySortHelper.h — in InventoryCore/Private/: it's used only inside InventoryCore's own .cpp files, no other module should rely on it, and therefore no other module should physically be able to include it.

The InventoryUI dependency on InventoryCore in InventoryUI.Build.cs — PublicDependencyModuleNames, if types from InventoryCore (for example, FInventorySlot) appear in the public headers of InventoryUI itself (for example, in a widget signature) — then this dependency is obliged to "leak" further, to any module that might include InventoryUI in the future. If InventoryCore types were used only inside .cpp files of the InventoryUI module, the dependency would be better declared as PrivateDependencyModuleNames.

08Frequently asked questions

?What does the third directory, Internal, mean? It sometimes appears next to Public/Private in newer engine modules.

It's a newer, intermediate boundary: headers from Internal (for example, Engine/Internal) are added to a separate include path list, which by default isn't inherited by arbitrary external modules as freely as Public — it's intended for APIs that should be visible to close, trusted modules of the same engine "family," but not to any third-party plugin. For most encyclopedia readers at this stage, it's enough to know that such an intermediate level exists — the details of how to hook into it aren't needed until you're writing a module inside the engine itself.

?If a header physically lies in Private, but I know its relative path on disk — why not just include it via a long relative #include?

Technically a specific compiler might tolerate it, but that's not the same as "the path resolves through the module's include paths" — such an include is fragile to any file move (and Private headers are moved and renamed without warning precisely because they're not obliged to be stabilized as public API), and it's the first candidate to break on an engine version update. It's the same workaround described in the "How this can be abused" section — it compiles, but deliberately violates the contract that Epic itself never promised to preserve.

?Why does Engine have a Classes directory, while newer modules like EnhancedInput don't?

Classes is a historical artifact: before the explicit Public/Private split appeared in the engine, all headers with UCLASS() lived en masse exactly there. Modules that exist from those times (Engine is one of the oldest engine modules) preserve this structure for backward compatibility — moving thousands of headers into Public would affect the include paths of a huge number of third-party projects. New modules are created right away with the current scheme — only Public/Private, without Classes, because they have no inherited history that must not be broken.

09What the reader should start noticing

The compiler error "cannot open include file" stops being perceived as "somewhere there's a typo in the path" and starts being read as a specific, diagnosable question: is the header public at all, or is it in Private? Is the module where it lives even declared as a dependency in Build.cs?

Opening any Build.cs — yours or someone else's — you start seeing not a comma-separated list of names, but a map of what this module is physically allowed to include, and what it, in turn, allows its consumers to include.

The path to a header (Classes/, Public/, Private/) in other people's engine code starts carrying information by itself — you know what it means even before opening the file.

10Summary

  • ✔ explain why the Public/Private division is a UnrealBuildTool restriction, not just a team convention
  • ✔ name the three conditions that must align for a #include from another module to compile
  • ✔ explain the difference between PublicDependencyModuleNames and PrivateDependencyModuleNames in terms of what "leaks" further down the dependency graph
  • ✔ decide which directory (Public/Private) to put a new header of your own module into
  • ✔ based on the compiler error "cannot open include file," understand what exactly is missing — a dependency in Build.cs or the very fact that the header is public
  • ✔ explain why forcibly including someone else's Private header compiles, but remains a contract violation

Material prepared for UE C++ Academy. Original article — uecppacademy.com. If this material helped you understand Unreal Engine — you can support the project's development.

© 2026 UE C++ Academy. All rights reserved. For copyright or technical issues — support@uecppacademy.com