Passing Complex Data Structures to Blueprints

In this lesson, you will learn how to bridge the gap between C++ logic and Blueprint visual scripting by defining custom USTRUCT types that the Unreal Editor can recognize and display as variables.

Why use USTRUCTs for Blueprints?

While you can expose simple variables like floats or booleans, real games require grouping related data together—like an inventory item's name, weight, and icon ID. To make these bundles visible and editable in Blueprints, we wrap them in a USTRUCT. By using the BlueprintType specifier, you tell the Unreal reflection system that this data structure is "safe" to be passed around, stored in arrays, and edited by designers inside the editor.

Defining Your Struct

To make a struct Blueprint-ready, you must define it outside of any UCLASS in your header file. You use the USTRUCT(BlueprintType) macro and define your variables as UPROPERTY with the EditAnywhere or BlueprintReadWrite specifiers.

USTRUCT(BlueprintType)
struct FCharacterStats
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float Health;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float Mana;
};

Once you compile this code, Unreal’s reflection system registers FCharacterStats as a new variable type. You can now create a variable in any Blueprint, click on the "Variable Type" dropdown, and search for "Character Stats."

Working with Data

Because you added the BlueprintReadWrite specifier, Blueprints can now "Break" these structs into their individual components or "Make" new ones to pass back into your C++ logic. This is the foundation of data-driven design: you handle the math and complex logic in C++, while your designers manage the actual data values using the intuitive pins and nodes in the Blueprint graph.

By keeping your data organized in USTRUCT containers, you prevent "pin clutter" in your Blueprints and ensure that your C++ structures remain modular and easy to manage as your project grows in complexity.

Key Takeaway: By marking a USTRUCT with BlueprintType and its members with BlueprintReadWrite, you transform raw C++ data into a first-class citizen that designers can manipulate directly within the Unreal Editor.