DEV Community

nipanko
nipanko

Posted on

A Beginner's Guide to C++ Programming in Unreal Engine 5

#unreal #computerscience #cpp #gamedev

Unreal Engine 5 is experiencing tremendous growth, presenting a significant opportunity for developers. Mastering it can set new industry standards and open doors for game creators everywhere. This guide provides a clear introduction to the fundamental programming concepts in UE5.

The Build Ecosystem

The entirety of Unreal Engine's functionality is accessible through its source code, which is written in C++. All C++ code, both from the engine itself and the custom classes you write, is organized into modules.

Every time you compile your project, the code is processed by the Unreal Build Tool (UBT). UBT is Unreal Engine's proprietary, cross-platform build system, written in C#, which manages the complex process of compiling C++ source code into a functional product.

For developers compiling the engine from the source, Epic Games recommends placing your engine and project directories within the same root folder. This setup designates your project as a "native project," allowing it to automatically associate with your custom-built engine version.

Code Architecture

Unreal Engine is designed for modularity and reusability. Its architecture is built upon a few key concepts:

Modules

A module is a collection of C++ classes with a corresponding C# build file (.build.cs) that describes how they should be compiled. The engine itself is composed of thousands of modules. In the editor, each module compiles into its own Dynamic-Link Library (DLL). However, when a project is packaged for release, these modules are typically combined into a single executable file in what is known as a monolithic build.

Plugins

A Plugin is a self-contained collection of modules and/or assets that can be easily enabled, disabled, or shared between projects.

  • Game Features Plugins are a special type that allows you to activate or deactivate entire sections of gameplay content at runtime, making them perfect for DLC, seasonal events, or optional game modes.
  • Platform Extensions are used to isolate platform-specific code (e.g., for PlayStation or mobile), ensuring the core project remains clean and portable.

Automation Tools

For those who are not programmers, or for automating complex build pipelines, Unreal provides several key tools:

  • Unreal Game Sync (UGS): A GUI-based tool primarily for studios using the Perforce version control system. It allows artists and designers to sync to specific project versions and build pre-compiled binaries without needing to use an IDE.
  • Unreal Automation Tool (UAT): The master script that handles common commands like building, cooking, and packaging your project. UAT is the backend tool that runs whether you package from the editor, a command line, or another utility.

Compiling

You can compile your C++ code directly from your IDE (like Visual Studio or Rider) or by clicking the "Compile" button inside the Unreal Editor. For more advanced workflows, tools like Live++ allow you to recompile and patch C++ code while the editor is running, significantly speeding up iteration time.

Core Programming Concepts

Macros

Unreal Engine uses special C++ macros (e.g., UCLASS(), UPROPERTY(), UFUNCTION()) to expose code functionality to the editor and Blueprints. These macros provide essential metadata for core systems like Reflection (the engine's ability to learn about your code), Serialization (saving and loading), Networking (replication), and garbage collection.

The Unreal Standard Library

Unreal Engine intentionally avoids using the standard C++ library (STL). Instead, it provides its own comprehensive standard library. This approach ensures greater portability across different platforms, seamless integration with engine systems like serialization and reflection, and consistent behavior.

  • Numbers: Standard float and double types are available. For integers, UE provides explicitly sized types like int8, int32, uint32, and int64 to avoid platform-dependent size variations. It is best practice to use these types instead of generic int or unsigned int.
  • Enums: You can create standard C++ enums, but using the UENUM() macro exposes them to the engine, allowing them to be used in Blueprints and serialized properly.
  • Structs: A USTRUCT() is a lightweight data container, similar to a class. However, structs are intended for plain old data (POD) and cannot contain Blueprint-callable functions. They are value types, meaning they are copied when passed around.
  • Strings: Unreal provides several string types for different use cases:
    • FString: The primary mutable string class. It is a wrapper for a wide character array and is ideal for string manipulation.
    • FName: An immutable, case-insensitive string stored in a global hash table. FName is highly efficient for frequently used identifiers like object names, bone names, or material parameters because it avoids expensive string comparisons by comparing lightweight index values instead.
    • FText: The required string type for any text that will be displayed to the user. FText has built-in support for localization, allowing your game to be translated into different languages easily.
  • Containers: UE provides its own templated container types: TArray (dynamic array), TMap (key-value pairs), and TSet (unique elements). These are fully integrated with the engine, can be exposed to Blueprints, and support custom memory allocators.
  • Math Library: The FMath library is a vast collection of static utility functions and transform types (FVector, FRotator, FTransform) that are fully supported by Blueprints and the replication system.

The UObject System

The UObject is the base class for almost everything in Unreal Engine. It provides fundamental features that power the engine's frameworks. Any class inheriting from UObject should be prefixed with U.

Key features provided by UObject:

  • Reflection: The ability for the engine to query information about the object's type, properties, and functions at runtime.
  • Garbage Collection: Automatic memory management.
  • Serialization: Saving and loading object state to/from disk.
  • Editor Integration: Making properties visible and editable in the Details panel.

Actor and Components

An Actor is any object that can be placed in a level (a "Scene"). Actors are the containers for gameplay logic and functionality. An Actor on its own is just a location; its behavior is defined by its Components.

  • UActorComponent: A non-spatial component that adds functionality, like health management or an inventory system. It does not have a physical location (Transform) in the world.
  • USceneComponent: A component that exists at a specific location in the world, defined by a Transform (location, rotation, scale) relative to its parent Actor. Scene Components can be attached to form a hierarchy. Every Actor has at least one Root Component, which dictates the Actor's position in the level.

Memory Management & Garbage Collection

You must follow Unreal's rules for object creation and memory management.

  • Create new UObjects using NewObject<UYourClass>().
  • Create new AActors using GetWorld()->SpawnActor<AYourActor>().
  • Never use the C++ keywords new or delete on UObjects.

The Garbage Collector (GC) automatically destroys UObjects that are no longer referenced by any other object. It runs periodically (about once every 60 seconds by default) to clean up memory. A common and hard-to-debug error is holding a raw C++ pointer to a UObject without marking it as a UPROPERTY(). The GC cannot see this reference, so the object may be destroyed, leaving you with a dangling pointer that will cause a crash when accessed.

Smart Pointers

Unreal provides two categories of smart pointers for different use cases.

1. UObject-Tracking Pointers (Garbage Collection Aware):

  • TObjectPtr<UYourClass>: The modern replacement for a raw UYourClass* pointer. It is tracked by the GC and will automatically be set to nullptr if the object it points to is destroyed.
  • TWeakObjectPtr: A pointer that does not prevent the object from being garbage collected. You must check if it's valid before using it.
  • TSubclassOf<UYourClass>: A type-safe way to hold a reference to a UClass that inherits from a specific base class. Useful for Blueprint variables where you want to choose a class to spawn.
  • TSoftObjectPtr / TSoftClassPtr: "Soft" pointers that reference an asset by its path instead of holding it in memory. This prevents the asset from being loaded until you explicitly request it, which is crucial for managing memory and load times.

2. Non-UObject Pointers (Standard C++ Style Memory Management):

  • TUniquePtr: Gives unique ownership of a pointer. When the TUniquePtr goes out of scope, the memory is automatically deleted.
  • TSharedPtr / TSharedRef: Manages a shared reference count for an object. The object is deleted only when the last TSharedPtr or TSharedRef pointing to it is destroyed.
  • TWeakPtr: A non-owning pointer that can observe a TSharedPtr/TSharedRef without affecting its reference count.

It is critical that you never use the non-UObject smart pointers (TUniquePtr, TSharedPtr, etc.) on UObjects, as this will break garbage collection and lead to crashes.

Advanced C++ Structures

  • Interfaces: Interfaces allow unrelated classes to share a common set of functions. Unlike in many other languages, a class in Unreal does not have to implement every function in an interface. You can safely call an interface function on any object, and it will only execute if the object has implemented it. It is highly recommended to use C++ interfaces, as they can be used by both C++ and Blueprints, whereas Blueprint Interfaces can only be used by Blueprints.
  • Data Assets: Generic UObject containers used to organize game data, similar to data-only Blueprints. They are an excellent way to structure gameplay constants and configurations.
  • Data Tables: A powerful system for managing large sets of data in a spreadsheet-like format. You define a C++ struct as the row structure, and then you can easily import/export data from CSV files.
  • Delegates and Events: A safe and robust implementation of the observer pattern. Delegates allow objects to subscribe to events and be notified when they occur, decoupling systems and improving code modularity.
  • Subsystems: Engine-managed classes with a defined lifetime (e.g., UGameInstanceSubsystem, UWorldSubsystem). They function like global singletons within their scope, providing an easy way to offer services and manage state without placing managers in your level.
  • Async Task Graph: An engine-managed task system that allows you to run work on multiple CPU cores or in asynchronous background threads. It uses an internal thread pool and is leveraged by many engine systems for performance.

The Gameplay Framework

The Gameplay Framework is a pre-built, network-ready foundation for structuring your game. It provides a robust set of base classes designed to support most game genres out of the box, with native multiplayer support.

  • Game Instance (UGameInstance): A global object that exists for the entire lifetime of the application (from launch to shutdown). It persists across level changes, making it the ideal place for data that needs to be stored permanently, like user settings or player profiles.
  • Game Mode (AGameModeBase): A server-only object that defines the rules for a specific level or match. It handles logic like spawning players, victory conditions, and player joining rules. Because it only exists on the server, clients never have direct access to it.
  • Game State (AGameStateBase): An object that tracks the state of the game for all connected players. The Game State is created on the server and replicated to all clients. It's used for tracking shared information like the match timer, current team scores, and a list of all connected players.
  • Player State (APlayerState): Represents the state of a single player in the game. It is also created on the server and replicated to all clients. It holds player-specific information like name, score, ping, and other custom data.
  • Controller (AController): The "brain" of a Pawn. It receives input and directs the Pawn's actions.
    • Player Controller (APlayerController): Represents a human player. It is the primary communication link from the client to the server and handles player input. It only exists on the owning client and the server.
    • AI Controller (AAIController): Controls a Pawn using artificial intelligence, such as a behavior tree.
  • Pawn (APawn): An Actor that can be "possessed" by a Controller. It is the base class for any object that can be controlled by a player or AI.
    • Character (ACharacter): A specialized type of Pawn that includes a CharacterMovementComponent, a SkeletalMeshComponent, and a CapsuleComponent, providing built-in functionality for bipedal movement like walking, running, jumping, and swimming.
  • Enhanced Input Component: The modern system in UE5 for handling user input. It uses Input Mapping Contexts to group a set of Input Actions (e.g., "Jump," "MoveForward"). This context-sensitive approach allows you to easily enable or disable entire sets of controls at once (e.g., switching between "OnFoot" controls and "InVehicle" controls).
  • Movement Component: A component responsible for translating input into movement. It is designed to handle network replication, client-side prediction, and lag compensation automatically.
  • Cheat Manager (UCheatManager): A class that centralizes development cheats and debug commands. Code in this class is automatically compiled out of release builds, making it a safe place to add debug functionality without risk of shipping it to players.

Advanced Gameplay Systems

  • Ticking System: Ticking is the process of updating an object every frame. Any Actor or Component can have a Tick() function that executes on each frame. While useful, ticking can be a major performance bottleneck. It's best practice to disable ticking on Actors that don't need constant updates and to use event-based logic instead whenever possible.
  • Gameplay Ability System (GAS): A highly flexible, data-driven framework for creating character actions and abilities (e.g., spells, attacks, skills). It is a complex but powerful system built around three core concepts: Gameplay Abilities (what an ability does), Gameplay Attributes (numeric values like Health or Mana), and Gameplay Effects (which modify Attributes).
  • Mass Entity Component System (ECS): A high-performance framework based on the Data-Oriented Design paradigm. Mass is designed for simulating thousands or tens of thousands of entities with minimal overhead, making it ideal for large-scale RTS games, crowd simulations, or complex ecosystems. It trades the flexibility of the Actor model for a massive gain in performance.
  • Game Features Plugins: As mentioned earlier, these allow for the creation of modular, self-contained gameplay content that can be enabled, disabled, loaded, and unloaded at runtime. This is the standard way to build DLC and other optional content.

Profiling and Debugging

Unreal Engine includes a professional suite of debugging and profiling tools. The best practice is to use both Unreal's tools and the native tools of your target platform (e.g., Visual Studio's debugger, Xcode Instruments) for the most comprehensive analysis.

  • Logging System: The UE_LOG macro allows you to print formatted messages to the Output Log and saved log files, which is essential for tracing code execution and diagnosing issues.
  • Visual Logger: An incredible tool for debugging complex, time-based behavior like AI. It records gameplay events and data on a navigable timeline, allowing you to scrub back and forth to see exactly what an object was doing at any given moment.
  • In-game Console: A command-line interface accessible in-game for executing debug commands and changing console variables.
  • Unreal Insights: A powerful, standalone application that provides in-depth performance analysis. It can capture and visualize CPU traces, memory allocations, network traffic, and more with very low overhead, making it the primary tool for hunting down performance bottlenecks.
  • CSV Profiler: Captures performance data over time and saves it to a comma-separated value (.csv) file, which can be analyzed in spreadsheets to track performance metrics.
  • LLM (Low-Level Memory) Tracker: A system that tracks every memory allocation made by the engine, giving you a precise view of memory usage to diagnose leaks or excessive consumption.
  • ProfileGPU / DumpGPU: Console commands that provide a detailed breakdown of what the GPU is doing for a single frame, helping you identify expensive shaders or rendering passes.
  • Gauntlet Automation Framework: A powerful framework for creating automated tests. You can script tests to load a map, perform actions, measure performance, and report the results, which is essential for continuous integration and quality assurance.

The Replication System

Unreal Engine's replication framework is a robust, battle-tested system for creating multiplayer games. It uses a server-authoritative model, where the server is the ultimate source of truth for the game state. The server then replicates this state to all connected clients.

Key concepts include:

  • Property Replication: You can mark variables with the UPROPERTY(Replicated) macro. The server will automatically detect when the value of this variable changes and send updates to all clients, keeping their view of the world synchronized.
  • RPCs (Remote Procedure Calls): These are functions that can be called on one machine and executed on another. You can define functions to run OnServer, OnClient, or be Multicast (run on the server and then all clients). This is how you send one-off events, like playing a sound effect or telling the server a player has fired their weapon.

Top comments (0)