【Unreal Engine】Data Table Basics: From Struct Definition to CSV Import

In game development, there's massive amounts of data to manage: character stats, item parameters, level design values, and more. Writing this data directly into Blueprint or C++ code causes problems like:

1. Inefficient Adjustment: Every small data change requires code editing and recompilation.
2. Role Mixing: Designers and planners want to adjust data but need programmer help.
3. Poor Data Visibility: Hard to grasp where and what data exists without reading code.

Data Table in Unreal Engine solves these problems and dramatically improves development efficiency and data manageability. This article explains everything from Data Table basics, to efficient data import using external CSV files, to practical Blueprint usage, in beginner-friendly terms.

---

Data Table Basic Structure

Data Table is an asset for centrally managing game data in a spreadsheet-like format. However, it's not just a table—it's closely integrated with Unreal Engine Structs.

The Role of Struct

Before creating a Data Table, you need to define the data "type." This is the role of Structure.

For example, to manage item data, you define a struct called FItemData combining variables like item name (String), attack power (Integer), and price (Float). Data Table uses this struct as the "row template."

Data Table Creation Steps

1. Create the Struct:
   • Right-click in Content Browser → Blueprint → Structure and define needed variables. (e.g., ItemData_ST)

Relationship Between Struct and Data Table

-Blueprint-created structs: No special inheritance settings needed; can be directly specified as Data Table's Row Structure. This is unchanged from UE4.

-C++-defined structs: Must inherit from FTableRowBase.

// Example of defining Data Table struct in C++
USTRUCT(BlueprintType)
struct FItemData : public FTableRowBase
{
    GENERATED_BODY()

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FString ItemName;

    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 AttackPower;
};

2. Create the Data Table Asset:
   • Right-click in Content Browser → Miscellaneous → Data Table.
   • When creating, specify the struct you defined earlier (e.g., ItemData_ST) as the Row Structure.

Now the Data Table asset is created and you can directly enter data in the editor.

---

CSV File Import

Manually entering large amounts of data is inefficient. One of Data Table's greatest strengths is the ability to import external CSV (Comma Separated Values) files.

Preparing the CSV File

CSV files for Data Table import require strict formatting.

RowName	ItemName	AttackPower	Price
Sword_01	Steel Sword	15	100
Shield_01	Wooden Shield	5	50

Important Rules:

1. First Row (Header): Must exactly match variable names in the Data Table's row struct (ItemData_ST)—case-sensitive.
2. First Column (RowName): This is a special column serving as the unique identifier (key) for each row. Duplicates are not allowed.
3. Delimiter: Basically use comma (,).

Create this CSV file with Notepad or spreadsheet software like Excel and save in UTF-8 format.

Note on CSV with Japanese

CSV files containing multibyte characters like Japanese should be saved as UTF-8 with BOM. Without BOM, character corruption may occur. You can also import by dragging and dropping CSV files directly into the Content Browser (creates Data Table and imports simultaneously).

Import to Unreal Engine

1. Right-click the created Data Table asset (e.g., DT_ItemData).
2. Select Import and choose the prepared CSV file.
3. On successful import, the CSV contents appear in the Data Table editor.

Best Practice: Placing CSV files in a dedicated folder within the project's Content folder (e.g., Content/Data/CSV) makes version control easier.

---

Data Retrieval in Blueprint

Once data is stored in Data Table, use it in Blueprint.

Data Retrieval Nodes

To get specific row data from Data Table, mainly use these nodes.

Node Name	Purpose
Get Data Table Row	Get struct data by specifying Row Name (key). Most common.
Get Data Table Row by Index	Get data by specifying row index (0-based number).
Get Data Table Row Names	Get list of all Row Names (keys) in the Data Table.

Blueprint Implementation Example

Here we implement processing to specify an item's Row Name (e.g., Sword_01) and get that item's attack power.

graph TD
    A[Event BeginPlay] --> B{Get Data Table Row};
    B -- Data Table --> C[DT_ItemData (Data Table Asset)];
    B -- Row Name --> D["Sword_01 (Name)"];
    B -- Found? (Boolean) --> E{Branch};
    B -- Out Row (ItemData_ST) --> F[Break ItemData_ST];
    E -- True --> G[Get AttackPower];
    G --> H[Print String: AttackPower];
    E -- False --> I[Print String: Error - Row Not Found];

Steps:

1. Place Get Data Table Row node.
2. Specify the created Data Table asset (DT_ItemData) in the Data Table pin.
3. Enter the key for desired data (e.g., Sword_01) in the Row Name pin.
4. The corresponding struct (ItemData_ST) data outputs from the Out Row pin.
5. Connect Break ItemData_ST node to extract struct contents (ItemName, AttackPower, Price, etc.).
6. Use the Found Row pin (Boolean) to check if data was found and handle errors.

This mechanism enables game balance adjustments just by editing the CSV file without changing code.

---

Common Mistakes and Best Practices

Follow these points to use Data Table effectively.

Common Mistakes

• Struct and CSV mismatch: If CSV header names differ even by one character from struct variable names, import errors occur or data isn't read correctly.
• Duplicate Row Names: Row Names must be unique keys. Duplicates cause unintended data to be read.
• Data type mismatch: If values entered in CSV cells differ from types defined in the struct (e.g., string in an Integer variable), warnings or errors occur on import.

Best Practices

• Struct naming conventions: Add suffixes like _ST or _Data to struct names (e.g., ItemData_ST) to clearly identify them as Data Table row structs.
• Thorough data-driven approach: Consolidate adjustable values in Data Table as much as possible, eliminating magic numbers from code.
• Comments and descriptions: Always add comments (descriptions) to each struct variable so other developers can understand their meaning.
• Integration with external tools: Establish a workflow managing data in external tools like Excel or Google Sheets and using export features to generate CSV, further improving data management efficiency.

Key Points for Data Table Usage

Unreal Engine's Data Table is a powerful tool for achieving data-driven development.

Element	Key Point
Basics	Uses struct (Struct) as template.
Import	CSV file first row must exactly match struct variable names. First column is unique Row Name.
Usage	Use Get Data Table Row node, specify Row Name to get needed data.
Benefits	Enables easy data adjustment by designers and planners, improving development iteration speed.

Mastering Data Table enables more flexible, maintainable game development. Start by trying to migrate simple item data to Data Table and experience its efficiency.