USTRUCT

An overview of USTRUCTs (Struct) Data Structure in Unreal

Updated 7 months ago Edit Page Revisions
Struct

This discussion is primarily focused on Unreal Engine C++

Structs are data structures that help you organize and manipulate related properties. For example, a Vector (FVector) is a commonly used Struct in Unreal defining an X, Y, and Z value.

In Unreal Engine, Structs may exist in either C++ or in Blueprint. Once created, you can use a Struct in a similar that you might use a fundamental data type (e.g. Integer, Bool, etc).

Declaring a USTRUCT in C++

Declaring a USTRUCT in C++ follows the same basic pattern as standard C++. Here is an example:


USTRUCT()
struct FExampleStruct
{
    GENERATED_BODY()
 
    UPROPERTY()
    int32 X;
 
    UPROPERTY()
    float Y;
};
  1. Prepend the USTRUCT() macro above the declaration of your Struct's name
  2. Ensure that your Struct includes the GENERATED_BODY() macro. (In older code you may see GENERATED_USTRUCT_BODY() but this is no longer required nor necessary).
  3. That's it, you have created a USTRUCT. Be sure to mark any properties you want exposed to Unreal Engine's reflection system

A USTRUCT cannot be declared within the scope of another Class or Struct.

Exposing a USTRUCT declared in C++ to Blueprint

If you want Blueprint to be able to instantiate and manipulate your Blueprint, then ensure that:

  1. Your USTRUCT is declared as BlueprintType
  2. The UPROPERTY members of your Struct are declared as BlueprintRead or BlueprintReadWrite, as appropriate.

Example code:


USTRUCT(BlueprintType)
struct FExampleStruct
{
    GENERATED_BODY()
 
    UPROPERTY(BlueprintReadWrite)
    int32 X;
 
    UPROPERTY(BlueprintReadWrite)
    float Y;
};

C++ Documentation

Epic Documentation

Legacy Content

When a Struct is defined using the USTRUCT macro in C++, it becomes exposed to the Unreal Engine reflection system and may become

In the Unreal Engine, they're recognized by the Engine's reflection system, but are not part of the UObject ecosystem. As a result, they are faster to create than a UObject with the same data layout, and support UProperties, but will not be managed by the Garbage Collection system and cannot provide UFunctions. Keep in mind that UStructs cannot be used inside classes.

Description

USTRUCT is a Macro used in UE4 C++ to specify certain settings and attributes.

Caveats

Replication

Remember that only UPROPERTY variables of USTRUCTs are considered for replication! '''Read more here!'''

When you declare a USTRUCT in Unreal Engine you can add a NetSerialize method which is part of the Unreal Engine struct trait system. If you define this method, the engine will use it while serializing and deserializing your struct for networking both during properties replication and RPC.

You can find a lot of documentation about serialization in this source file: Runtime/Engine/Classes/Engine/NetSerialization.h '''More information here!'''

Garbage Collection

Only variables specified as UPROPERTY will be counted for the purposes of Garbage Collection.

Valid Keywords

Atomic

Indicates that this struct should always be serialized as a single unit.

BlueprintType

Exposes this struct as a type that can be used for variables in Blueprints.

Immutable

Immutable is only legal in Object.h and is being phased out.

Do not use on new structs!

NoExport

No autogenerated code will be created for this class; the header is only provided to parse metadata from.

Related