UE4 Containers

UE4 has plenty of great C++ libraries to use for game development, but it’s not always obvious in a large code project where to find them. In this post, I just want to call out a few that are especially useful and worth checking out. For more information, you might also want to read the “Core” part of the API document here.

CONTAINERS

To suit your storage needs, UE4 has a whole gamut of container classes available, many mirroring the basic functionality that would traditionally be a part of C++’s standard library. Honestly, just about the only thing you won’t be able to contain is your excitement from all of these classes!…I’m sorry.

COMMON CONTAINERS

TARRAY

(Engine\Source\Runtime\Core\Public\Containers\Array.h)

TArray is a templated, dynamically-sized array and easily the most commonly used of the UE4 containers. It has all the features you would expect from a dynamic array as well as full UPROPERTY support. TArray’s API additionally provides functionality for treating a TArray as a stack or heap structure.

As TArrays can be declared as UPROPERTYs, they are easily displayed in editor property windows and are eligible for network replication, as well as automatic UPROPERTY serialization. As a result of this feature, TArray is often the container of choice in gameplay code implementations.

If you’ve ever used the C++ Standard Template Library (STL) vector class, TArray is the friend you’re looking for.

TSET

(Engine\Source\Runtime\Core\Public\Containers\Set.h)

TSet is a templated implementation of the concept of a mathematical set and offers the expected set operations, such as Intersect, Union, and Difference, as well as a quick way to check if an element is a member of a set or not (PeopleWhoLoveTSet.Contains(Me); // Always evaluates to true).

Caveat: Unlike TArray, TSets (and TMaps) are not directly supported as UPROPERTYs and so cannot be automatically replicated, serialized, etc. If a TSet (or TMap) is used with hard UObject references (example: TSet<UObject*>), it is up to the user to make sure those references are properly serialized for the purposes of garbage collection. Someone has to take out the trash…

TSet is analogous to the C++ STL set class, however the UE4 implementation is based on hashing. If you make a new type and need to use it in a TSet (or TMap), you need to implement a simple function to hash the type: uint32 GetTypeHash(const YourType& TypeVar). There are plenty of examples in the code base if you want to check them out.

TMAP

(Engine\Source\Runtime\Core\Public\Containers\Map.h)

TMap is a templated data structure allowing the mapping of one type to another (key-value pairs) with fast element addition, removal, and look-up. If coming from another programming language, you might also know the structure the TMap represents as a “dictionary.”

Like the TSet, the TMap cannot be declared as a UPROPERTY.

TMap is comparable to the C++ STL map class, however the UE4 implementation is based on hashing.

ITERATORS

The UE4 containers provide iterator support, though the usage is not exactly the same as in the C++ STL. You can check each container type for its supported iterators, but in general const and non-const iterators are available.

Example:

// Example direct from the engine source:
// Initialize an iterator from the provided array (InPackages)
for (TArray<UPackage*>::TConstIterator PkgIter(InPackages); PkgIter; ++PkgIter)
{
// Access the element at the current position of the iterator with the * operator
UPackage* CurPackage = *PkgIter;

If you’re a fan of C++11 (and being lazy), you can also use the auto keyword with iterators:

for (auto FileIt = Files.CreateConstIterator(); FileIt; ++FileIt)
{
const FString FileExtension = FPaths::GetExtension(*FileIt);

SORTING

In addition to a default sorting option, the UE4 containers that support sorting also allow custom sorting via a predicate object.

Example:

// Custom struct written to serve as the predicate for sorting. Given two constant references to elements
// in the data structure (anim notify events), sort them according to their trigger time.
struct FCompareFAnimNotifyEvent
{
FORCEINLINE bool operator()(const FAnimNotifyEvent& A, const FAnimNotifyEvent& B) const
{
return A.GetTriggerTime() < B.GetTriggerTime();
}
};
 
// Sort the notifies array (TArray<FAnimNotifyEvent>) with the custom predicate
Notifies.Sort(FCompareFAnimNotifyEvent());

OTHER CONTAINERS

TArray, TSet, and TMap are the most commonly used UE4 containers, but certainly not the only ones! If you want to check out the source code for these three and the others, you’ll want to look in theEngine\Source\Runtime\Core\Public\Containers directory.

STRING HANDLING

(Engine\Source\Runtime\Core\Public\Containers\UnrealString.h)

(Engine\Source\Runtime\Core\Public\UObject\NameTypes.h)

(Engine\Source\Runtime\Core\Public\Internationalization\Text.h)

UE4 provides three different classes for interacting with strings that you should be aware of: FString,FName, and FText. Each has their own particular purpose and optimal use case, which is explained in great detail in the documentation here. (and in the reference guides linked to from that page).

MATH

(Engine\Source\Runtime\Core\Public\Math\UnrealMathUtility.h)

(Engine\Source\Runtime\Core\Public\GenericPlatform\GenericPlatformMath.h)

What’s a game without math?! Luckily, UE4 has a very robust, cross-platform math library, generally implemented as a series of static functions within FMath. FMath encompasses a very large set of math operations from the very simple to the more complex. It’s definitely worth browsing both header files to get a full grasp of what’s already written for you to use before you begin anything involving math!