ue-data-assets-tables

What this skill does

# 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:

```cpp
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.

```cpp
// 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)`.

```cpp
// 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

```cpp
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

```cpp
// 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->CreateTableFromCSVString(CsvContent);

// Import from JSON at runtime. JSON format uses "RowName" as key with struct fields as properties.
TArray<FString> JsonProblems = ItemTable->CreateTableFromJSONString(JsonContent);

// Export to CSV/JSON strings (WITH_EDITOR only — unavailable in cooked/shipping builds):
FString CsvOut  = ItemTable->GetTableAsCSV();
FString JsonOut = ItemTable->GetTableAsJSON();

// FDataTableRowHandle: a UPROPERTY-friendly typed row reference.
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Config")
FDataTableRowHandle StartingWeaponHandle;

const FItemTableRow* Row = StartingWeaponHandle.GetRow<FItemTableRow>(
    TEXT("StartingWeapon lookup"));
```

---

## Asset References

### Hard References

```cpp
// Hard ref: loaded when the referencing asset loads. Causes the mesh/material
// to be in memory as long as this object is alive.
UPROPERTY(EditDefaultsOnly, Category = "Art")
TObjectPtr<UStaticMesh> Mesh;          // UE5 TObjectPtr preferred over raw ptr
```

Use hard references only for assets that are always needed while this object exists (e.g., a character's skeleton).

### Soft References

Soft references store a path string. The asset is NOT loaded until explicitly resolved.

```cpp
// TSoftObjectPtr<T>: soft ref to an asset instance.
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Art")
TSoftObjectPtr<UStaticMesh> MeshSoft;

// TSoftClassPtr<T>: soft ref to a class (blueprint subclasses especially).
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Spawning")
TSoftClassPtr<AActor> SpawnableSoft;

// FSoftObjectPath: untyped path, useful for generic systems.
FSoftObjectPath MeshPath = MeshSoft.ToSoftObjectPath();
```

#### Synchronous Resolution (avoid on game thread for large assets)

```cpp
UStaticMesh* Mesh = MeshSoft.LoadSynchronous();   // Blocks until loaded.

// FSoftObjectPath::TryLoad — returns nullptr if not on disk, does not assert.
UObject* Loaded = MeshPath.TryLoad();
```

#### Checking State Without Loading

```cpp
if (MeshSoft.IsNull())    { /* no path set */ }
if (MeshSoft.IsValid())   { /* path set AND asset is loaded in memory */ }
if (MeshSoft.IsPending()) { /* path set, async load started, not complete */ }

UStaticMesh* MeshPtr = MeshSoft.Get(); // Returns nullptr if not loaded.
```

---

## Async Loading

### FStreamableManager

`FStreamableManager` is declared in `Engine/StreamableManager.h`. Access it via `UAssetManager::GetStreamableManager()`.

```cpp
FStreamableManager& SM = UAssetManager::GetStreamableManager();