Overview

Project

A project is stored in its own directory and a file with the .uproject extension.

Projects have various subfolders:

Content – The project's assets (.uasset), and levels (.umap). The files in this folder are displayed in the Content Browser.

Source – The C++ files for the project including source files (.cpp) and header files (.h). The folder also contains C# build scripts (.Build.cs, .Target.cs).

Binaries – The binaries built for the project.

Config – The configuration files (.ini) for the project.

Intermediate – The temporary files generated by the toolsets.

Engine

The Engine folder contains additional subfolders:

Build – Build files.

Documentation – The documentation for the Engine (markdown and HTML).

Plugins – The Engine Plugins.

Programs – Configuration files for the tools.

Shaders – Built-in shaders (.usf).

Engine Sources

The C++ source code for the Engine is divided in different subfolders:

Developer – Additional Editor source code.

Editor – Editor source code.

Programs – Tools including the UnrealHeaderTool and UnrealBuildTool.

Runtime – Engine source code.

ThirdParty – Third-party source code and libraries.

UE4Editor.Target.cs – The Editor build configuration.

UE4Game.Target.cs – The Engine build configuration.

Assets

Unreal supports several common file formats that can be imported into a project.

Assets	Formats
3D	.fbx, .obj
Texture	.png, .jpeg, .bmp ,.tga, .dds, .exr, .psd, .hdr
Sound	.wav
Fonts	.ttf, .otf
Videos	.mov, .mp4, .wmv

Build System

Configurations

The project configurations are named as [Configuration][Target].

Configuration is required. It is set to: Debug, DebugGame, Development, Shipping, or Test.

Target is optional. It is set to: Editor, Client, or Server.

When the target is not set, it builds a stand-alone executable version of the project (requires cooked content).

💡

To open a project in the Editor, the project must be built in an Editor configuration.

UE4 uses a custom building method.

The UnrealHeaderTool (UHT) application is responsible for parsing and code generation.

The UnrealBuildTool (UBT) application is responsible for compilation and linking.

UnrealHeaderTool

The UnrealHeaderTool (UHT) parses the C++ source code of the Engine and Game Project to perform the code generation that supports the Reflection System.

UHT parses the C++ header files for the metadata macros such as UCLASS, USTRUCT, UPROPERTY...

UHT generates the C++ code in <TypeName>.gen.cpp and <TypeName>.generated.h files.

The generated files are located in Intermediate/Build/<Platform>/UE4Editor/Inc/<Project>/.

The generated header file must be included last in the header file of the corresponding type.

UnrealBuildTool

UBT uses the .Build.cs and .Target.cs files to build the Engine Modules and the Game Project.

The .Build.cs files are used for the Engine Modules.

They contain a class that derives from ModuleRules and provide the module settings in its constructor.


using UnrealBuildTool;

public class <ModuleName> : ModuleRules
{
	public <ModuleName>(ReadOnlyTargetRules Target) : base(Target)
	{
		PrivateIncludePaths.Add("<ModuleName>/Private");

		PublicDependencyModuleNames.AddRange(
			new string[] {
				"Core",
				"CoreUObject",
				"Engine",
				"RenderCore",
				"RHI",
			}
		);

		PrivateDependencyModuleNames.AddRange(
			new string[] {
				"Renderer",
			}
		);

    ...
	}
}

The .Target.cs files are used for the Engine and the Game Project.

They contain a class that derives from TargetRules and provide the target settings in its constructor.

using UnrealBuildTool;
using System.Collections.Generic;

public class <ProjectName>Target : TargetRules
{
	public <ProjectName>Target(TargetInfo Target) : base(Target)
	{
		Type = TargetType.Game;
		ExtraModuleNames.AddRange( new string[] { "<ProjectName>" } );

    ...
	}
}

UBT uses the platform-specific toolchain to build the C++ source code (Visual Studio or Xcode).

The Game Project is built as a dynamic library (.dll on Windows, .dylib on macOS) in the Binaries/<Platform>/ folder.

Terminology

Core

Object

Objects are instances of classes that inherit from the UObject class.

UObject provides engine features such as reflection, serialization, and garbage collection.

This is the base class of all objects in the Unreal Engine.

The memory of UObject instances is automatically zeroed before their constructors are called.

Class

The metadata that represent the type information is exposed as UClass instances in Editor builds.

Actor

Actors represents objects that exists in a level.

AActor is a base type that is inherited for specific types of actors.

Actors can be updated (ticked) each frame, or at a custom interval to perform any update calculations or actions over time.

Actors are ticked through the Tick function.

Actors contain a hierarchy of ActorComponents.

ActorComponent

UActorComponent is the base type for actor components.

ActorComponents are ticked through the TickComponent function.

SceneComponent

USceneComponent contains a transform (position, rotation, and scale).

SceneComponents can be parented to create a scene hierarchy.

The transform of an Actor is determined by its RootComponent property, which is a SceneComponent.

PrimitiveComponent

UPrimitiveComponent is the base type to represent visual objects such as a mesh, a terrain, a particle system, or a geometry.

Gameplay

Pawn

APawn represents a controllable actor in a level.

A Pawn is controlled (possessed) by a player or an AI.

Character

ACharacter represents a Pawn Actor used as a player character.

A Character provides collisions, input bindings, and movement for a controllable character.

Controller

A AController possesses a Pawn or a Character.

The main controllers are:

APlayerController – Controller for the representation of the player in a game.

AAIController – Controller for a non-player character (NPC) in a game.

PlayerCameraManager

A APlayerCameraManager represents a Camera.

Brush

A Brush is Actor that represents level geometries (BSP) and volumes.

Brushes are used to prototype levels, and set up gameplay volume for triggers and collisions.

Level

A Level is a container for Actors.

A Level is stored as a .umap file in the Content folder.

World

A World contains a list of Levels.

Levels can be streamed in and out during gameplay.

Game Rules

A game is made up of a GameMode and GameState.

Players joining the game are associated with PlayerControllers.

The Game Rules objects are used in multiplayer games.

GameMode

The GameMode contains the rules of the game.

GameMode is stored on the server.

GameState

The GameState contains the current state of a play session.

GameState is stored on the server and every clients.

PlayerState

The PlayerState contains the state of the players and bots.

Blueprint Function Libraries

Blueprint Function Libraries are a collection of C++ static functions.

To create Blueprint Library, create a new C++ class that inherits from UBlueprintFunctionLibrary.

The class needs the UCLASS and GENERATED_UCLASS_BODY macros.

The class should only contain static methods.

Functions that are exposed to Blueprint need the UFUNCTION macro with the BlueprintCallable or BlueprintPure specifier.

For example, the UMyBlueprintLibrary exposes the MyFunction static function to Blueprint:

UCLASS()
class UMyBlueprintLibrary : public UBlueprintFunctionLibrary
{
    GENERATED_UCLASS_BODY()

    UFUNCTION(BlueprintCallable, Category="MyCategory")
    static bool MyFunction();
};

Subsystems

Subsystems are automatically instanced classes with managed lifetimes.

Subsystems are useful when creating plugins.

There are four subsystems:

Subsystem	Type	Access
Engine	UEngineSubsystem	GEngine->GetEngineSubsystem
Editor	UEditorSubsystem	GEdito->GetEditorSubsystem
GameInstance	UGameInstanceSubsystem	GameInstance->GetSubsystem
LocalPlayer	ULocalPlayerSubsystem	LocalPlayer->GetSubsystem

Subsystems are automatically exposed to Blueprints.

Module

A game is made up of one or more gameplay modules.

💡

Usually a game contains only one module. Additional game modules may improve link times and provide faster code iteration.

A module is a container for a set of classes.

ℹ️

Modules are similar to Packages from UE3.

A module contains the following folders:

Public

Private

A module must contain:

A header file (.h) in the Public folder

A C++ file (.cpp) in the Private folder

A build file (*.Build.cs) in the root folder

Header

The header file includes Engine.h, EnginePrivate.h and the generated headers.

#include "Engine.h"
#include "EnginePrivate.h"
#include "<ModuleName>Classes.h"

Source

The source file registers and implements the module.

The primary module must be registered using IMPLEMENT_PRIMARY_GAME_MODULE.

Additional modules use IMPLEMENT_GAME_MODULE.

#include "<ModuleName>.h"

IMPLEMENT_PRIMARY_GAME_MODULE( <ModuleName>, "<GameName>" );

Build

The build file defines the public and private dependencies used by the UnrealBuildTool to compile the module.

using UnrealBuildTool;

public class <ModuleName> : ModuleRules
{
    public <ModuleName>( TargetInfo Target )
    {
        PublicDependencyModuleNames.AddRange( new string[] { "Core", "Engine" } );
        PrivateDependencyModuleNames.AddRange( new string[] { "RenderCore" } );
    }
}

INI

Every module is registered in the DefaultEngine.ini file.

[UnrealEd.EditorEngine]
+EditPackages=<ModuleName>

[Launch]
Module=<ModuleName>

[/Script/Engine.UObjectPackages]
+NativePackages=<ModuleName>

Plugins

Plugins are a set of code and data can be enabled or disabled on a per-project basis.

Plugins can add or modify Engine and Editor functionality.

Many subsystems are designed to be extended by Plugins.

Plugins are located in the Plugins folder either in the Engine folder, or the Project folder.

Plugins are identified using Plugin Descriptors which are JSON files with the .uplugin extension.

The Plugin Descriptors are serialized as FPluginDescriptor structures.

The icon for a Plugin is a 128 x 128 PNG file called Icon128.png and stored in the Plugin's Resources directory.

Plugins can have one or many Modules. For example, a runtime and Editor-only module.

Project Modules can depend on other Plugins and Plugins can depend on other Plugins.

Structure

PluginName.uplugin – Plugin Descriptor

Resources/Icon128.png – Icon for the Plugin.

Source folder – C++ source code for the Plugin.

Content folder – Assets for the Plugin.

Config folder – INI configuration files for the Engine and Editor.

Binaries folder – Binaries for the Plugin.

Code Generation

The UE4 metadata is represented by types declared in the UE4CodeGen_Private namespace.

The generated C++ code declare:

Private move and copy constructors with no implementation to disable moving and copying instances.

A default constructor.

A standard constructor with a single parameter: const FObjectInitializer& ObjectInitializer.

A private static StaticRegisterNatives<TypeName> function.

References

Coding Standard