TweenCancelBehaviourの指定ごとの挙動

.NET .NET Core .NET Framework Unity

DOTween + UniTask 環境で ToUniTask に渡す TweenCancelBehaviour の識別子ごとの挙動の説明です。

前提として、DOTween を UniTask で await するときに挙動を指定する ToUniTask メソッドには TweenCancelBehaviour を渡すことでキャンセル時の挙動を指定することができます。デフォルトではキャンセルすると（例外などが発生せずに）次のステップが実行されます。これだと都合が割ることが多いため、終了後に UniTask で判定することもできますが毎回それをすると実装の負担が大きいです。そのため、ToUniTask に TweenCancelBehaviour を指定することで挙動を制御することができます。

TweenCancelBehaviour の指定によってどういう挙動になるのか見ていきたいと思います。

確認環境

  • Unity 2021.3.5f1
  • Windows 11 + VisalStudio 2022
  • DOTween
  • UniTask 2.3.1

TweenCancelBehaviour

識別子ごとの挙動は以下の通りです。

キャンセルすると例外が発生する指定と、発生しない指定の 2 つが組であります。キャンセル時に発生する例外は OperationCanceledException です。

識別子 挙動
Kill (デフォルト) tween.Kill(false) + 例外なし
KillAndCancelAwait tween.Kill(false)+キャンセルで例外
KillWithCompleteCallback tween.Kill(true)+例外なし
KillWithCompleteCallbackAndCancelAwait tween.Kill(true)+キャンセルで例外
Complete tween.Complete(false)+例外なし
CompleteAndCancelAwait tween.Complete(false)+キャンセルで例外
CompleteWithSequenceCallback tween.Complete(true)+例外なし
CompleteWithSequenceCallbackAndCancelAwait tween.Complete(true)+キャンセルで例外
CancelAwait キャンセルで例外、例外は出るが実行は停止しない（詳細不明

Tween の各メソッドの挙動は以下の通りです。

メソッド 説明
tween.Kill(false) その場で即時終了、OnComplete が呼ばれない
tween.Kill(true) その場で即時終了、OnComplete が呼ばれる
tween.Complete(fasle) 最終位置にジャンプ、OnCompleteが呼ばれる
tween.Complete(true) 最終位置にジャンプ、途中のコールバックと OnComplete を全部呼ぶ

確認用のコード

今回の挙動は以下のコンポーネントをワールドに配置した SpriteRebderer に配置して確認しています。

// 確認用のコンポーネント
public class Square : MonoBehaviour
{
    [SerializeField] TweenCancelBehaviour _type;

    Tween tween;
    CancellationTokenSource _cts;

    //[Button]
    public async void Exec()
    {
        using (_cts) { }
        _cts = new CancellationTokenSource();

        tween.Kill();
        transform.SetLocalPosX(-1.0f);

        try
        {
            Log.Trace("開始しました --->");

            await transform.DOLocalMoveX(1.0f, 5.0f).ToUniTask(_type, _cts.Token);

            Log.Trace("終了しました <---");
        }
        catch (System.Exception ex)
        {
            Log.Warn($"【★例外発生】{ex.Message}");
        }
    }

    //[Button]
    public void Cancel()
    {
        _cts.Cancel();
    }
}

余談ですが Qiita の「DOTWeenでToUniTaskを使う時に～」という記事は例外が出る or 出ないの表記が誤ってるのでご注意ください。