UniTaskとは?

UniTaskは、Cysharpが公開している、Unity向けのasync/awaitライブラリです。

前回の記事では、標準のには次のような課題があると紹介しました。

  • Taskはクラスなので、生成のたびにヒープ確保が発生する
  • Task.DelayはOSのタイマーで動くため、Time.timeScaleの影響を受けない

UniTaskは構造体ベースで作られているので、アロケーションを抑えられます。

また、UnityのPlayerLoopに組み込まれて動くため、コルーチンと同じようにフレームに合わせて待機できます。

AsyncOperationやUnityWebRequestといったUnityの非同期処理も、そのままawaitで待てます。

使用するバージョン

  • Unity 6
  • UniTask 2.5.11

UniTaskの導入

UniTaskはPackage Managerから、GitのURLを指定して追加します。

Window → Package Managerを開き、左上の「+」ボタンから「Install package from git URL…」を選びます。

入力欄に以下のURLを貼り付けて、「Install」を押します。

https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask

バージョンを固定したい場合は、URLの末尾に#2.5.11のようにタグを付けます。

Packages/manifest.jsonに直接書き込む方法や、OpenUPMから追加する方法もあります。

基本的な使い方

UniTaskを使うときは、Cysharp.Threading.Tasks名前空間をusingします。

async UniTaskで非同期メソッドを書く

書き方は標準のasync/awaitとほとんど同じで、戻り値のTaskをUniTaskに置き換えるだけです。

using System;
using UnityEngine;
using Cysharp.Threading.Tasks;

public class UniTaskSample : MonoBehaviour
{
    private async UniTask ShowMessageAsync()
    {
        Debug.Log("3秒待ちます");

        // 3秒待機する
        await UniTask.Delay(TimeSpan.FromSeconds(3));

        Debug.Log("3秒経ちました");
    }
}

戻り値のあるUniTaskを書く

値を返したいときはUniTask<T>を使います。

Task<T>と同じように、awaitした結果をそのまま受け取れます。

ここから先のコードは、上のUniTaskSampleクラスに追加するメソッドとして読んでください。

private async UniTask<int> LoadScoreAsync()
{
    // 読み込みに時間がかかる想定
    await UniTask.Delay(TimeSpan.FromSeconds(1));

    return 100;
}

private async UniTask ShowScoreAsync()
{
    var score = await LoadScoreAsync();
    Debug.Log($"スコア: {score}");
}

async voidの代わりにUniTaskVoidを使う

Start()やボタンのイベントのように、呼び出し元でawaitできない場所ではasync voidを使いたくなります。

前回の記事で触れたとおり、async voidは例外を呼び出し元で受け取れないため危険です。

UniTaskでは、代わりにUniTaskVoidを使います。

private void Start()
{
    // 待たずに実行する場合はForget()を呼ぶ
    RunAsync().Forget();
}

private async UniTaskVoid RunAsync()
{
    await UniTask.Delay(TimeSpan.FromSeconds(1));
    Debug.Log("完了");
}

Forget()は「完了を待たずに実行する」ことを明示するメソッドです。

Forget()を付けないとコンパイラの警告が出るので、待たないときは必ず付けておきます。

UniTaskを返すメソッドにForget()を付けても、同じように実行だけできます。

コルーチンからの書き換え

コルーチンで書いていた待機処理は、ほとんどがUniTaskのメソッドに置き換えられます。

コルーチンUniTask
yield return nullawait UniTask.NextFrame()
yield return new WaitForSeconds(1f)await UniTask.Delay(TimeSpan.FromSeconds(1))
yield return new WaitForSecondsRealtime(1f)await UniTask.Delay(TimeSpan.FromSeconds(1), ignoreTimeScale: true)
yield return new WaitForFixedUpdate()await UniTask.WaitForFixedUpdate()
yield return new WaitForEndOfFrame()await UniTask.WaitForEndOfFrame()
yield return new WaitUntil(条件)await UniTask.WaitUntil(条件)
yield return new WaitWhile(条件)await UniTask.WaitWhile(条件)
yield return StartCoroutine(別の処理)await 別の処理Async()

引数なしのUniTask.WaitForEndOfFrame()はUnity 2023.1以降で使えます。

それより前のバージョンでは、UniTask.WaitForEndOfFrame(this)のようにを渡します。

フェード処理を書き換える

例として、の透明度を1秒かけて0にするフェード処理を書き換えてみます。

フェードにかける時間は、クラスにprivate const float FadeDuration = 1f;として定義しておきます。

コルーチンで書くと、次のようになります。

private IEnumerator FadeOut(CanvasGroup group)
{
    var time = 0f;

    while (time < FadeDuration)
    {
        time += Time.deltaTime;
        group.alpha = 1f - time / FadeDuration;

        // 次のフレームまで待つ
        yield return null;
    }

    group.alpha = 0f;
}

UniTaskで書くと、次のようになります。

private async UniTask FadeOutAsync(CanvasGroup group)
{
    var time = 0f;

    while (time < FadeDuration)
    {
        time += Time.deltaTime;
        group.alpha = 1f - time / FadeDuration;

        // 次のフレームまで待つ
        await UniTask.NextFrame();
    }

    group.alpha = 0f;
}

ループの中身はほぼそのままで、yield return nullがawait UniTask.NextFrame()に変わっただけです。

違うのは、StartCoroutine()を使わずに普通のメソッドとして呼び出せる点です。

ただし、このままだとフェード中にCanvasGroupが破棄されたときにエラーになります。

対策は後半の「キャンセルとタイムアウト」で紹介します。

Delayとタイムスケール

UniTask.Delay()は、標準ではTime.timeScaleの影響を受けます。

と同じく、ポーズ中にTime.timeScaleを0にすると待機も止まります。

ポーズ中も時間を進めたい場合は、ignoreTimeScale: trueを指定します。

// ポーズ中でも3秒経てば進む
await UniTask.Delay(TimeSpan.FromSeconds(3), ignoreTimeScale: true);

NextFrameとYieldの違い

yield return nullの置き換えには、UniTask.Yield()もよく使われます。

UniTask.Yield()は「次にPlayerLoopが回ってきたタイミング」で再開します。

そのため、PlayerLoopTimingを指定して呼んだ場合などは、同じフレーム内で戻ってくることがあります。

必ず次のフレームまで待ちたいなら、UniTask.NextFrame()を使うほうが確実です。

キャンセルとタイムアウト

UniTaskには、コルーチンのようにの破棄で自動的に止まる仕組みがありません。

そのため、を渡してキャンセルできるようにしておきます。

destroyCancellationTokenでキャンセルする

MonoBehaviourのdestroyCancellationTokenを渡すと、GameObjectが破棄されたときに処理が止まります。

using System;
using UnityEngine;
using Cysharp.Threading.Tasks;

public class CancelSample : MonoBehaviour
{
    private async UniTaskVoid Start()
    {
        var token = destroyCancellationToken;

        // 破棄されたらDelayの途中でも止まる
        await UniTask.Delay(TimeSpan.FromSeconds(5), cancellationToken: token);

        Debug.Log("5秒経ちました");
    }
}

先ほどのフェード処理も、await UniTask.NextFrame(cancellationToken: token)のようにトークンを渡せば、破棄と同時に止められます。

destroyCancellationTokenはUnity 2022.2以降で使えます。

それより前のバージョンでは、UniTaskの拡張メソッドGetCancellationTokenOnDestroy()で同じことができます。

キャンセルされるとOperationCanceledExceptionが発生しますが、UniTaskVoidやForget()で実行した処理ではエラーログは出ません。

CancelAfterSlimでタイムアウトさせる

「5秒以内に終わらなければ中断する」というタイムアウトも、キャンセルの仕組みで書けます。

CancellationTokenSourceのCancelAfterSlim()を使うと、指定した時間が経ったときにキャンセルされます。

using System;
using System.Threading;
using UnityEngine;
using Cysharp.Threading.Tasks;

public class TimeoutSample : MonoBehaviour
{
    private bool _isReady;

    private async UniTask WaitForReadyAsync()
    {
        // 5秒経ったらキャンセルする
        using var cts = new CancellationTokenSource();
        using var timer = cts.CancelAfterSlim(TimeSpan.FromSeconds(5));

        try
        {
            await UniTask.WaitUntil(() => _isReady, cancellationToken: cts.Token);
            Debug.Log("準備完了");
        }
        catch (OperationCanceledException)
        {
            Debug.Log("タイムアウトしました");
        }
    }
}

標準のCancelAfter()はスレッドのタイマーで動くため、UnityではPlayerLoopで動くCancelAfterSlim()を使うのがおすすめです。

CancelAfterSlim()も標準ではTime.timeScaleの影響を受けます。

ポーズ中も時間を測りたいときは、delayType: DelayType.Realtimeを指定します。

CancelAfterSlim()の戻り値はタイマーを止めるためのものなので、usingで受け取っておくと処理が先に終わったときにタイマーも止まります。

気をつける点

同じUniTaskは2回awaitできない

UniTaskは、1つのインスタンスを1回だけawaitする前提で作られています。

メソッドの中で次のように書くと、2回目のawaitで例外が発生します。

var task = UniTask.Delay(TimeSpan.FromSeconds(1));
await task;

// 2回目は例外になる
await task;

変数に入れて何度も待ちたい場合は、Preserve()を呼んでおくと複数回awaitできます。

Forget()した処理を見失わない

Forget()で実行した処理は、終わったかどうかを呼び出し元で確認できません。

止め忘れた処理が残っていないかは、Window → UniTask Trackerで確認できます。

「Enable Tracking」をオンにすると、実行中のUniTaskが一覧で表示されます。

Awaitableとの使い分け

Unity 2023.1以降では、Unity公式のAwaitableも使えます。

Awaitableは追加のパッケージなしでawait UnityEngine.Awaitable.NextFrameAsync()のように書けるのが利点です。

ただ、待機の種類はUniTaskのほうが多く、UniTask Trackerのようなデバッグ機能もそろっています。

迷ったら、まずはAwaitableで書いてみて、機能が足りなくなったところでUniTaskを導入するのがよいでしょう。

まとめ

今回は、UniTaskの導入と基本的な使い方について解説しました。

UniTaskを使うと、Unityのフレームに合わせた非同期処理を少ないアロケーションで書けます。

書き方は標準のasync/awaitとほぼ同じで、TaskをUniTaskに置き換えるだけで使い始められます。

コルーチンのyield returnも、ほとんどがUniTaskのメソッドに1対1で置き換えられます。

ただし、GameObjectの破棄で自動的には止まらないので、destroyCancellationTokenを渡す習慣をつけておきましょう。

ぜひ手元のコルーチンを1つ選んで、UniTaskで書き直してみてください。