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.


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 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:


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:


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.

Myths and Facts of the Unity Game Engine

Unity is only for games

It’s a myth. Of course Unity has been created as a game engine, but it’s so flexible that it is successfully being used in other industries, such as architecture, medicine, and engineering. For an example, see 3RD Planet.

It is the largest online consumer event platform, showcasing the top tourist destinations in each country with Unity 3D.

The Coherentrx SuiteAnother example is The Coherentrx Suite.

CoherentRx is a suite of point-of-care patient education applications that combine realtime 3D anatomy models with HIPAA-compliant doctor-patient messaging. CoherentRx apps currently address ten medical specialties, from orthopedics to opthalmology.

In the Unity Showcase there’s a separate category for non-game applications. Check it out yourself!

Unity is free

It’s a myth, but not entirely. You can download Unity for free. The free (personal) version of Unity has all the features that Unity Professional has (with some small exceptions). When your game is ready, you can publish it and make money out of it! It’s just like that! But if at one point your company exceeds a turnover of $100,000, then you are obligated to purchase the Unity Professional license. It’s not too expensive at that point, because the cost is $1500 US dollars. Sounds really cheap when compared to $100,000, doesn’t it?

The difference between free license and pro license is that in the former one mobile games and web games display a Unity logo for few seconds on startup. It’s not a big deal, but as a professional game developer you may want to get rid of it sometime in the future. Also, you aren’t allowed to use Unity editor pro skin and Cache Server.

You can only do small games with Unity

It’s a myth. The reason why there are so many small games created in Unity is that it is very indie-friendly. Unity does not constrain your game size in any way. You can create a clone of World of Warcraft if you really want to! All scenes can be loaded and merged in the run-time, so player won’t see any loading screens while playing. It’s also not true that Unity performance degrades when you have too much objects on your scene. Of course you have to optimize it in a special way. So it’s all about the experience.

One of the greatest examples of a large-scene and well-optimized Unity game is City Skylines.

Unity is worse than Unreal Engine

It’s a myth, but it really depends on what are your needs (it’s not worse in general). Unity has been always compared to Unreal Engine because the latter always had the upper hand in game development industry. Today the situation is a little different. While Unreal Engine was targeting PC and stationary consoles, Unity took its chances with mobile devices. Unreal was always about big games with stunning visuals, but this approach made it more difficult to learn and use. Unity on the other hand is based on the Mono platform. Thanks to that you can program your games using C# instead of C++ which is quite difficult to learn.


Unity GDC demo – Adam – Part 1

Today Unity is trying to take over the Unreal Engine market. The first steps were made by Unity 5 graphics enhancements and by the optimization of scripting backend. On GDC 2016 Unity Technologies has published a stunning real-time demo of what Unity 5.3.4 is capable of. From today it will be more and more difficult to tell the difference between Unity and Unreal Engine graphics capabilities.

You don’t need programming knowledge to use Unity

It’s a fact. It’s easier when you have at least some programming knowledge, but you can easily build a complete game without it. One of the most popular editor extensions on the Asset Store is Playmaker. Playmaker allows you to build finite-state machines that will drive your entire game logic, and it does it well! If you need a good reference, then Dreamfall Chapters is a damn good one!

playmaker screen

Because of this fact many people may consider Unity as a toy rather than a serious tool for creating games. The truth is that Unity can be used by everyone, regardless of your skills!

You cannot spawn threads in Unity

Again, it’s a myth. Many people are confusing Unity coroutines with threads. Let’s get this straight: Coroutines have nothing to do with threads. Coroutine is only a way to delay code execution without too much effort. It’s really a great method of writing game code when some routines are needed to be executed in sequence over a time (like animations), but everything is still done in a single thread.

Yet you can create threads in Unity. You will not find too much about it in the official documentation, because there’s not much to be said. All you need to know is that Unity API is not thread safe, but it is a good thing! To learn more about how to use threads in Unity please read our article about threads.

All Unity games looks the same

It’s a myth, of course. Every developer who decides to use one game engine or another is asking himself a question how this game engine will help him and how it will constrain his ideas.  Unity is quite interesting because it’s easy to learn and hard to master. Yet if you will master it you will realize that you can do almost anything with it! You can even create your own game engine within! If you’re still wondering if Unity constrains your creativity, stop right now. It doesn’t!

You need to know that many of Unity components (like physics) can be replaced by anything you want. There’s no requirement of Unity game using components provided by Unity. This is a great deal if you have very specific needs.

Unity has a lot of bugs

It’s a fact. Since Unity 5 the developers were rushing forward with new features, but with a cost of stability. On GCD 2016 current Unity CEO John Riccitiello announced that Unity will take a road of increasing Unity releases’ quality. At the time Unity 5.3.4 has been released and Unity 5.4 entered a beta stage. Let’s hope for the best, because we all need a tool that is as stable as possible, and lately there was a serious fear of upgrading to a new release that could be heard in Unity community.

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.


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.

Mobile Optimization with Unity Profiler

Mobile Optimization – Unity Profiler

In the previous Mobile Optimization series post we talked about how important the batching is. We talked about how to use Unity Profiler in order to inspect how many batches are actually made. Now we will talk a little more about the Profiler itself. If you already know about it you may learn something new!

The idea

The idea behind the Profiler is to provide as much timing, memory, and statistical information as possible. You can learn:

  • how long your game needs to compute and render a frame
  • What takes so long? (scripts, physics, graphics etc.)
  • the cause of spikes (short moments when your game fps is dropping)
  • what is generating garbage
  • how much memory the game allocates
  • and many more…

To access all this data you need to:

  1. Open the Profiler window from Windows -> Profiler main menu.
  2. Make sure that the Record button is enabled.
  3. Press the Play button and pause (or disable the Record button) when you want to analyze the collected data.

profiler record button

Note that it’s highly recommended to profile your game on target platform rather than in the Unity editor. You can do so by building a Development Build and by selecting Autoconnect Profiler in the build window. Although the second is not required, it will automatically start the profiling when the game is launched.

autoconnect profiler

Be aware that you’re required to own Android Pro or iOS Pro licenses to profile on Android or iOS platforms.

Deep look onto the Profiler Window

Let’s have a look at the Profiler window. You will learn everything that you need to know from the Unity manual, but we will now look at some part of it.

profiler window

  1. 1-3 are categories of profiling methods. There is more, but these three will be the most interesting. The first one is CPU Usage. Here you will learn the total time needed for your frame to compute and render. Times are categorized to Rendering, Scripts, Physics, etc.
  2.  Rendering category shows you information about Batches, SetPass Calls (formerly draw calls), Triangles and Vertices count.
  3. Memory category informs you about memory statistics. Be sure that your game is not consuming too much!
  4. This is CPU usage profiling section. Here you will find a lot more information about theUnity internals and your own scripts performance. This is information only about a single frame, so you have to click anywhere on the graph to select a frame. By default you’re able to expand some method calls only to level 1; enable Deep Profile (button at the bottom) to browse the script calls more deeply. Be careful with deep profiling. It requires a lot of memory and it makes your game run significantly slower.

The spikes

Let’s talk about spikes. This is usual term for situations when your game fps is significantly dropping for a split second. Why this is called a “spike”? That’s because in Profiler it looks just like a spike standing out the ground.

profiler spikes

Spikes are telling you that something caused, in this exact moment, that your frame is computed longer than usual. And you should inspect it.


I will list most known cause of spikes:

Garbage collector

If you know .NET platform well enough then most probably you’re aware of the garbage collector. If you don’t, imagine that all the memory that is allocated by your game at the runtime must be freed at some point, and this is also done at the runtime. This process is called garbage collection and it freezes your game until it is finished. Usually it can take only a fraction of a second, but this is more than enough to make your game feel laggy and unpleasant. The only way to target this issue is to prevent garbage collection from happening. We will look deeper into this matter in another blog post.


Instantiating objects during the game is one of the most expensive operations. When you’re instantiating an object, you are instantiating all its children including all the components. All script components requires to be properly initialized. This is easy way to generate quite a large spike.

To prevent this from happening, learn about object pooling. Simply talking you need to instantiate all possible needed objects at the beginning and hide them until needed. There are some pool scripts on the asset store that will help you handling that issue.

Scripts and expensive algorithms

Sometimes spikes will be generated by your own scripts. Maybe you’re doing too expensive operation that could be optimized or should be done in separate thread.

This kind of spikes are usually the easiest to fix, but most probably you will need to enable Deep Profile mode to make the Profiler to generate more information about your scripts performance. Many algorithms may be optimized. Those that cannot may be executed in coroutines or separate threads. Be aware that if you will decide to move your code to a separate thread, you shouldn’t call Unity API from within that thread. Instead you should use components like Dispatcher from UnityToolbag that will dispatch Unity API calls to the main thread.

Background processes and operating system itself

Sometimes you may experience spikes that are not your game’s fault. These spikes are displayed with a large amount of time assigned to Other category. This can be seen on operating systems that are allowing too many apps to run in the background (desktop operating systems or Android). This is not something that you can do about it, so kill as many background apps as possible, keep your Profiler open and observe if the spikes will go away. You can always try profiling it on a different device.

More tips

Mobile optimization is such a broad topic that it cannot be exhausted in a single blog post. Keep watching for new blog posts tagged with Mobile Optimization tag. There will be more! Next time we will talk about garbage collecting!