unreal-cpp-gameplay

Unreal C++ ゲームプレイ

正しい UE5 ゲームプレイ C++ を記述します。C++ とエディターや Blueprints を連携させるリフレクションマクロ、Gameplay Framework のクラスの役割、 モジュール依存関係を扱います。対象は UE 5.8 です。

使用する場面

• C++ ゲームプレイクラス（AActor、APawn、ACharacter、AGameModeBase、 UActorComponent）を作成するとき、UPROPERTY／UFUNCTION でプロパティや関数を公開するとき、 GameMode のデフォルトクラスを設定するとき、または *.Build.cs でモジュール依存関係を追加するときに使用します。
• プロジェクトに UCLASS を使用する *.h／*.cpp と *.Build.cs を含む Source/ ツリーがある場合に使用します。

使用しない場面： デザイナー向けのビジュアルロジック → unreal-blueprints。プレイヤー入力の バインドの詳細 → unreal-enhanced-input。AI ロジック → unreal-behavior-trees。このスキルは、 それらの基盤となる C++ クラス／リフレクションを扱います。

基本的なワークフロー

1. 適切なプレフィックスを付けます。 A = Actor 派生、U = UObject／コンポーネント派生、 F = 通常の構造体、E = enum、I = インターフェースです。プレフィックスは基底クラスに合わせます。
2. リフレクションマクロを使ってクラスを宣言します。 クラスの上に UCLASS() を置き、クラス本体の 最初の行に GENERATED_BODY() を置き、ヘッダーでは #include "ClassName.generated.h" を 最後の include にします。
3. UPROPERTY でデータを公開し（エディター／Blueprints からの可視性とガベージコレクションによる 追跡の両方）、UFUNCTION（BlueprintCallable など）で振る舞いを公開します。
4. コンストラクターで CreateDefaultSubobject<T>(TEXT("Name")) を使ってコンポーネントを作成し、 RootComponent を設定します。
5. フレームワークでの役割を把握します。 AGameModeBase はルールとデフォルトクラスを設定し、 APawn／ACharacter は操作可能な本体、APlayerController はプレイヤーの意思、 UActorComponent は再利用可能な振る舞いを担います。
6. *.Build.cs にモジュール依存関係を追加します（例：EnhancedInput）。追加しないと 未解決シンボルのリンクエラーが発生します。
7. コンパイルして確認します。（関数本体には Live Coding の Ctrl+Alt+F11 を使用し、 ヘッダー／UPROPERTY の変更にはフルリビルドを行います。）クラスやプロパティがエディターに 表示されることも確認します。

パターン

1. 最小限の Actor クラス（ヘッダー＋ソース）

// Pickup.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Pickup.generated.h"          // MUST be the last include

UCLASS()
class MYGAME_API APickup : public AActor   // MYGAME_API = your module's export macro
{
    GENERATED_BODY()
public:
    APickup();

    // EditAnywhere = tweak per-instance & on the CDO; BlueprintReadWrite = BP get/set.
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")
    int32 ScoreValue = 10;

    // UPROPERTY on a UObject* pointer is what keeps it from being garbage-collected.
    UPROPERTY(VisibleAnywhere)
    TObjectPtr<UStaticMeshComponent> Mesh;   // UE5: TObjectPtr instead of raw UStaticMeshComponent*

    UFUNCTION(BlueprintCallable, Category = "Pickup")
    void Collect();

protected:
    virtual void BeginPlay() override;
};

// Pickup.cpp
#include "Pickup.h"
#include "Components/StaticMeshComponent.h"

APickup::APickup()
{
    Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    RootComponent = Mesh;                     // the mesh is this actor's root
}

void APickup::BeginPlay() { Super::BeginPlay(); }   // always call Super
void APickup::Collect()   { Destroy(); }

2. GameMode でデフォルトクラスを設定する

// MyGameMode.cpp — set in the constructor so the engine spawns your classes.
AMyGameMode::AMyGameMode()
{
    DefaultPawnClass      = AMyCharacter::StaticClass();
    PlayerControllerClass = AMyPlayerController::StaticClass();
}

3. Build.cs でのモジュール依存関係

// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
    "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput"
});

注意点

• generated.h が最後にない／存在しない — 「Cannot find generated header」や 「Expected an include」などのコンパイルエラーが発生します。ヘッダー内の最後の include にする必要があります。
• GENERATED_BODY() を忘れる — UHT（Unreal Header Tool）のエラーが発生します。クラス本体の最初に置く必要があります。
• UPROPERTY を付けずに UObject* を使う — ガベージコレクターが認識できず、オブジェクトが予期せず破棄されることがあります。すべての UObject ポインターを UPROPERTY で追跡します（UE5 では TObjectPtr を使用します）。
• Live Coding 中にヘッダー／UPROPERTY を編集する — Live Coding が対応するのは関数本体です。UCLASS／UPROPERTY／ヘッダーの変更には、エディターの完全な再起動とリビルドが必要です。
• クラスのプレフィックスが間違っている — Actor に UFoo（またはコンポーネントに AFoo）と名前を付けると UHT で問題が発生します。基底型に合ったプレフィックスを付けます。
• リンク時に未解決の外部シンボルが発生する — API を提供するモジュールが Build.cs の PublicDependencyModuleNames に含まれていません。
• オーバーライドした BeginPlay／Tick などで Super:: を呼び出さない — エンジンの初期化処理が省略されます。

参考資料

• UActorComponent の作成／アタッチ、UPROPERTY によるガベージコレクションの所有権ルール （TObjectPtr、TArray<TObjectPtr<>>、AddToRoot）、およびレプリケーションの入門については、 references/components-and-gc.md を参照してください。
• 公式ドキュメント：「Unreal Engine CPP Quick Start」と「Gameplay Framework」 （https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-framework-in-unreal-engine）。

関連スキル

• unreal-blueprints — デザイナー向けに C++ を公開する方法、BP／C++ の連携。
• unreal-enhanced-input — C++ の Pawn／Character で入力をバインドする方法。
• unreal-behavior-trees — ビヘイビアツリーから実行する C++ AI タスク。