Unreal Engine's JSON serialization

In order to use the visualizations involved with the LaserGraph framework, you should first understand how Unreal Engine's JSON serialization works. This page assumes you have a basic understanding of Unreal Engine C++ (including USTRUCT) and modules. Please check the official Unreal Engine resources and search for additional online resources, if you are unsure of this area.

Serialization can be achieved in UE blueprints with the JSON Blueprint library as well, and the examples shown below will work identical with the C++ library's functions.

Serialization in Unreal Engine

Unreal Engine supports USTRUCT serialization with the help of the Json and JsonUtilities modules, which can be added into your project or plugin in the Private/PublicDependencyModuleNames array of the *.Build.cs file. Please refer to official Unreal Engine resources linked above for more information about the Build.cs file.

USTRUCT serialization

For information on USTRUCTs, see here. USTRUCTs which are BlueprintType can be used in blueprints, and any existing struct visible in blueprints is already BlueprintType. For performing USTRUCT serialization in blueprints, see the JSON blueprint library documentation, linked above.

UStruct structure

In order for fields to be serialized in a USTRUCT, they must have the UPROPERTY macro applied to them, be public or protected, and must be a datatype which supports UPROPERTY. Generally, any other USTRUCT, as well as UObjects (by reference only), and primitive types like bool and int, should serialize without issue.

Sometimes we may want to store data in a USTRUCT and not have it serialize. We can apply the UPROPERTY specifier SkipSerialization to achieve this.

See the below example for a snippet of a USTRUCT which can be serialized. Note that there are some more advanced serialization techniques which are not covered in this documentation, so check other resources for information on how to add serialization support to objects otherwise not supported.

USTRUCT(BlueprintType)
struct LASERTAG_API FMatchData
{
	GENERATED_BODY()

    UPROPERTY()
    FText GameTypeName = FText::FromString("Team Tag Match");

    UPROPERTY(SkipSerialization)
    bool bFreeForAll = false;

    //additional fields not shown
}

This example shows GameTypeName as a variable which will be serialized, and bFreeForAll which will not.

Serialization

To serialize USTRUCTs, we can use functions included in JsonObjectConverter.h which should be able to be included after including the Json modules. For a complete list of the functions available with the JsonObjectConverter, click here.

Below is a snippet of code showing how we serialize match data in The Laser Games, stored as a USTRUCT:

FString UGameTypeDataComponentBase::GetMatchDataJSON()
{
    FJsonObjectWrapper root;
    TSharedPtr<FJsonObject> match = FJsonObjectConverter::UStructToJsonObject<FMatchData>(matchData);
    root.JsonObject->SetObjectField("MatchData", match);
    FString ret;
    root.JsonObjectToString(ret);
    return ret;
}

In the code snippet above, we create a root FJsonObjectWrapper, which is a blueprint-compatible wrapper containing the FJsonObject we store data to. We then convert the matchData struct into an FJsonObject struct with the FJsonObjectConverter::UStructToJsonObject function. Then, we store the JSON object into the root via JsonObject->SetObjectField, and return the JSON struct in string format, using root.JsonObjectToString to convert to a string format. The output will look something like this (with formatting applied):

{
    "MatchData": {
        "GameTypeName": "Team Tag Match",

        //variables in the matchData object
    }
}

Note how bFreeForAll is not serialized since it has SkipSerialization applied.

Manually storing values

We can also store data directly into a JSON object without it being stored in a USTRUCT before. Similar to how JsonObject->SetObjectField was used, we can use other functions to store booleans, numbers, strings, and arrays. See the documentation for FJsonObject for a complete list of all the different functions to store data.

In the below example, we create an FJsonObjectWrapper to store the ID of the HitInfo into a JSON format, which we will pass down in later function calls, to eventually be serialized similar to how we serialized the USTRUCT above.

int UGameTypeDataComponentBase::AddValidHit(const FHitInfo_DataAsset& Hit)
{
	FJsonObjectWrapper data;
	data.JsonObject->SetNumberField("ID", Hit.HitIndex);
	//additional code not shown
}