Directory Layout of Unreal Engine 3

Document Summary: This document outlines the Unreal Engine 3 directory structure for shared and game-specific data.

Document Changelog: Created; maintained over time.

Overview

The Unreal Engine 3 directory structure was designed to allow multiple games sharing the same code to coexist side by side. This is a typical scenario for licensees extending our codebase and want to keep the base engine content minimally changed for easier merging and testing.

The idea is to have one centralized code base to which additional game-specific modules can be appended. In addition to the code base, other things such as tools and documentation are often shared amongst the projects. For content, the base game engine sits along side any game-specific content.

We are developing two games with the same code tree so the presented solution will be tested extensively internally and refined over time.

In the past the main areas of conflict have been:

• Localization files
• Configuration files
• Script files
• Log files
• Content (maps, packages) - Shared and Game-spedific
• Binaries - Shared and Game-specific
• Game specific extensions (e.g. for maps) and protocols
• Lots of hardcoded names and assumptions in UE2

Base Structure

Binaries

All binary files are currently shared in the Binaries folder. Multiple build configurations can coexist, so executable (.exe) files created by Debug builds being prefixed with "DEBUG-" and Release builds will be prefixed with "LTCG-". The Lib subfolder contains Program Debug Database (.pdb) files which are used for stack walking/error reporting in release builds.

Development

All non content-related development is centralized in the Development directory.

Documentation

Unreal Engine 3 documentation can be found in the Documentation directory.

External

Any tools and utilities that were developed by external parties and partners are located in the External directory.

Fonts

Any commands related to fonts can be stored in the Fonts directory.

Src

All source code is located in the Src directory. Contained within are directories that represent the modules that make up Unreal Engine 3, as well as examples of creating game-specific modules.

Tools

Any tools and utilities that were developed internally are located in the Tools directory.

Game-specific directories

There will be one directory for each game project, including the base Engine.

Directory Contents

For each game project, including the base Engine, there will be one or more directories that contain elements specific to that project.

__Trashcan

Config

Sharing a base set of settings (render and windowing settings, base "WASD" input, ...) and other engine settings that rarely need game specific tweaking is accommodated by having a set of root ini files reside in the Engine\Config directory. These ini files are BaseEngine.ini, BaseEditor.ini, BaseGame.ini and BaseInput.ini with configuration options split accordingly.

These base configuration files are referenced by the respective per game/mod default INIs like DefaultEngine.ini, DefaultEditor.ini, DefaultGame.ini and DefaultInput.ini. Each of these INI files reside in the game specific configuration directory - "GameName"Game\Config.

On initialization, the engine tries to locate "GameName"Game\Config\"GameName"*.ini for Engine, Editor, Game and Input inis and will create a new version of the respective files based on the defaults contain in Default*.ini file's Configuration.BasedOn field, recursively searching until a root ini has been found. Upon finding the INI file, it then merge settings bottom up.

The engine has special support for merging ini files by treating lines starting with `+' or `-` differently. The default action is to replace existing keys, `+' tells the engine to append which is useful for expanding TArrays and `-` will remove a key/value pair defined in the base ini.

Content

The engine has a set of known file extensions (Core.System.Extensions, by default "u" and "upk") to satisify resource dependencies. It recursively searches the configured paths (Core.System.Paths) defaulting to "Engine\Content" folder.

Localization

The engine looks for localization files in a configurable selection of paths (Core.System.LocalizationPaths, defaulting to "Engine\Localization"). When localizing a resource, it first looks in the currently configured language localization file. If it fails to find a localized version of that resource, it then looks for an entry in the international localization file.

Logs

Log files are created by looking at the current executable's base name (that is the executable name without the potential "DEBUG-" prefix) and prefixing it with "GameName"Game\Logs.

Save Data

Screenshots

Script

Like regular packages, script files have the ability to reside in any subdirectory of directories configured in the Core.System.Paths array. For editing simplicity, the script compiler requires all files built in a single pass to reside in the directory specified by EditPackagesOutPath and looks at the EditPackages array for packages to compile with source found in the EditPackagesInPath folder (all in Editor.EditorEngine section).

Splash

Stats

Additional Considerations

Game specific extensions

The majority of the engine has been overhauled to allow configuration of used extensions, protocols, and map names extensions. In order to not have conflicting file associations for map file extensions we encourage licensees to pick an unique one. A list of known used file extensions can be found on the Licensee File Extensions page.

Hardcoded directory names, protocols, etc.

Please help us make the engine as modular and extensible as possible by reporting all encountered hardcoded path references or settings that should be configurable. The UnProg3 mailing list is the appropriate venue for this purpose.

Useful information

Game Name

The default game name is "Example" which means by default the engine will look for its configuration files in the ExampleGame\Config folder. You can either change the global =GGameName= variable in Core.cpp or use the new -game=MyGame command line option to explicitly specify the game name and hence the path the engine uses to look for .inis.

D:\Development\UnrealEngine3\Binaries> unreal -game=MyGame

The above tells the engine to set GGameName to MyGame and use MyGameGame\Config as the configuration folder. Please keep in mind that this option also applies to "UnrealEd" and "ucc" so in order to compile MyGame's script files you will need to invoke "ucc" with "ucc make -game=MyGame".

It is suggested that updating Core.cpp's GGameName with your game name or codename and use -game=demo to invoke the sample content after you are far enough along to not rely on Epic's content.

Configuration File examples

Snippets from BaseEngine.ini (Engine)

[URL]
Protocol=unreal
Name=Player
Map=Index.ue3
LocalMap=Entry.upk
MapExt=ue3

[Core.System]
Paths=..\Engine\Content
LocalizationPaths=..\Engine\Localization
Extensions=upk
Extensions=ue3
Extensions=u

[Editor.EditorEngine]
AutoSaveDir=..\Engine\Content\Maps\Autosaves
EditPackagesInPath=..\Development\Src
EditPackages=Core
EditPackages=Engine
EditPackages=Editor
EditPackages=UnrealEd
EditPackages=SequenceObjects
EditPackages=GamePlay
EditPackages=WarfareGame
EditPackages=SampleNativePackage

[D3DDrv.D3DRenderDevice]
ShaderPath=..\Engine\Shaders

Snippets from DefaultEngine.ini (ExampleGame)

[Configuration]
BasedOn=..\Engine\Config\BaseEngine.ini

[Core.System]
+Paths=..\ExampleGame\Content
+Paths=..\ExampleGame\Script
+LocalizationPaths=..\ExampleGame\Localization

[Editor.EditorEngine]
EditPackagesOutPath=..\ExampleGame\Script
AutoSaveDir=..\ExampleGame\Content\Maps\Autosaves

See the Configuration Files page for more information.

Architecture Overview

For an overview of the project structure and subsystem hierarchy of Unreal Engine 3, see the Architecture Overview page.