Why
I’ve seen a lot of Unity3d projects over the years. The first thing I look for in every project is one critical piece: how does it handle asynchronous tasks. In Unity, there is a limitation that you can only talk to the engine on one thread or “train of thought.” Asynchronous tasks are how the project appears to do two things at the same time, even though they are actually only using one set of tracks. There are two very common reasons to need asynchronous tasks.
The first is for networking with a server. The Internet takes time, no matter how fast or strong the connection you have to it. And you can’t just make the entire game halt while you wait to talk to the server. Everything is on that one track – including drawing your game. If you wait for the network response, your game isn’t drawing anything at all. It just freezes.
The second reason to need asynchronous tasks is to load assets. If you’re loading a new level, it takes time to load all those neat objects and textures you spent so much time and effort into creating. Even for simple levels, most of the time it’s pretty fast. But these devices are doing a whole bunch of other things like checking your email. Sometimes it can take minutes!
Fortunately, most games don’t actually need this asynchronous ability. They can get by with freezing the screen for a moment and then moving on. Therefore typical Unity tutorials do nothing to teach about it. This is a real problem! Tutorials don’t offer much for best practices. This leaves many coders casting about for their own solutions, which often end up overcomplicated and wasteful. Worse is the fact that retrofitting the code is often very difficult.
Coroutines
Unity handles asynchronous tasks with a C# idiom called “coroutines”. They are a way to turn a regular function “inside out”, breaking it down into steps that will stop when the coder says so, allow it to do something else, and then come back later to where it was. The technology is part of the C# standard, which turns a method containing “yield return thing;” into an IEnumerable class that the caller uses for its side effects.
What Unity adds is StartCoroutine to most of the common classes to run those IEnumerable classes for you. This works fine in most cases. Until something goes wrong! Unfortunately, error handling isn’t included. If the coroutine method throws an exception, the most you get is an error in the log. It completely breaks anything that’s waiting on the coroutine, just jumping off into nowhere, with hardly any way to recover or even find out what happened!
Another place coroutines fall down is for returning values. Coroutines cannot have “out” or “ref” parameters. This means to get a value out of an asynchronous process, you have to pass in an object that will get the resulting value and then read from that.
Callbacks
Another standard C# idiom is the “callback.” These actually seem easier to use than coroutines, because you can create callback handlers just about anywhere. At the place you start an asynchronous call, you can immediately declare an “inner” method to handle the result of that call. All of it just happens for you, nice and clean.
Until you have to chain a bunch of tasks together, and properly deal with errors at any stage of the tasks. Suddenly you’re facing what I will refer to as “boomerang hell.” This is where there are so many callbacks and inner methods that the intent of the code is unreadable. Let’s start with a real world example. We need the game manager to “load next level.” This makes a server call to find out what the next level is. Back in the game manager, it asks the level manager to load the level. And then the game manager asks the game piece manager to load the player’s pieces based on the server response. Only then it ‘switches’ the game mode to the new level. Here’s what that would look like with callbacks.
public class GameManager
{
public Promise LoadNextLevel()
{
var result = new Promise();
var getNextLevelToken = _networkManager.GetNextLevelFor(_player);
getNextLevelToken.OnSuccess += (getNextLevelResult) =>
{
// load the level
var loadLevelToken = _levelManager.LoadLevel(getNextLevelResult.levelName);
loadLevelToken.OnSuccess += (loadLevelResult) =>
{
// and start loading the pieces
int numWaiting = 0;
Exception lastError = null;
// call when all pieces are done
var loadPieceDone = ()=>
{
if (lastError == null)
{
// All finished without error.
SetGameMode(getNextLevelResult.levelName);
result.Succeed();
} else {
// error.
// Note how we add information to the exception, creating nested Exceptions as a kind of higher-level stack trace
result.Fail(new Exception("Trying to load next level "+getNextLevelResult.levelName,innerException:lastError));
}
};
foreach (var name in getNextLevelResult.levelName)
{
var loadPieceToken = _pieceManager.LoadPiece(name, _player);
numWaiting ++;
loadPieceToken.OnSuccess += (loadPieceResult) =>
{
numWaiting --;
if (numWaiting == 0)
loadPieceDone();
};
loadPieceToken.OnFail += (error3) =>
{
numWaiting --;
if (numWaiting == 0)
loadPieceDone();
};
}
};
// deal with errors appropriately
loadLevelToken.OnFail += (error2) =>
{
result.Fail(new Exception("Trying to load next level "+getNextLevelResult.levelName,innerException:error2));
};
};
// deal with errors appropriately
getNextLevelToken.OnFail += (error1) =>
{
result.Fail(new Exception("Trying to load next level.",innerException:error1));
};
return result;
}
}
Notice how it is almost easy to read, until you add error handling. Then it gets long and difficult to read the flow of the method. And you will need error handling! You can’t just leave your players out in the cold with no indication that something happened.
A common response to this situation is “then make your methods do less.” At that point you’re making it even harder to work out the flow of what should happen.
Coroutines?
Let’s take another look at what that task would look like with coroutines. This time, we are going to use some custom wrappers that get around some of Unity’s limitations.
public class GameManager
{
// caller will do self.Run(_gameManager.LoadNextLevel());
public IEnumerator LoadNextLevel()
{
// make server call
// This 'Run()' is a wrapper on StartCoroutine().
var getNextLevelToken = Run(_networkManager.GetNextLevelFor(_player));
yield return getNextLevelToken;
if (getNextLevelToken.Failed)
{
// returning an exception automatically stops this coroutine.
// Note how we add information to the exception, creating nested Exceptions as a kind of higher-level stack trace
yield return new Exception("Trying to load next level.",innerException:getNextLevelToken.Error);
}
// load the level
var loadLevelToken = Run(_levelManager.LoadLevel(getNextLevelToken.levelName));
yield return loadLevelToken;
if (getNextLevelToken.Failed)
yield return new Exception("Trying to load next level "+getNextLevelToken.levelName,innerException:getNextLevelToken.Error);
// start loading all game pieces.
var pieceTokens = new List<Promise<GamePiece>>();
foreach (var name in getNextLevelToken.levelName)
pieceTokens.Add(Run(_pieceManager.LoadPiece(name, _player)));
// wait for all pieces to finish loading.
foreach (var token in pieceTokens)
yield return token;
// Any of them fail?
foreach (var token in pieceTokens)
{
if (token.Failed)
yield return new Exception("Trying to load next level "+getNextLevelToken.levelName,innerException:token.Error);
}
// All finished without error.
SetGameMode(getNextLevelToken.levelName);
}
}
Isn’t that so much easier to read? You always know what steps are going to happen in what order. And as an added bonus, if something were to interrupt the flow like the game being force closed, or the caller being deleted for some other reason, this will automatically stop and clean up after itself.
What madness is this? How do we get such magic for ourselves? You can get the latest at GitHub.
In another post, we will dive in deep on the design and use of this magical wrapper.