Couroutines in Unity Part 2

Coroutines in Unity – Encapsulating with Promises [Part 2]

In the last article we focused on the internals behind Unity’s Coroutines and went in depth on how they work. We covered IEnumerator interface and iterator blocks to get a grasp on how the engine takes care of the coroutine functions. We’ve also managed to list a few problems with the implementation and shortcomings that you can stumble upon if a need to write more complex coroutines arises.
In today’s article, we’re going to present you the idea of Promises and where they originated from.

Callbacks

Most asynchronous operations in Javascript APIs return a result with a callback (in C# terms: an Action delegate) when they finish work. You can explicitly provide a function for those, but to follow asynchronous code easier many decide to implement callbacks using anonymous functions. In theory it does seem like a decent upgrade to our Coroutines. Let’s try to form an example of how to do that in C#:

Not bad! As you can see that actually works fairly well. It gives us a possibility to return a value as well as raise errors and react to them. The problem, however, is the code growing horizontally with more indents as you stack coroutines in a sequence. Also, the error checking has to be done in each and every one of them. Eventually, with more complicated functions you end up in a callback hell. What is that? Well, let’s just copy our coroutine calls and stack four of these bad boys:

Just look at the pyramid shape and all the } and })); at the end. Yikes! You’d also need to get really creative with the names as they have to be unique. In terms of errors, you could probably clean it up a bit if you moved error handling to another function. But it still doesn’t look appealing and here we only have four coroutines stacked. When writing more complex functions or perhaps APIs for your backend services, that number can increase drastically. So, what’s the solution?

Promises

Promises have been popularized by many 3rd party Javascript libraries before getting a native implementation in ES6. It’s interesting to note that the idea itself had been actually researched and introduced in the 70s and 80s. Promises as we know them today were first introduced in a year 1988 by Barbara Liskov and Liuba Shira, but a similar idea came from the functional programming languages years before.

A C# library conforming the Promises/A+ Spec was released a couple of years ago and is a big game changer for managing asynchronous operations. Let’s dive into the code.

A Promise is an object that you return from your asynchronous function immediately, so the caller can await resolution (or error) of your operations. Essentially, it represents a proxy for a value not necessarily known when the promise is created. A Promise can be later resolved or rejected once you complete your actions. This allows asynchronous methods to return values and run like synchronous methods: except instead of the final value, they return a promise of having a value at some point in the future. The best part, however, is the simplicity of stacking them with a simple interface. Here’s how we can redo our first example and implement Promises instead of pure Action delegates:

Much better on the caller side! You get to hide and encapsulate coroutine behavior while getting all the advantages from the promises. With .Then() function you can easily stack new promises in a logical order and handle different result types throughout them. Moreover, with .Catch() you can catch exceptions in all of your promises. If any of the above gets rejected, then the promise chain will get immediately terminated and the code will jump to the nearest catch. Not only that, the catch function actually uses Exception type, so you can also easily throw your own exceptions:

As long as you extend from Exception class you can write your own exceptions, mimicking try…catch behavior. Handle them like this:

Summary

As you can see, Promises provide a great mechanism to handle your asynchronous operations. You can easily throw errors from any of your promises in stack, handle returning values as well as hide the coroutine implementation if you use it while working with Unity. You retain all the powerful aspects of Coroutines in terms of the implementation, but also improve greatly the interface for your complicated APIs and services. The library offers much more than what was covered and we strongly recommend looking up the documentation to see what else it has to offer.
In the final part of the series, we’ll show you a real example of writing a REST API interface using Unity’s Coroutines & Promises to achieve the cleanest code possible.

Continued in Part 3 here.

Coroutines in Unity Part 1

Coroutines in Unity – Encapsulating with Promises [Part 1]

Every Unity developer should be familiar with Coroutines. For many they are the way to script a lot of asynchronous and time-delayed tasks. If you’re not up to the speed, they’re pretty much special methods that can suspend and resume their execution for any time desired. In practice, they can be perceived as an illusion of concurrent functions (although they have nothing to do with threads!). There are, however, some problems that many programmers stumble upon while using them. Let’s take a closer look.

The internals

So what exactly are Unity’s coroutines under the hood? How do they work? Granted that we don’t have a direct access to Unity’s source code, but gathering evidence from Manual and expanding on the knowledge from C# we can assume this is more or less how they’re done. Let’s lean over this simple example:

You don’t have to be genius to figure out that this will log “Hello there!” in the console and “Hello from future!” after 2 seconds. But how? To understand coroutines one must first look at the function’s signature – more precisely, the returned type. The IEnumerator serves as a way of performing iterations on a collection. It controls moving from one object to the next one in a sequence.

To do it, it declares two very important members: a Current property, which has a reference to the element that enumerator (or a cursor you could say) is currently over, and a MoveNext() function, which moves to the next element whilst calculating the new current value. It also has a Reset() function that sets the enumerator to its initial position, but we’ll skip that.

Now since the IEnumerator is just an interface it doesn’t explicitly specify the Current type (other than it’s an object). We can do whatever we want to calculate the next object. MoveNext() will simply do the job and return false if we end up at the end of a sequence.

Iterator blocks

In pure C# we can easily “implement” this interface in special iterator blocks. In practice, C# compiler converts iterator blocks into state machines. Those are the functions that return the IEnumerator type and use the yield return statement to return the values (yes, multiple ones). Calling that makes the MoveNext() function simply return true and set Current to whatever you’re returning. If you want to stop the enumerator you can just call yield break which makes sure that MoveNext() returns false and terminates the sequence (think of it like break; in a loop). An example:

Compile this on your own and you’ll get the following output:

111111

This example uses the generic interface IEnumerator<T>, but as previously mentioned, you can use the regular one, IEnumerator, where your Current will be of any type. This is exactly what Unity requires in coroutines.

So, with that in mind, we start to get a clearer picture on what Unity actually does with coroutines. StartCoroutine adds the coroutine to some sort of a container. Unity iterates through every executed coroutine in StartCoroutine and performs MoveNext() on those which are ready to continue their work. As shown in the example above, it evaluates expressions between yield return statements and returns a value. If it returns false then it obviously tells Unity to terminate that coroutine (as it simply has just finished). If true, it checks the Current property (remember, non-generic interface!) and sees if there are any familiar types. Remember WaitForSeconds() in the very first example? Unity sees that and pauses the coroutine for seconds specified. In fact, it actually extends from YieldInstruction base type. You’ve also got:

  • WaitForEndForFrame, which resumes the coroutine at the end of the frame after all cameras and GUI are rendered
  • WaitForFixedUpdate, which waits until next fixed frame rate update function
  • Coroutine type itself, which you could use for nest coroutines
  • CustomYieldInstruction, introduced to write your own custom yield statements – just extend from that class and override keepWaiting property

So where’s the catch?

It goes without saying that with these simple types you can suddenly script some time-based game logic as well as asynchronous events very easily. You can show a UI notification after few seconds in just a few lines of code without any dirty timers. Not only that, but you can even yield return the UnityWebRequest.Send() function and pause your function until you get a HTTP response. “What’s the problem with that then?”, you may ask.

First of all, you can’t easily return a value from coroutines. The signature needs to return IEnumerator to keep a track of when and where to resume your method. Second of all, there is no exception handling at the coroutine level. You can’t use try…catch block with a yield statement in it. You would have to basically try catch every non-yield expression in your coroutine. But what if there are multiple expressions segregated with multiple yields? Or maybe you’d like to stack coroutines one after another. But how to communicate to the coroutines down below the pipe that the top one has encountered a runtime exception?

Fortunately, there is a solution. In the next part we’ll take a look at Promises and their origin from Javascript. Read it here.

How to Integrate Steamworks with Unity Games

Integrating Unity Games with Steamworks

I believe that many of you have thought of publishing a game on Steam. It wouldn’t be surprising, as Steam is a great distribution platform for PC and now also for Mac and Linux games. But Steam is not only about distribution. When you get approved by Valve, you gain the access to something that may help you a lot with your game development. This little thing is called Steamworks.

Steamworks features

Here’s a list of some most known Steamworks features:

  • Achievements – provide free grass roots marketing for your application. As players unlock achievements it exposes your product to their friends.
  • Error Reporting – provides dead simple error collection so that you can quickly find and fix your most common bugs. With a few simple api calls Steam will automatically collect the most common crash reports for the game or software. You can then review error reports on the error reporting page, which you can find from your application landing page in Steamworks.
  • Cloud Saves – is free storage that gives players ability to play where they choose as well as the peace of mind tha they won’t lose all the work they’ve put into your game. Cloud can also be used for software applications to store work-in-progress or special configuration settings.
  • Steam Workshop –  is a system of storing, organizing, and downloading user-created content uploaded through your application. This makes sharing custom levels, skins, or complete mods easy and user-friendly.
  • Other features to consider are stats, leaderboards, and multi-player matchmaking.
As you will accept Steamworks SDK terms & conditions you will get the access to official Steamworks SDK documentation.

As you will accept Steamworks SDK terms & conditions you will get the access to the official Steamworks SDK documentation.

Integrating Unity game with Steamworks

Steamworks SDK is distributed as a native DLL file (*.so when talking about Mac and Linux). In order to make it work with Unity you have to create a binding. Fortunately such binding already exists and it is distributed also as an easy to install, unitypackage file!

I am of course talking about Steamworks.NET. It’s an open source wrapper distributed under MIT license (you’re free to use it even in commercial projects!). The good thing about Steamworks.NET is that the authors value API compatibility over simplicity. That means that you only need a quick look over how it should be used and when you’re familiar with the concept, all you need is the official Steamworks documentation. The downside of this approach is that callback setup need one extra step, but it’s not a hassle.

Installation

To make Steamworks.NET  work you have to be a Steamworks developer and you need an AppID (this is just a number in Steam database). At the time of writing of this article you can get one after passing Steam Greenlight or by making a custom deal with Valve.

When you have acquired an AppID all you have to do is import Steamworks.NET unitypackage file to your Unity project. At the time of writing of this article the current stable version is 7.0.0, but please use installation page links instead to always get the latest version.

steamworks unitypackage installation

Steamworks.NET package includes libraries for Windows, Mac and Linux in x86 and x86_64 architectures. After importing it you don’t need to add anything else to your project. Even official Steam dll/so is included, so there are just two more steps to go.

After importing the package, a new file called steam_appid.txt will be created in your project root directory (this is the one that contains the Assets and Library folders). Open it in the text editor and replace 480 with your Steam AppID.

Finally, the last step – create a new empty game object on your scene and add SteamManager script to it. There! Now you’re good to go!

Checking to make sure it works

Make sure that Steam is running. Then create a script like this:

Add this script to a new game object on your scene and hit the Play button. If everything is OK, you will see your Steam name in your Unity Editor console!

When something went wrong you will end with an error message that may not tell you what exactly has gone wrong. If you’re working on Windows then you may want to get DebugView application. Just run it before running your Unity game and after the error is printed out, alt-tab to DebugView window and see if there’s something more in there.

 

More information and getting help

You can learn more about how to get started (and how callbacks should be handled) on the Getting Started page of Steamworks.NET documentation. It you ever feel lost, you can use SteamworksDev discussion group. It’s invite-only so you should contact Steam about getting access to this one. It is worth it!

steamworks discussion group

If you ever feel lost, please leave a comment here or reach the Knights using our Facebook page.

Using threads with Unity

If you’re an experienced developer then you most probably worked with threads at some point of your career. As you’re now working with Unity, you most probably have forgotten about how the threads were once important to you.

Unity as a game engine handles many things for you. It also introduces a functionality called Coroutines that can be threads’ substitution in most cases. Yet if you use coroutines, this code still works on a single thread so you don’t need to worry about concurrency issues. One may ask – “So why do I need threads when I can use Coroutines instead?”. It depends…

When threads are bad

You have to realize that creating a thread is an expensive operation. You use a thread poll design pattern, but there’s the moment when you have to synchronize back your computed data to the main thread. This is very individual thing, so you have to consider this very carefully, maybe even doing some performance tests, because synchronization might be more expensive operation than computing your data in the main thread in the first place.

Threads are dangerous, so you have to be very careful when synchronizing things back. You also need to remember that Unity API is not thread safe, so all calls to Unity API should be done from the main thread.

When threads are good

When you’re computing some expensive and/or long-term operations. Like:

  • AI
  • Pathfinding
  • Network communication
  • Files operations

Sometimes you don’t have other choice than using a thread. Nobody wants their game to freeze for a few seconds. Threads are often created to listen for events or handle I/O. These things should be handled as fast as possible.

TrafficReportTool_2

Threads can be used to compute pathfinding. Screenshot is showing Cities: Skylines game also made with Unity.

Minimizing the risk

You have to know about the risk. Threads can be very, very risky, because if not used with caution they can crash your game without a word of warning. What’s more, these kind of errors are very difficult to trace down, because everything may work fine for most of the time just to get you by surprise when you least expect it.

There are some techniques and libraries that you should know to minimize the risk of using threads.

The documentation

This is where you should start. You have to realize how difficult threads are and what are the basic concepts.

Use UnityToolbag Dispatcher

Dispatcher is a class that is included in UnityToolbag library. It checks if the code passed to dispatcher is always executed in the main thread, so you can safely execute Unity API code within.

Use UnityToolbag Futures

Future is another class from UnityToolbag. It depends on the Dispatcher, so you will have to install both.

Future is a reversed case of the above example. Before, we made computations in a thread and then sent the data back to the main thread. But the Future is a nice interface for getting the data back from a thread. Here’s an example:

More to read

I don’t want to repeat myself when there are many great articles about threads. You know the risks now and you know what you may gain when using thread. Now, go and learn the concepts. Here are some resources that I can recommend.

Unity 5.1 Assertion Library

There’s a great article by Yegor Bugayenko called Need Robust Software? Make It Fragile. It’s about Fail Fast philosophy where you should write your code in the way that your application will fail as fast as possible if something is significantly wrong with your data or environment.

When you’re building a mobile game with Unity then most probably you’re eager to set Script Call Optimization to Fast But No Exceptions option, as soon as you’re sure that you can do it.

Fast But No Exceptions option is hidden in Edit -> Project Settings -> Player menu (Other Settings/Optimization section). By selecting this option your code will be stripped from the exception handling code in a favor of better performance. By enabling this option you’re also taking a great risk. From now on, any exception will immediately crash your game and you won’t even know what was the cause (crash log may be not so helpful at the time).

Knowing what the stake is, you may want to enable Fast But No Exceptions option only when you’re pretty sure that your game won’t throw a single exception not ever once. There’s a plenty of situations when something may go wrong. Moreover, if you’re not the only person working in the project, the risk is even greater. It’s really easy to get NullReferenceException when your MonoBehaviour script setup requires reference to some other game objects and somebody will delete those from the scene.

Don’t assume anything

Don’t assume that your script is set up correctly. Be a pessimist and think of worst case scenario all the time. Let’s take this script for example:

This is a very basic example on how the Plane may interact with an Airport. I think you already know what I am going to say. This code will break if there’s no airport set. This is the case where we assumed that anyone who is working on the scene will be careful enough to connect all the references between the objects. It’s not so easy, because the Unity won’t give anyone any error or warning when they don’t connect all the references unless they run the scene and see the exception (that says very little for non-programmer person).

when_you_assume

OK, let’s try to make this script a little more self-aware. We want it to make a noise when something is wrong with it. In order to do that, I will use MonoBehaviour.OnValidate() message. OnValidate() is called:

  • In the editor without the need of entering the play mode
  • when any script value is changed
  • when the scene is loaded

So the script may now look like this:

That will print error messages to the console that something is wrong while playing with your game in the editor, and for most cases this will be good enough. However, you may also want to check if the airport is not null on the runtime (OnValidate() function works only in the editor).

OK, you’re now quite sure that your game is not throwing any exceptions, and all the validations are causing some (small, but still) overhead. How to get rid of it? Maybe preprocessor will help?

OK, that’s pretty lot of code for such simple task. Maybe there’s another way?

Asserts to the rescue!

If you’re Unity 5.1 (or above) user, then you can take advantage of the new assertion libraryIt’s really easy to use and all needed functions can be found inside the Assert class. Let’s use it instead of a simple null-check.

As you can see, I’ve used Assert.IsNotNull(). This function tells that I am expecting the value to be not-null and if it is null then I’d like to know about it.

Asserts have some advantages over manual checking:

  • Simple and readable code
  • Error messages are clean and readableassert error message
  • By default asserts are stripped off when building the game is in non-development mode (you don’t need to use preprocessor).

If you want asserts to be included in your build (asserts are not exceptions by default) then all you need to do is to define UNITY_ASSERTIONS in Script Define Symbols that can be found in Edit -> Project Settings -> Player menu. Asserts are not breaking the execution; assets will just print the error and the execution will continue. If you want it to act just as exceptions (breaking the execution), make sure to set Assert.raiseExceptions to true from your code.

And remember, the asserts may be used anywhere in your code (it doesn’t have to be at the beginning of Update), but it is a good practice to check as many things as possible before the actual code is executed. Fail fast and be safe!