【UE】Gameplay Tasks 入門

#pragma once

#include "CoreMinimal.h"
#include "GameplayTask.h"
#include "GameplayTask_Sample.generated.h"

UCLASS()
class SAMPLE_API UGameplayTask_Sample : public UGameplayTask
{
    GENERATED_BODY()

    //デリゲートを宣言する（アウトプットピンの数と型、名前を設定する）
    DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FGameplayTaskSampleDelegate, FString, OutputValue);

public:
    //コンストラクタ（メンバ変数の初期値を設定する）
    UGameplayTask_Sample(const FObjectInitializer& ObjectInitializer);

    //タスク完了時にブロードキャストするデリゲート
    UPROPERTY(BlueprintAssignable)
    FGameplayTaskSampleDelegate OnCompleted;

    //ブループリントから呼び出す用の関数
    UFUNCTION(BlueprintCallable, meta = (AdvancedDisplay = "TaskOwner, Priority", DefaultToSelf = "TaskOwner", BlueprintInternalUseOnly = "TRUE"))
    static UGameplayTask_Sample* SampleGameplayTask(TScriptInterface<IGameplayTaskOwnerInterface> TaskOwner, const FString& InputValue, const uint8 Priority = 192);

    // C++ から呼び出す用の関数
    static UGameplayTask_Sample* SampleGameplayTask(IGameplayTaskOwnerInterface& InTaskOwner, const FString& InputValue, const uint8 Priority = FGameplayTasks::DefaultPriority);

protected:
    //非同期処理を実装する関数
    virtual void Activate() override;

private:
    //タスク完了時の処理を実装する関数
    void HandleOnCompleted();

    //引数で受け取った値を保持する用のメンバ変数
    FString CachedInputValue;
};

#include "GameplayTask_Sample.h"

UGameplayTask_Sample::UGameplayTask_Sample(const FObjectInitializer& ObjectInitializer)
    : Super(ObjectInitializer)
{
    //メンバ変数の初期値を設定する
    CachedInputValue = FString();
}

//タスクを作成して返す（ここに非同期処理を書くわけではない）
UGameplayTask_Sample* UGameplayTask_Sample::SampleGameplayTask(TScriptInterface<IGameplayTaskOwnerInterface> TaskOwner, const FString& InputValue, const uint8 Priority)
{
    UGameplayTask_Sample* SampleGameplayTask = NewTaskUninitialized<UGameplayTask_Sample>();
	
    if (SampleGameplayTask && TaskOwner.GetInterface())
    {
        SampleGameplayTask->InitTask(*TaskOwner, Priority);
        SampleGameplayTask->CachedInputValue = InputValue;
    }
	
    return SampleGameplayTask;
}

//タスクを作成して返す（ここに非同期処理を書くわけではない）
UGameplayTask_Sample* UGameplayTask_Sample::SampleGameplayTask(IGameplayTaskOwnerInterface& InTaskOwner, const FString& InputValue, const uint8 Priority)
{
    UGameplayTask_Sample* SampleGameplayTask = NewTaskUninitialized<UGameplayTask_Sample>();
	
    if (SampleGameplayTask)
    {
        SampleGameplayTask->InitTask(InTaskOwner, Priority);
        SampleGameplayTask->CachedInputValue = InputValue;
    }
	
    return SampleGameplayTask;
}

void UGameplayTask_Sample::Activate()
{
    //3秒後に HandleOnCompleted() を呼び出す
    FTimerHandle TimerHandle;
    GetWorld()->GetTimerManager().SetTimer(TimerHandle, this, &UGameplayTask_Sample::HandleOnCompleted, 3.f);
}

void UGameplayTask_Sample::HandleOnCompleted()
{
    //デリゲートをブロードキャストする
    const FString OutputValue = CachedInputValue + TEXT(" World");
    OnCompleted.Broadcast(OutputValue);

    // EndTask() を呼び出してタスクを終了する
    EndTask();
}

AbilityTasks are small, self contained operations that can be performed while executing an ability. They are latent/asynchronous is nature. They will generally follow the pattern of ‘start something and wait until it is finished or interrupted’ We have code in K2Node_LatentAbilityCall to make using these in blueprints streamlined. The best way to become familiar with AbilityTasks is to look at existing tasks like UAbilityTask_WaitOverlap (very simple) and UAbilityTask_WaitTargetData (much more complex).

These are the basic requirements for using an ability task:

1) Define dynamic multicast, BlueprintAssignable delegates in your AbilityTask. These are the OUTPUTs of your task. When these delegates fire, execution resumes in the calling blueprints.
2) Your inputs are defined by a static factory function which will instantiate an instance of your task. The parameters of this function define the INPUTs into your task. All the factory function should do is instantiate your task and possibly set starting parameters. It should NOT invoke any of the callback delegates!
3) Implement a Activate() function (defined here in base class). This function should actually start/execute your task logic. It is safe to invoke callback delegates here.

This is all you need for basic AbilityTasks.

CheckList:

-Override ::OnDestroy() and unregister any callbacks that the task registered. Call Super::EndTask too!
-Implemented an Activate function which truly ‘starts’ the task. Do not ‘start’ the task in your static factory function!

We have additional support for AbilityTasks that want to spawn actors. Though this could be accomplished in an Activate() function, it would not be possible to pass in dynamic “ExposeOnSpawn” actor properties. This is a powerful feature of blueprints, in order to support this, you need to implement a different step 3:
Instead of an Activate() function, you should implement a BeginSpawningActor() and FinishSpawningActor() function. BeginSpawningActor() must take in a TSubclassOf<YourActorClassToSpawn> parameters named ‘Class’. It must also have a out reference parameters of type YourActorClassToSpawn*& named SpawnedActor. This function is allowed to decide whether it wants to spawn the actor or not (useful if wishing to predicate actor spawning on network authority). BeginSpawningActor() can instantiate an actor with SpawnActorDeferred. This is important, otherwise the UCS will run before spawn parameters are set. BeginSpawningActor() should also set the SpawnedActor parameter to the actor it spawned. [Next, the generated byte code will set the expose on spawn parameters to whatever the user has set] If you spawned something, FinishSpawningActor() will be called and pass in the same actor that was just spawned. You MUST call ExecuteConstruction + PostActorConstruction on this actor! This is a lot of steps but in general, AbilityTask_SpawnActor() gives a clear, minimal example.

AbilityTask.h

AbilityTask は、アビリティの実行中に行われる 小さく、自己完結した処理単位です。本質的には Latent（遅延）／非同期処理であり、一般的に「何かを開始して、それが完了するか中断されるまで待つ」というパターンに従います。Blueprint での使用を簡単にするために、K2Node_LatentAbilityCall に関連コードが用意されています。AbilityTask に慣れる一番良い方法は、既存のタスクを見ることです。たとえば、UAbilityTask_WaitOverlap（とてもシンプル）や UAbilityTask_WaitTargetData（かなり複雑）などです。

AbilityTask を使うための基本要件

1) AbilityTask 内に、dynamic multicast かつ BlueprintAssignable な delegate を定義します。これらはタスクの出力（OUTPUT） です。これらの delegate が発火すると、呼び出し元の Blueprint の実行が再開されます。
2) 入力は、static なファクトリ関数によって定義します。この関数はタスクのインスタンスを生成します。関数の引数が、そのまま タスクへの入力（INPUT） になります。ファクトリ関数の役割は「タスクを生成し、必要であれば初期パラメータを設定すること」だけです。callback delegate を呼び出してはいけません。
3) Activate() 関数（この基底クラスで定義されています）を実装します。この関数が、実際にタスクのロジックを開始・実行する場所です。ここで callback delegate を呼び出すのは安全です。

これだけで、基本的な AbilityTask は実装できます。

チェックリスト

-OnDestroy() をオーバーライドし、タスクが登録した callback を解除してください。その際、Super::EndTask も必ず呼び出してください。
-タスクを本当に「開始」するのは Activate() です。static ファクトリ関数内でタスクを開始してはいけません。

Actor をスポーンする AbilityTask には、特別なサポートがあります。Activate() 内でスポーンすることも可能ですが、その方法では動的な 「ExposeOnSpawn」プロパティを渡すことができません。ExposeOnSpawn は Blueprint の強力な機能なので、これをサポートするために手順 3 を別の形で実装する必要があります。Activate() の代わりに、BeginSpawningActor() と FinishSpawningActor() を実装する必要があります。BeginSpawningActor() には、Class という名前の TSubclassOf<YourActorClassToSpawn> 型の引数が必要です。また、SpawnedActor という名前の YourActorClassToSpawn*& 型の out 参照引数も必要です。この関数内で、Actor をスポーンするかどうかを判断して構いません（例：ネットワーク権限がある場合のみスポーンする、など）。Actor を生成する場合は、SpawnActorDeferred を使います。これは重要で、そうしないとスポーンパラメータが設定される前にUCS（User Construction Script）が実行されてしまいます。BeginSpawningActor() は、生成した Actor を SpawnedActor パラメータに必ず設定してください。（この後、生成されたバイトコードによって、ユーザーが設定した ExposeOnSpawn パラメータが自動的に設定されます）Actor を生成していた場合、次に FinishSpawningActor() が呼ばれ、先ほど生成した同じ Actor が渡されます。この関数内で、必ず ExecuteConstruction と PostActorConstruction を呼び出してください。手順は多いですが、全体像を理解するには AbilityTask_SpawnActor() が 最小かつ分かりやすい実装例になっています。

ChatGPT による和訳

#pragma once

#include "CoreMinimal.h"
#include "Abilities/Tasks/AbilityTask.h"
#include "AbilityTask_Sample.generated.h"

UCLASS()
class SAMPLE_API UAbilityTask_Sample : public UAbilityTask
{
    GENERATED_BODY()

    //デリゲートを宣言する（アウトプットピンの数と型、名前を設定する）
    DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FAbilityTaskSampleDelegate, FString, ReturnValue);

public:
    //コンストラクタ（メンバ変数の初期値を設定する）
    UAbilityTask_Sample(const FObjectInitializer& ObjectInitializer);

    //タスク完了時にブロードキャストするデリゲート
    UPROPERTY(BlueprintAssignable)
    FAbilityTaskSampleDelegate OnCompleted;

    //ブループリントや C++ から呼び出す関数
    UFUNCTION(BlueprintCallable, meta = (HidePin = "OwningAbility", DefaultToSelf = "OwningAbility", BlueprintInternalUseOnly = "TRUE"))
    static UAbilityTask_Sample* SampleAbilityTask(UGameplayAbility* OwningAbility, const FString& InputValue);

protected:
    //非同期処理を実装する関数
    virtual void Activate() override;

private:
    //タスク完了時の処理を実装する関数
    void HandleOnCompleted();

    //引数で受け取った値を保持する用のメンバ変数
    FString CachedInputValue;
};

#include "AbilityTask_Sample.h"

UAbilityTask_Sample::UAbilityTask_Sample(const FObjectInitializer& ObjectInitializer)
    : Super(ObjectInitializer)
{
    //メンバ変数の初期値を設定する
    CachedInputValue = FString();
}

//タスクを作成して返す（ここに非同期処理を書くわけではない）
UAbilityTask_Sample* UAbilityTask_Sample::SampleAbilityTask(UGameplayAbility* OwningAbility, const FString& InputValue)
{
    UAbilityTask_Sample* SampleAbilityTask = NewAbilityTask<UAbilityTask_Sample>(OwningAbility);

    if (SampleAbilityTask)
    {
        SampleAbilityTask->CachedInputValue = InputValue;
    }

    return SampleAbilityTask;
}

void UAbilityTask_Sample::Activate()
{
    //3秒後に HandleOnCompleted() を呼び出す
    FTimerHandle TimerHandle;
    GetWorld()->GetTimerManager().SetTimer(TimerHandle, this, &UAbilityTask_Sample::HandleOnCompleted, 3.f);
}

void UAbilityTask_Sample::HandleOnCompleted()
{
    //デリゲートをブロードキャストするべきかどうか（アビリティが有効かどうか）を確認する
    if (ShouldBroadcastAbilityTaskDelegates())
    {
        //デリゲートをブロードキャストする
        const FString OutputValue = CachedInputValue + TEXT(" World");
        OnCompleted.Broadcast(OutputValue);
    }

    // EndTask() を呼び出してタスクを終了する
    EndTask();
}

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "SampleActor.generated.h"

UCLASS()
class SAMPLE_API ASampleActor : public AActor
{
    GENERATED_BODY()

public:	
    ASampleActor();

    UPROPERTY(EditDefaultsOnly, BlueprintReadOnly)
    TObjectPtr<UGameplayTasksComponent> GameplayTasksComponent;

protected:
    virtual void BeginPlay() override;

public:
    virtual void Tick(float DeltaTime) override;

private:
    //コールバック関数（UFUNCTION() を必ず付ける）
    UFUNCTION()
    void OnCompleted(const FString OutputValue);
};

#include "SampleActor.h"
#include "GameplayTasksComponent.h"
#include "GameplayTask_Sample.h" //追加

ASampleActor::ASampleActor()
{
    PrimaryActorTick.bCanEverTick = true;

    GameplayTasksComponent = CreateDefaultSubobject<UGameplayTasksComponent>(TEXT("GameplayTasksComponent"));
}

void ASampleActor::BeginPlay()
{
    Super::BeginPlay();

    // C++ 用の関数を使って UGameplayTask_Sample* を取得する
    //（IGameplayTaskOwnerInterface を参照渡しする）
    UGameplayTask_Sample* SampleGameplayTask = UGameplayTask_Sample::SampleGameplayTask(*GameplayTasksComponent, TEXT("Hello"));

    if (SampleGameplayTask)
    {
        //コールバック関数を登録する
        SampleGameplayTask->OnCompleted.AddDynamic(this, &ASampleActor::OnCompleted);

        // ReadyForActivation() でタスクを実行する
        SampleGameplayTask->ReadyForActivation();
    }
}

void ASampleActor::Tick(float DeltaTime)
{
    Super::Tick(DeltaTime);
}

//コールバック関数
void ASampleActor::OnCompleted(const FString OutputValue)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *OutputValue);
}

#pragma once

#include "CoreMinimal.h"
#include "Abilities/GameplayAbility.h"
#include "SampleGameplayAbility.generated.h"

UCLASS()
class SAMPLE_API USampleGameplayAbility : public UGameplayAbility
{
    GENERATED_BODY()

protected:
    virtual void ActivateAbility(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo* ActorInfo, const FGameplayAbilityActivationInfo ActivationInfo, const FGameplayEventData* TriggerEventData) override;

private:
    //コールバック関数（UFUNCTION() を必ず付ける）
    UFUNCTION()
    void OnCompleted(const FString OutputValue);
};

#include "SampleGameplayAbility.h"
#include "AbilityTask_Sample.h" //追加

void USampleGameplayAbility::ActivateAbility(const FGameplayAbilitySpecHandle Handle, const FGameplayAbilityActorInfo* ActorInfo, const FGameplayAbilityActivationInfo ActivationInfo, const FGameplayEventData* TriggerEventData)
{
    Super::ActivateAbility(Handle, ActorInfo, ActivationInfo, TriggerEventData);

    //自身を第一引数に渡して UAbilityTask_Sample* を取得する
    UAbilityTask_Sample* SampleAbilityTask = UAbilityTask_Sample::SampleAbilityTask(this, TEXT("Hello"));

    if (SampleAbilityTask)
    {
        //コールバック関数を登録する
        SampleAbilityTask->OnCompleted.AddDynamic(this, &USampleGameplayAbility::OnCompleted);

        // ReadyForActivation() でタスクを実行する
        SampleAbilityTask->ReadyForActivation();
    }
}

//コールバック関数
void USampleGameplayAbility::OnCompleted(const FString OutputValue)
{
    UE_LOG(LogTemp, Log, TEXT("%s"), *OutputValue);
}