Serializing Custom Containers for Unreal Reflection

In this lesson, you will learn how to make your custom C++ data structures compatible with Unreal’s reflection system, enabling them to appear in the Editor and save to disk automatically.

The Bridge to Reflection

By default, Unreal’s reflection system (the UHT or Unreal Header Tool) only understands specific types like TArray, TMap, and TSet. If you create a custom container—such as a specialized struct that wraps internal logic—Unreal will ignore it unless you explicitly define its properties.

To make your custom container "visible" to the engine, you must declare it as a USTRUCT and ensure its internal members are tagged with UPROPERTY(). This is the secret sauce: the reflection system relies on these macros to know what to serialize, how to show it in the Details Panel, and how to save it to your USaveGame files.

Structuring for Success

Imagine you have a custom inventory container. If you just define a standard C++ class, the engine cannot track its state. By using a USTRUCT, you provide the reflection metadata required for the engine to manage memory and persistence.

USTRUCT(BlueprintType)
struct FInventoryContainer
{
    GENERATED_BODY()

    // The UPROPERTY macro tells Unreal to manage this member for serialization
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inventory")
    TArray<FItemData> Items;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Inventory")
    int32 MaxCapacity = 20;
};

Why Metadata Matters

When you mark your container with UPROPERTY, you aren't just making it editable in the editor. You are enabling:

1. Serialization: Unreal’s binary serializer can now traverse your container to save/load game data.
2. Memory Management: The engine tracks references within your structure to prevent memory leaks.
3. Editor Integration: You can modify these values directly in the Details Panel without writing custom Slate code.

Without these macros, the engine treats your container as an opaque "blob" of memory, making it invisible to the Save Game system and the visual Editor tools.

Key Takeaway: By wrapping custom data in a USTRUCT and flagging members with UPROPERTY, you register your container with the Unreal reflection system, unlocking seamless serialization, persistence, and editor-side management.