タイトル: データテーブル (DataTable)
SEOタイトル: UE5 Data Table 完全ガイド（CSV/JSON取り込み／USTRUCT行構造／Blueprint参照）
| この記事の要点 |
|
Data Table とは
UE5 の Data Table は、表形式のデータ（行 × 列）をアセットとして保持する仕組みです。1 行 1 レコードで、CSV / JSON から取り込めるため、エクセル管理しているマスターデータをそのまま UE に流し込めます。
典型的な用途:
- アイテム一覧（ID / 名前 / アイコン / 攻撃力 / 説明文）
- 敵キャラのパラメータ表（HP / 攻撃力 / ドロップ ID）
- 会話セリフ（ID / 話者 / 本文 / 次の ID）
- クエスト定義 / 装備 / バフ / 設定値
行構造（Row Structure）を定義
Data Table を作る前に、1 行の中身を表すデータ構造が必要です。C++ では USTRUCT + FTableRowBase、Blueprint では Structure アセットで定義します。
C++ で定義
// ItemData.h
#pragma once
#include "CoreMinimal.h"
#include "Engine/DataTable.h"
#include "ItemData.generated.h"
USTRUCT(BlueprintType)
struct FItemRow : public FTableRowBase
{
GENERATED_BODY()
UPROPERTY(EditAnywhere, BlueprintReadWrite) FName ItemId;
UPROPERTY(EditAnywhere, BlueprintReadWrite) FText DisplayName;
UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 Attack = 0;
UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 Price = 0;
UPROPERTY(EditAnywhere, BlueprintReadWrite) TSoftObjectPtr<UTexture2D> Icon;
UPROPERTY(EditAnywhere, BlueprintReadWrite) FText Description;
};Blueprint で定義
Content Browser → 右クリック → Blueprints → Structure → S_ItemRow。ItemId（Name）、DisplayName（Text）、Attack（Integer）など列を追加します。
Data Table アセットの作成
- Content Browser → 右クリック → Miscellaneous → Data Table
- 「Pick Row Structure」で先ほど作った
FItemRow/S_ItemRowを選択 DT_Itemsとして保存- ダブルクリックで Editor が開き、行追加・編集が可能
CSV から取り込む
マスターデータは Excel / スプレッドシートで作って CSV エクスポートし、Data Table にインポートするのが王道です。
Name,DisplayName,Attack,Price,Description
"sword01","鋼の剣",10,100,"基本的な剣です"
"sword02","炎の剣",25,500,"火属性付与"
"potion01","ポーション",0,30,"HP を 50 回復"1 列目は必ず Name（Row Name となる識別子）です。
取り込み手順
- Content Browser → CSV をドラッグ＆ドロップ
- 「DataTable Row Type」で行構造を選択
- インポート完了。再インポートも CSV 更新 → 右クリック → Reimport
Blueprint から行を取得
Get Data Table Row
Data Table → DT_Items
Row Name → "sword01"
↓
分岐: Found / NotFound
Found → Break Struct → DisplayName, Attack を使用
NotFound → エラー処理C++ から行を取得
UPROPERTY(EditAnywhere) UDataTable* ItemTable;
void AMyGameMode::SetupItem(FName Id)
{
if (!ItemTable) return;
static const FString Ctx(TEXT("ItemLookup"));
FItemRow* Row = ItemTable->FindRow<FItemRow>(Id, Ctx);
if (Row)
{
UE_LOG(LogTemp, Log, TEXT("%s ATK=%d"), *Row->DisplayName.ToString(), Row->Attack);
}
}全 Row を取り出す
TArray<FName> Names = ItemTable->GetRowNames();
for (const FName& Name : Names)
{
FItemRow* Row = ItemTable->FindRow<FItemRow>(Name, TEXT(""));
// 表示・処理
}
// 全件マップ取得
TMap<FName, uint8*> Map = ItemTable->GetRowMap();Blueprint では Get Data Table Row Names ノードを使います。
CSV / JSON エクスポート
Data Table エディタの上部メニューから Export As CSV / JSON で外部出力できます。バージョン管理や校正用に便利です。
Data Table と Data Asset の使い分け
| 項目 | Data Table | Data Asset |
|---|---|---|
| レコード単位 | 表形式（1 行 1 レコード） | 1 アセット 1 オブジェクト |
| 取り込み | CSV/JSON から一括 | 個別作成 |
| 参照 | FName で検索 | 直接参照（Soft / Hard） |
| 変更頻度 | マスタデータ向き | 個別ロジック向き |
| Blueprint で派生 | 不可 | 可（Blueprintable） |
| 例 | アイテム一覧 / 敵パラメータ | 武器プロパティ / Boss 構成 |
多言語対応（ローカライズ）
Data Table の FText 列はそのまま UE のローカライゼーションシステムに乗ります。 FString ではなく FText を使うのが必須。Editor の Gather Text フローでキー抽出され、翻訳テーブルが作れます。
運用 Tips
- CSV の1 列目 Name は重複不可。重複行はインポート時に警告
- ID（Name 列）は意味のある文字列（
sword01等）にしてデバッグ性を確保 - 大量行は Editor の表示が重くなる → 分割 Data Table or Data Asset 化
- 列追加時は Struct を変更後 Data Table の Reimport
- Hot Reload で構造変更後にクラッシュする場合は Editor 再起動が確実
- Asset Soft Reference（
TSoftObjectPtr）にすると遅延ロードになりメモリ節約
サンプル: アイテムショップ実装
void AShopManager::RefreshShopList()
{
TArray<FName> Names = ItemTable->GetRowNames();
for (FName N : Names)
{
if (auto* Row = ItemTable->FindRow<FItemRow>(N, TEXT("")))
{
FShopEntry Entry;
Entry.Id = Row->ItemId;
Entry.Name = Row->DisplayName;
Entry.Price = Row->Price;
ShopList.Add(Entry);
}
}
}FAQ
Q: 行を動的に追加できる？
A: ランタイムで UDataTable::AddRow は可能ですが、Shipping ビルドでは不可。ランタイム編集は Data Asset や独自構造のほうが向きます。
Q: CSV インポートで日本語が文字化け
A: CSV を UTF-8 (BOM 付き) で保存してください。Excel で「CSV UTF-8」を選ぶか、テキストエディタで BOM 付き変換。
Q: 行の編集を制限したい
A: Source CSV を Single Source of Truth とし、Editor 側を読み取り専用にする運用が一般的。Reimport で常に CSV を反映させます。