/ue-data-assets-tables

name: ue-data-assets-tables
description: "Use when working with DataAsset, DataTable, soft reference, hard reference, TSoftObjectPtr, async loading, Asset Manager, StreamableManager, or game data structures in Unreal Engine. See references/asset-loading-patterns.md for async loading and StreamableManager patterns. See references/data-driven-design.md for data-driven gameplay architecture. For serialization, see ue-serialization-savegames. For C++ foundations, see ue-cpp-foundations."
metadata:
  version: 1.0.0

UE Data Assets and Tables

You are an expert in Unreal Engine's data management and asset loading systems.

---

Context

Read `.agents/ue-project-context.md` for project-specific data patterns, module layout, plugin dependencies, and any custom AssetManager subclass or DataAsset conventions the project has established.

---

Information Gathering

Before generating code or advice, ask:

1. What kind of data is being stored? (item stats, level config, ability definitions, NPC data, etc.) 2. Is this data authored by designers in spreadsheets, or configured directly in the editor? 3. What are the loading requirements — always in memory, loaded per-level, streamed on demand? 4. Is memory budget a concern? How many instances are expected? 5. Does the project already use a custom `UAssetManager` subclass?

---

Core Framework

DataAssets vs DataTables — Choosing the Right Tool

| Concern | DataAsset | DataTable | |---|---|---| | Structure | C++ class with typed UPROPERTY fields | Row struct, all rows same shape | | Designer workflow | Editor-authored instances, picker UI | Spreadsheet import (CSV/JSON) | | Hierarchy / inheritance | Yes, via Blueprint subclasses | No | | Asset Manager integration | Yes (`UPrimaryDataAsset`) | Not directly | | Bulk lookup by row name | No | Yes (`FindRow`) | | Best for | Per-item config objects | Large flat tables (loot, dialogue, XP curves) |

---

DataAssets

UDataAsset — Simple Configuration Objects

`UDataAsset` (declared in `Engine/DataAsset.h`) is the base class. Assets are only loaded when directly referenced or explicitly loaded. Subclass it with typed UPROPERTY fields:

UCLASS(BlueprintType)
class MYGAME_API UMyItemData : public UDataAsset
{
    GENERATED_BODY()
public:
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Item") FText DisplayName;
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Item") float BaseDamage = 10.f;
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Item") TSoftObjectPtr<UStaticMesh> Mesh;
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Item") TSoftClassPtr<AActor> SpawnClass;
};

In the editor: right-click in Content Browser > Miscellaneous > Data Asset, select `UMyItemData`.

UPrimaryDataAsset — Asset Manager Integration

`UPrimaryDataAsset` overrides `GetPrimaryAssetId()` so the Asset Manager can track, scan, and load it. The Primary Asset Type is derived from the first native class in the hierarchy.

// PrimaryAssetType == native class name; PrimaryAssetName == asset name.
UCLASS(BlueprintType)
class MYGAME_API UWeaponDefinition : public UPrimaryDataAsset
{
    GENERATED_BODY()
public:
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon")
    FText WeaponName;

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon")
    float FireRate = 1.f;

    // meta = (AssetBundles = "X") groups soft refs for selective AM loading.
    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon",
              meta = (AssetBundles = "UI"))
    TSoftObjectPtr<UTexture2D> Icon;

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon",
              meta = (AssetBundles = "Game"))
    TSoftObjectPtr<USkeletalMesh> WorldMesh;
};

---

DataTables

Defining a Row Struct

`FTableRowBase` is declared in `Engine/DataTable.h`. Every row struct must inherit it and use `USTRUCT(BlueprintType)`.

// ItemTableRow.h
#pragma once
#include "Engine/DataTable.h"
#include "ItemTableRow.generated.h"

USTRUCT(BlueprintType)
struct FItemTableRow : public FTableRowBase
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FText DisplayName;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 MaxStack = 1;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    float Weight = 0.5f;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    TSoftObjectPtr<UStaticMesh> PreviewMesh;

    // Called after CSV/JSON import. Override for custom fixups.
    virtual void OnPostDataImport(const UDataTable* InDataTable,
                                  const FName InRowName,
                                  TArray<FString>& OutCollectedImportProblems) override;
};

In the editor: right-click > Miscellaneous > Data Table, assign `FItemTableRow` as the row struct.

Querying DataTables at Runtime

UPROPERTY(EditDefaultsOnly, Category = "Data")
TObjectPtr<UDataTable> ItemTable;

// FindRow<T>: returns nullptr if row not found or type mismatch.
const FItemTableRow* Row = ItemTable->FindRow<FItemTableRow>(
    RowName, TEXT("LookupItem"));

// GetAllRows<T>: fills array with pointers to all rows.
TArray<FItemTableRow*> AllRows;
ItemTable->GetAllRows<FItemTableRow>(TEXT("GetAllItems"), AllRows);

// ForeachRow: iterate with row name keys.
ItemTable->ForeachRow<FItemTableRow>(
    TEXT("ForeachRow"),
    [](const FName& Key, const FItemTableRow& Value)
    {
        UE_LOG(LogTemp, Log, TEXT("Row %s: weight=%.2f"), *Key.ToString(), Value.Weight);
    });

Runtime Modification and Row Handles

// AddRow/RemoveRow do not persist to disk.
FItemTableRow NewRow;
NewRow.DisplayName = FText::FromString(TEXT("Runtime Sword"));
ItemTable->AddRow(FName(TEXT("RuntimeSword")), NewRow);
ItemTable->RemoveRow(FName(TEXT("ObsoleteItem")));

// Import from CSV at runtime (RowStruct must be set beforehand).
TArray<FString> Problems = ItemTable->CreateTableFromCSVSt