【Unreal Engine】構造体（Struct）で複雑なデータを管理する方法

複雑なデータ管理の課題と構造体の必要性

Unreal Engineでゲーム開発を進めていると、キャラクターのステータス、アイテムのプロパティ、あるいは複雑な設定値など、複数の関連するデータをひとまとめにして扱いたい という場面に必ず遭遇します。

例えば、キャラクターの「体力」「スタミナ」「攻撃力」を管理する場合を考えてみましょう。これらをそれぞれ独立した変数として持つと、以下のような問題が発生します。

1. 可読性の低下: 複数の変数がバラバラになり、どの変数がどのデータセットに属するのかが分かりにくくなります。
2. ノードの煩雑化 (Blueprint): 関数に渡す引数が多くなりすぎたり、関連する変数を毎回個別に「Set」したり「Get」したりするノードが大量に発生し、グラフが複雑になります。
3. データテーブルの非効率性: データテーブル（DataTable）を使用する際、関連データを行ではなく列として管理することになり、データの構造化が難しくなります。

この課題を解決し、データを論理的かつ効率的に管理するための強力なツールが、Unreal Engineの構造体（Struct） です。

---

構造体（Struct）とは？

構造体とは、異なるデータ型（Variable Type）の変数を一つにまとめて、新しいカスタムデータ型として定義できる 仕組みです。

例えるなら、構造体は「名刺」のようなものです。名刺には「氏名（文字列）」「役職（文字列）」「電話番号（整数）」など、異なる種類の情報が、一人の人物という共通のテーマ のもとに整理されて記載されています。

Unreal Engineでは、BlueprintとC++の両方で構造体を定義・利用できます。

特徴	構造体（Struct）	配列（Array）
格納できるデータ型	異なるデータ型を混在可能	単一のデータ型のみ
目的	論理的に関連するデータをグループ化	同種のデータをリストとして保持
性質	値型（Value Type）として扱われる	値型（Value Type）として扱われる

💡 TArrayとUObjectの関係

TArray自体は値型としてコピーされますが、TArray<UObject*>のようにUObjectのポインタを格納している場合、中身のオブジェクトは参照型 として扱われます。配列をコピーしても、格納されているUObjectは同じインスタンスを指します。

USTRUCTとFStruct

C++で構造体を定義する場合、Unreal Engineの型システムに認識させるためにUSTRUCT()マクロを使用します。

• USTRUCT(): Unreal Engineのガベージコレクションやリフレクションシステムに対応した構造体を定義するために使用します。
• Fプレフィックス: Unreal Engineの慣例として、構造体の名前にはFプレフィックス（例: FCharacterStats）を付けます。

---

実践！Blueprintで構造体を作成・活用する

初心者の方にとって最も手軽なのは、Blueprintで構造体を定義する方法です。

1. 構造体の作成

1. コンテンツブラウザ内で右クリックし、「Blueprint」 -> 「Structure」を選択します。
2. 名前を付けます（例: F_ItemData）。
3. 作成した構造体をダブルクリックして開き、「New Variable」で必要な変数を追加します。

例: アイテムデータ構造体 F_ItemData

変数名	型	役割
ItemName	String	アイテム名
ItemID	Integer	アイテムID
IconTexture	Texture 2D Object Reference	アイコン画像
Stackable	Boolean	スタック可能か

2. 構造体の活用（Make/Break Structノード）

構造体は、Blueprintグラフ内で「Make Struct」ノードと「Break Struct」ノードを使って、簡単にデータの出し入れができます。

• Make F_ItemData (Make Struct): 複数の入力ピン（ItemName, ItemIDなど）を受け取り、一つの構造体ピンとして出力します。新しいデータを作成する際に使用します。
• Break F_ItemData (Break Struct): 一つの構造体ピンを入力として受け取り、個々のメンバー変数を出力ピンとして展開します。構造体内のデータを取り出す際に使用します。

これにより、関数やイベントディスパッチャーの引数を、構造体一つに集約でき、ノードの配線を大幅に簡略化できます。

graph LR
    A[Item Name String] --> M
    B[Item ID Int] --> M
    C[Icon Texture Ref] --> M
    M(Make F_ItemData) --> S[F_ItemData Variable]
    S --> B2(Break F_ItemData)
    B2 --> D[Item Name]
    B2 --> E[Item ID]

---

C++での構造体定義とBlueprintへの公開

より高度なデータ管理や、パフォーマンスが求められる場合は、C++で構造体を定義し、Blueprintから利用できるようにします。

// CharacterStats.h
#pragma once

#include "CoreMinimal.h"
#include "Engine/DataTable.h" // データテーブルで使用する場合に必要
#include "CharacterStats.generated.h"

// Blueprintから利用可能にするためのUSTRUCT()マクロ
USTRUCT(BlueprintType)
struct FCharacterStats : public FTableRowBase // データテーブルの行として使用
{
    GENERATED_BODY()

public:
    // Blueprintで編集可能にするためのUPROPERTY()マクロ
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Stats")
    float Health;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Stats")
    float Stamina;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Stats")
    int32 AttackPower;

    // コンストラクタ（初期値設定）
    FCharacterStats()
        : Health(100.0f)
        , Stamina(100.0f)
        , AttackPower(10)
    {}
};

ポイント:

1. USTRUCT(BlueprintType): この構造体をBlueprintでデータ型として使用できるようにします。
2. UPROPERTY(EditAnywhere, BlueprintReadWrite): 構造体のメンバー変数をBlueprintから読み書きできるように公開します。
3. FTableRowBase: データテーブルの行としてこの構造体を使用したい場合に継承します。

C++で定義した構造体は、Blueprint側で自動的に認識され、Blueprintで作成した構造体と同様に「Make/Break」ノードが利用可能になります。

---

よくある間違いとベストプラクティス

構造体は非常に便利ですが、その性質を理解せずに使うと予期せぬ問題を引き起こすことがあります。

❌ よくある間違い：構造体をオブジェクトのように扱う

構造体は値型（Value Type） です。これは、構造体を別の変数に代入したり、関数に渡したりする際、データ全体がコピーされる ことを意味します。

間違いの例: 「キャラクターAのステータス」という構造体を「キャラクターBのステータス」に代入し、その後「キャラクターBのステータス」の体力を変更しても、「キャラクターAのステータス」は影響を受けません。これは、代入時にデータがコピーされているためです。

💡 ベストプラクティス：オブジェクトと構造体の使い分け

用途	推奨される型	理由
静的なデータ定義	Struct	アイテムの基本データ、設定値など、単なるデータの集合体として扱う。Data Tableとの相性が抜群。
動的な状態管理	UObject / ActorComponent	キャラクターのインベントリ、ゲーム内の進行中のイベントなど、ユニークなIDやライフサイクル、動的な振る舞い（関数）が必要な場合。これらは参照型（Reference Type）として扱われます。

❌ よくある間違い：構造体に関数を持たせる（Blueprint）

Blueprintの構造体は、純粋なデータコンテナであり、関数（ロジック）を持たせることはできません。

💡 C++構造体では関数を定義可能

C++のUSTRUCTでは、通常のC++メンバー関数を定義することができます（ただしUFUNCTIONマクロは使用できません）。例えば、体力を計算するヘルパー関数などを構造体内に持たせることは可能です。ただし、これらの関数はBlueprintからは直接呼び出せないため、Blueprintでの使用を想定する場合は、別のクラスにロジックを持たせる設計が推奨されます。

💡 ベストプラクティス：ロジックは別のクラスに持たせる

構造体はデータのみを保持し、そのデータを操作するロジック（例: ダメージ計算、ステータス表示のフォーマット）は、ActorやActorComponent、あるいはBlueprint Function Library に持たせるようにしましょう。これにより、データとロジックが分離され、保守性が向上します。

---

構造体活用のポイント

Unreal Engineにおける構造体（Struct）は、初心者から中級者へのステップアップに不可欠なデータ管理手法です。

構造体活用のメリット	詳細
データのカプセル化	関連するデータを論理的にグループ化し、コードやBlueprintの可読性を高めます。
Data Tableとの連携	複雑なゲームデータをExcelやCSVから効率的にインポート・管理するための基盤となります。
インターフェースの簡素化	関数やイベントの入出力ピンを大幅に減らし、Blueprintグラフの配線をシンプルにします。
C++とBlueprintの連携	C++で定義した堅牢なデータ構造を、Blueprintで手軽に利用可能にします。

構造体を活用することで、あなたのプロジェクトのデータ管理は格段に整理され、大規模な開発にも耐えうる堅牢な設計へと進化するでしょう。まずは、最も複雑なデータセットを一つ選び、構造体への置き換えを試してみてください。