UE4: Guidebook
Search…
4.24
Structs, USTRUCTS(), They're Awesome
Guide on using USTRUCTS by Rama the legend
Overview
Original Author: Rama
Structs enable you to create custom variable types to organize your data, by relating other c++ or UE4 C++ data types to each other.
The power of structs is extreme organization, as well as ability to have functions for internal data type operations!
Technical
Structs enable you to create custom variable types to organize your data, by relating other C++ or UE4 C++ data types to each other. The power of structs is extreme organization as well as the ability to have functions for internal data type operations. '
In UE4, structs should be used for simple data type combining and data management purposes. For complex interactions with the game world, you should make a
UObject or AActor subclass instead.Core Syntax
1
//If you want this to appear in BP, make sure to use this instead //USTRUCT(BlueprintType)
2
USTRUCT() struct FJoyStruct
3
{
4
GENERATED_BODY()
5
​
6
// Always make USTRUCT variables into UPROPERTY()
7
// any non-UPROPERTY() struct vars are not replicated
8
​
9
// So to simplify your life for later debugging, always use UPROPERTY()
10
UPROPERTY()
11
int32 SampleInt32;
12
​
13
//If you want the property to appear in BP, make sure to use this instead
14
//UPROPERTY(BlueprintReadOnly)
15
​
16
UPROPERTY()
17
AActor* TargetActor;
18
​
19
//Set
20
void SetInt(const int32 NewValue)
21
{
22
SampleInt32 = NewValue;
23
}
24
​
25
//Get
26
AActor* GetActor()
27
{
28
return TargetActor;
29
}
30
​
31
//Check
32
bool ActorIsValid() const
33
{
34
if(!TargetActor)
35
return false;
36
​
37
return TargetActor->IsValidLowLevel();
38
}
39
​
40
//Constructor
41
FJoyStruct()
42
{
43
// Always initialize your USTRUCT variables!
44
// exception is if you know the variable type has its own default
45
constructor SampleInt32 = 5;
46
TargetActor = nullptr;
47
}
48
};
Copied!
Additional Note Author: DesertEagle_PWN The idea of USTRUCTS() is to declare engine data types that are in global scope and can be accessed by other classes/structs/blueprints. Because of this, it is invalid UE4 syntax to declare a struct inside of a class or other struct if using the USTRUCT() macro. Regular structs can still be utilized inside your classes and other structs; however these cannot be replicated natively and will not be available for UE4 reflective debugging or other engine systems such as Blueprints.Additional Note Author: Darkgaze Concerning the variables visibility on the editor: In the example above, if you don't add "EditAnywhere" parameter into UPROPERTY inside the members of the USTRUCT, whey won't show up in the Editor panel. You will see the variable but there will be no way to see/change/unfold the values inside. The class that defines a new UPROPERTY using that struct type should have that parameter too. In case you can't modify the data and you are using blueprints, you should add BlueprintType inside the USTRUCT parenthesis.
Examples
Example 1
You want to relate a float brightness value with a world space location FVector, both of which are interpolated using an Alpha value.
And you want to do this for 100 different game locations simultaneously. And you want to do this process repeatedly over time! You need to store the incremental interpolation values between game events. AActors/UObjects are not involved (You could just subclass
AActor/UObject and store the data per instance)1
USTRUCT()
2
struct FMyInterpStruct
3
{
4
GENERATED_BODY()
5
​
6
UPROPERTY()
7
float Brightness;
8
​
9
UPROPERTY()
10
float BrightnessGoal; //interping to
11
​
12
UPROPERTY()
13
FVector Location;
14
​
15
UPROPERTY()
16
FVector LocationGoal;
17
​
18
UPROPERTY()
19
float Alpha;
20
​
21
​
22
void InterpInternal()
23
{
24
Location = FMath::Lerp<FVector>(Location,LocationGoal,Alpha);
25
Brightness = FMath::Lerp<float>(Brightness,BrightnessGoal,Alpha);
26
}
27
​
28
//Brightness out is returned, FVector is returned by reference
29
float Interp(const float& NewAlpha, FVector& Out)
30
{
31
// value received from rest of your game engine
32
Alpha = NewAlpha;
33
​
34
//Internal data structure management
35
InterpInternal();
36
​
37
//Return Values
38
Out = Location;
39
return Brightness;
40
}
41
​
42
FMyInterpStruct()
43
{
44
Brightness = 2;
45
BrightnessGoal = 100;
46
Alpha = 0;
47
Location = FVector::ZeroVector;
48
LocationGoal = FVector(0,0,200000);
49
}
50
};
Copied!
Example 2
You want to track information about particle system components that you have spawned into the world through
1
UGameplayStatics::SpawnEmitterAtLocation() // returns a UParticleSystemComponent
Copied!
and you want to track the lifetime of the particle and apply parameter changes from C++. You could write your own class, but if your needs are simple or you do not have project-permissions to make a subclass of
UParticleSystemComponent, you can just make a USTRUCT to relate the various data types!1
USTRUCT()
2
struct FParticleStruct
3
{
4
GENERATED_BODY()
5
​
6
UPROPERTY()
7
UParticleSystemComponent* PSCPtr;
8
​
9
UPROPERTY()
10
float LifeTime;
11
​
12
​
13
void SetColor()
14
{
15
// your code here
16
}
17
​
18
FLinearColor GetCurrentColor() const
19
{
20
// your code here
21
}
22
​
23
// For GC
24
void Destroy()
25
{
26
PSCPtr = nullptr;
27
}
28
​
29
//Constructor
30
FParticleStruct()
31
{
32
PSCPtr = nullptr;
33
LifeTime = -1;
34
}
35
};
Copied!
Particle Data Tracker
Now you can have an array of these
USTRUCTS for each particle that you spawn!1
// Particle Data Tracking Array
2
UPROPERTY()
3
TArray<FParticleStruct> PSCArray;
Copied!
Garbage Collection
By marking a
USTRUCT or USTRUCT array as UPROPERTY() and marking any UObject / AActor members as UPROPERTY(), you are protected from dangling pointer crashesHowever you must also clear ustructs you no longer need if they have pointers to
UObjects if you ever want GC to be able garbage collect those UObjects.Structs With Struct Member Variables
The struct that wants to use another struct must be defined below the struct it wants to include.
1
USTRUCT()
2
struct FFlowerStruct
3
{
4
GENERATED_BODY()
5
​
6
UPROPERTY()
7
int32 NumPetals;
8
​
9
UPROPERTY()
10
FLinearColor Color;
11
​
12
UPROPERTY()
13
FVector Scale3D;
14
​
15
void SetFlowerColor(const FLinearColor& NewColor)
16
{
17
Color = NewColor;
18
}
19
​
20
FFlowerStruct()
21
{
22
NumPetals = 5;
23
Scale3D = FVector(1,1,1);
24
Color = FLinearColor(1,0,0,1);
25
}
26
};
27
​
28
USTRUCT()
29
struct FIslandStruct
30
{
31
GENERATED_BODY()
32
​
33
UPROPERTY()
34
int32 Type;
35
​
36
UPROPERTY()
37
TArray<FVector> StarLocations;
38
​
39
UPROPERTY()
40
float RainAlpha;
41
​
42
//Dynamic Array of Flower Custom USTRUCT()
43
UPROPERTY()
44
TArray<FFlowerStruct> FlowersOnThisIsland;
45
​
46
​
47
void SetRainAlpha(const float& NewAlpha)
48
{
49
RainAlpha = NewAlpha;
50
}
51
​
52
int32 GetStarCount() const
53
{
54
return StarLocations.Num();
55
}
56
​
57
FIslandStruct()
58
{
59
Type = 0;
60
Percent = 1;
61
}
62
};
Copied!
Struct Assignment
My personal favorite thing about structs is that unlike
UObject or AActor classes, which must be utilized via pointers (AActor*) you can directly copy the entire contents of a USTRUCT to another USTRUCT of the same type with a single line of assignment!1
FFlowerStruct ExistingFlower;
2
​
3
// ... create ExistingFlower here
4
​
5
FFlowerStruct NewFlower;
6
NewFlower = ExistingFlower;
Copied!
Deep Copy
If you have struct members pointing to UObjects or array pointers, you must be careful to copy these members yourself!
1
USTRUCT()
2
struct FMyStruct
3
{
4
int32* MyIntArray;
5
};
6
​
7
FMyStruct MyFirstStruct, MySecondStruct;
8
​
9
// Create the integer array on the first struct
10
MyFirstStruct.MyIntArray = new int32[10];
11
for( int i = 0; i < 10; ++i )
12
{
13
MyFirstStruct.MyIntArray[i] = i;
14
}
15
​
16
GEngine->AddOnScreenMessage(-1, 10.f, FColor::Blue, FString::FromInt(MyFirstStruct.MyIntArray[4]));
17
​
18
// Assign the first struct to the second struct, i.e. create a shallow copy
19
MySecondStruct.MyIntArray[4] = 6;
20
​
21
GEngine->AddOnScreenMessage(-1, 10.f, FColor::Blue, FString::Printf(
22
TEXT("%d %d"), MyFirstStruct.MyIntArray[4], MySecondStruct.MyIntArray[4]));
Copied!
On screen the output will be
1
4
2
6 6
Copied!
instead of the expected
1
4
2
4 6
Copied!
This is because the data stored in
MyStruct::MyIntArray is not actually stored inside of MyStruct. The new keyword creates the data somewhere in RAM and we simply store a pointer there. The address the pointer stores is copied over to MySecondStruct, but it still points to the same data. In fact, it would be counterproductive to remove this functionality since there are cases where you want exactly that. Additionally the Unreal Property System does not support non-UObject pointers, which is why MyIntArray is not marked with UPROPERTY().However, copying arrays of integers (e.g.
int32[10] instead of int32*) means the data is stored directly inside the struct and as such "deep copied". However, if you store a pointer to a UObject, this object is NOT deep copied! Once again only the pointer is copied and the original UObject left unchanged. Which is good because otherwise you might manipulate the wrong instance thinking you only had one to begin with leaving the original UObject unaffected, thus resembling a very nerve-wrecking and very difficult to track down bug!Automatic Make/Break in BP
Marking the
USTRUCT as BlueprintType and adding EditAnywhere, BlueprintReadWrite, Category = "Your Category" to USTRUCT properties causes UE4 to automatically create Make and Break Blueprint functions, allowing to construct or extract data from the custom USTRUCT.Special thanks to Community member Iniside for pointing this out. :)
1
USTRUCT(BlueprintType)
2
struct FFlowerStruct
3
{
4
GENERATED_BODY()
5
​
6
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Flower Struct")
7
int32 NumPetals;
8
​
9
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Flower Struct")
10
FLinearColor Color;
11
​
12
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Flower Struct")
13
FVector Scale3D;
14
};
Copied!
Replication
Remember that only
UPROPERTY() variables of USTRUCTS() are considered for replication!So if your
USTRUCT is not replicating properly, the first thing you should check is that every member is at least UPROPERTY()! The struct does not have be a BlueprintType, it just needs UPROPERTY() above all properties that you want replicated.Other notes
In case you are looking for
GENERATED_USTRUCT_BODY, in 4.11+, GENERATED_BODY() should be used instead.Related Links
Thank You Epic for USTRUCTS()
I love
USTRUCTS(), thank you Epic!Authors
Original author: Rama <3
Captured from the epic wiki via the Wayback Machine. Reformatted by Maldonacho
Last modified 2yr ago