Coroutine Runner - CitiesSkylinesModding/UrbanDevKit GitHub Wiki
Created by: @toverux Authors: @toverux SDKs needed: .NET (NuGet)
Overview
A simple helper class to run Unity coroutines from anywhere and convert them to C# Tasks.
Usage
Run Coroutine From Anywhere
As you may know, Unity only allows to start coroutines from MonoBehaviour
classes.
This is a bit annoying with DOTS are we are typically not using MonoBehaviour
s, but we do often need to work with coroutines.
This means you have to create an empty GameObject
and attach an empty MonoBehaviour
just to call StartCoroutine()
.
Clunky, that's why UDK does that for you.
using UrbanDevKit.Utils;
CoroutineRunner.Start(MyCoroutine());
// you can also stop them:
var coroutine = CoroutineRunner.Start(MyCoroutine());
CoroutineRunner.Stop(coroutine);
Convert a Coroutine to a Task
The extension method CoroutineRunner.RunAsTask(IEnumerator, CancellationToken?)
allows you to easily wrap a coroutine in a Task, which is generally easier to use especially in already TAP-based code.
Wrapping a coroutine yourself can be clunky and error prone (error handling, return, cancellation...), that's why UDK also exposes a shortcut for that.
using UrbanDevKit.Utils;
await MyCoroutine().RunAsTask();
// Using a cancellation token, which will call StopCoroutine():
var cts = new CancellationTokenSource();
await MyCoroutine().RunAsTask(cts.Token);
cts.Cancel();
Note that the Task that is returned:
- Is immediately scheduled for execution (it is not a "cold" Task awaiting to be awaited to start).
- Rethrows coroutine exceptions.
- Stops the coroutine if passed a CancellationToken and marks the Task as Canceled (which throws a TaskCanceledException).
- If the enumerator ends, The Task resolves with the last value the coroutine yielded.