What's a Native Project?

Article written by Branden T.

Various tools around Unreal, such as UGS, BuildGraph, and Gauntlet, are simpler to use or only work with native projects. A native project is one that an instance of Unreal will recognize as being a part of its directory structure. Conversely, a non-native, or “foreign” project, is a project that sits outside of the Unreal directory structure. This article aims to explain in detail how to set up a Native Project, with clear examples.

Projects are discovered by Unreal by searching for their .uproject files one level deep from the top level of the Unreal directory structure, or one level deep from any path listed in then UE4Games.uprojectdirs file. This file is also located at the top level of the Unreal directory structure, and all the paths listed inside it are relative to the top level. For a project to be considered “Native” to an instance of Unreal, it needs to be in one of these locations within the directory structure of the Unreal instance that’s running the project.


Top Level Project Folders
Here’s the top level of an Unreal instance’s directory structure. For this example we’re using a local copy of the //UE4/Main stream from Epic’s Perforce server:

In this example “VanillaProj” is an example project. Its directory structure looks like this:

Since VanillaProj.uproject is one level below the top level of the directory structure, this is considered a native project. If it were above the top level, or anywhere else outside of the directory structure, it would be a foreign or non-native project. By this definition, the “EngineTest” project above in the first image is also a native project.


Another example of a native project would be any project that is discoverable from any paths ( relative to the top level ) listed in UE4Games.uprojectdirs ( highlighted at the bottom of the first image ) :

In this example, any project with its .uproject file located one level below [UE Root]/Samples/Games/* will be considered a native project. So the ShooterGame sample in this stream would be considered a native project:

Note: All uprojectdirs files (*.uprojectdirs) at the top level directory will be read for search paths, so you can create your own if you don’t want to use UE4Games.uprojectdirs.



Informative thread, i have a question on the UE4Games.uprojectdirs folder though. are we allowed to write …/ in addition to ./ to get the parent directory of the engine folder included as a native project as well?

There are benefits to using a native project, but having a game repo inside an engine folder with it’s own repo can have disadvantages which if we have the ability to move the project one folder out are largely resolved.