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.

7 Ways to Keep Your Unity Project Organized

I saw a person on Quora the other day, asking how programmers are able to write projects that consist of over 10,000 lines of code. When software gets bigger, it is more difficult to maintain and that’s a fact. So here’s the thing – if you don’t keep your project organized, you’re going to have a hard time to keep the pace. Later on, you will find yourself wasting time with a messy project instead of adding new features. This is also true regarding any Unity Project. Here are (in my opinion) the most important tips that will help you with keeping your project organized.

1. Directory Structure

We cannot talk about organization without mentioning organizing project directory structure. Unity gives you a total freedom in that matter, but because of that, it can frequently get really messy. This is the directory structure I personally use:

  • 3rd-Party
  • Animations
  • Audio
    • Music
    • SFX
  • Materials
  • Models
  • Plugins
  • Prefabs
  • Resources
  • Textures
  • Sandbox
  • Scenes
    • Levels
    • Other
  • Scripts
    • Editor
  • Shaders
  1. Do not store any asset files in the root directory. Use subdirectories whenever possible.
  2. Do not create any additional directories in the root directory, unless you really need to.
  3. Be consistent with naming. If you decide to use camel case for directory names and low letters for assets, stick to that convention.
  4. Don’t try to move context-specific assets to the general directories. For instance, if there are materials generated from the model, don’t move them to Materials directory because later you won’t know where these come from.
  5. Use 3rd-Party to store assets imported from the Asset Store. They usually have their own structure that shouldn’t be altered.
  6. Use Sandbox directory for any experiments you’re not entirely sure about. While working on this kind of things, the last thing that you want to care about is a proper organization. Do what you want, then remove it or organize when you’re certain that you want to include it in your project. When you’re working on a project with other people, create your personal Sandbox subdirectory like: Sandbox/JohnyC.

2. Scene hierarchy structure

Next to the project’s hierarchy there’s also scene hierarchy. As before, I will present you a template. You can adjust it to your needs.

  • Management
  • GUI
  • Cameras
  • Lights
  • World
    • Terrain
    • Props
  • _Dynamic

There are several rules you should follow:

  1. All empty objects should be located at 0,0,0 with default rotation and scale.
  2. When you’re instantiating an object in runtime, make sure to put it in _Dynamic – do not pollute the root of your hierarchy or you will find it difficult to navigate through it.
  3. For empty objects that are only containers for scripts, use “@” as prefix – e.g. @Cheats

3. Use prefabs for everything

Prefabs in Unity are not perfect, but they are the best thing you will find to share pre-configured hierarchies of objects. Generally speaking, try to prefab everything that you put on your scenes. You should be able to create a new level from an empty scene just by adding one or more prefabs to it.

The reason why you should use prefabs is that when a prefab changes, all the instances change too. Have 100 levels and want to add a camera effect on all of them? Not a problem! If your camera is a prefab, just add a camera effect to the camera prefab!

Be aware that you cannot have a prefab in another prefab. Use links instead – have a field that requires a prefab to be assigned and make sure to assign it when instance is created. Consider auto-connecting prefab instances in Awake() or OnEnable() when it makes sense.

4. Learn how to use version control system (VCS)

git logoYou may already know something about GIT, Subversion or any other VCS out there. As a matter of fact, “knowing something” is only a small piece of what you may learn. You should focus on learning about important but infrequently used features of VCS of your choice. Why? Mostly because VCS systems are much more powerful that you think, and unfortunately many users are using these as nothing more than a backup and synchronized solutions. For example, did you know that GIT allows you to stash your changes, so you can work on them later without committing anything to your master branch?

Programmers tend to comment out blocks of code in case it’s needed later. Don’t do that! If you’re using VCS learn how to quickly browse previous versions of a file. When you are familiar with it, your code looks a lot nicer without unnecessary block of commented code.

Here’s a nice resource of tips for GIT users: http://gitready.com/

5. Learn to write editor scripts

Unity is a great game engine in the matter of extensibility (see Asset Store). Learn how to write editor scripts and utilize this knowledge. You don’t necessary need to create fancy GUI for your scripts, it can be something simple, as menu entries that are doing something useful. Here are some examples of editor scripts that I have created not so long ago:

  • Google Sheets .csv download – I had a translation spreadsheet saved on Google Drive. It automatically downloaded the newest version as .csv file, so I never had to do it manually.
  • Randomize the position, rotation and size of trees – I had a lot of trees and wanted it to look more like a forest than a grid.
  • Create distribution – Built for specified target, zips all the files and copy to the right place.
  • String replace in the sources – I had several files that contained the application version.

You can learn how to create editor scripts from the official documentation.

6. Learn to program defensively

Have you heard about defensive programming? Wikipedia defines it as follows:

Defensive programming is a form of defensive design intended to ensure the continuing function of a piece of software under unforeseen circumstances. Defensive programming techniques are used especially when a piece of software could be misused.

Generally when you’re writing MonoBehaviours, you should make sure that:

  • All needed references are set
  • All required components are present
  • If you’re using singletons, make sure that they exists
  • If you’re searching for objects and expect to find something, do it as fast as possible
  • Mix-in editor code (ExecuteInEditMode and #if UNITY_EDITOR) to do as many checks as possible before you run the scene

For many of these checks you can use asserts. You should also read A Story of NullPointerException Part 1 and 2.

7. Implement in-editor and/or in-game cheats

After you learn how to write editor script, you should be able to write a set of in-editor cheats. It can work as menu entry that unlocks something (all levels for instance). It’s really easy to create:

Generally you should write cheats that will allow you to:

  • Unlock all levels, characters, items etc
  • Give you immortality
  • Add/subtract values like time, money, coins etc
  • Allow you to see things not meant to be seen by players
  • Anything else that will help you with testing your game

Of course more practical (but harder to write) are in-game cheats. These type of cheats can be executed outside Unity editor, but you have to think how you would like to execute it. See our other article about implementing cheats subsystem controlled by mouse.

Finite State Machines [Part 3]

Here’s our final blog tutorial for the FSM. We will review what we’ve discussed on the first part, and implement the FSM System that we did before.

Just a recap on the previous parts:

sOSpPXe__WTretdttbvYesQ

This will be the loop of our FSM. First we initialize the FSM, create states, create actions, and map them all together. After we have mapped them, we will now start the FSM and indicate the state that the AI will start to. Now, the AI will change to a specific state, and the FSM will initialize the action, update it until it the action finishes and sends an event indicating that the action is finished. Finally, the FSM will go back and change the state.

Now it’s time to implement them.

Text Action

Let’s create a TextAction so that we’ll see the FSM System first hand.

1FReRU4CWYFVPXTHKa65PQqfu7VQx6nJ3poP4_6A

Let’s first import the Common.FSM so that we could use our FSM system, and let this class inherit the FSMAction class.

Let’s now write the variables and constructor for this specific action.

textToShow is the string that we will print out in the console when updating. Duration is the length of this action, and the finishEvent is the call to transition to another state.

Let’s override the virtual functions of the FSMAction so that the FSM could call them.

OnEnter will handle all the things that we want to do when starting an action. Just like a Start() in MonoBehaviour, we will initialize our action at this stage. Update will be called by the FSM’s action processor, that is called by the FSM’s Update function, and that is called by our AI’s class. On exit of course, will be the things that we will do when we finishes an action. Personally, I’d rather have a finish function that will send the event.

AI Implementation

Now that we’ve made an action, let’s make an AI.

1vBWCxCqzAGoyCv4XThrLnrhqyVKfgTpDvPZN4Tk

Let’s create an empty that will hold our AI script.

1fHeGwtXW1jPMC7ezRqHJpHrrztNsHa7yKHwb3q4After creating an empty, let’s create a script that will implement our FSM system and the action that we made.

Let’s make two FSMStates and two FSMAction for our AITest. Don’t forget to import Common.FSM or we won’t be able to use the FSM system that we’ve made.

Again, fsm will be the engine of our state machine, we will have two kinds of state, PatrolState, and IdleState. It’s up to you how you want to name them. Lastly, we will have two text actions, one for each state, PatrolAction, and IdleAction.

Let’s now create the FSM, States, and Actions in the Start() function.

First, we will initialize the FSM, then add new states. Remember, FSM.AddState() returns FSMStates so that we won’t have to declare a new FSMState, and add them to the FSM.

Now that we have states and action, let’s now map everything, and add event ids to every transitions.

We mapped the PatrolState to IdleState when an event was sent to the state and vice versa. Let’s now initialize our actions.

The first property which is a string, will be the output of our action, the second one will determine the duration of the action, and the last property will be the event that it will send out after the action is finished.

Keep in mind that everything here is inside the start function. Let’s now try and make the FSM work by calling the FSM.Start() and FSM.Update();

Again, fsm.Start() is called after all initialization under the Start(). Now let’s attach the AITest to the empty game object that we created earlier and press Play in the editor.

Now finally, watch the automation happens!

1s-7f6nFEDuhmfFSXjaXAk0_Fh0Jyhs1P_N6EKsQAI will print out Idle for every 2 seconds and will Patrol every 3 seconds.

Moving Action

1VwqSEDvSaDRP50DJsCX2w-dso9Bch-lcqp0D9y8Now let’s take it to another level. Let’s make a moving object and at the same time, printing out strings in the console. But we’re not going to do it in one action. We’ll be creating another action that will be added to the same state.

Let’s make another script called AITestTwo.

1IU-GFRQu-tgoJLrMoM_GZ2SxE0rq6sMd5cfswRALet’s create another action called MoveAction. This will be a generic action for moving object.’

Open up the MoveAction.cs and let’s write the action.

 

MoveAction.cs is different, we have to have a reference to the object’s transform so that the action could move it.

 

Let’s discuss the properties. As I said above, we will need to have the object’s transform to be referenced in this action since we want THIS action to move the object, NOT the AI Class. Pretty self explanatory, Vector3 from, and to. Again, duration of the action, and the finish event.

As you see there, we have two variables that aren’t included in the Init() properties which is the journeyLength, and polledTime. We will use them for our Vector3.Lerp function later on. The polled time will be included in our calculation later on.

Now we added a helper function for position which is the SetPosition() to make things easier for us. Again, OnEnter() initializes the action, the OnUpdate() will be the one that will execute the Lerp function. This is also where we will calculate the ratio that is needed for the Lerp function. When the action finishes, we will set the object to the desired final position, and reset our variables.

Multi-action Implementation

Now, let’s go and set up the second AI.

We now have two actions for each state. The FSM will now update two actions in one state. What we did here is just the same from what we did on the TextAction.cs. We made instances of the classes, added the actions to states, and added transitions and calls to those states, and initialized the actions.

Now let’s hit play and hope that it works properly.

1KDFzVJldz17rgpUe8XPO884SAYqx5JYzd5D8jaA

1RmIMDg8oKBNpn_2JPWFTLf1FNPbdbYj0YmMe4Ic

As you can see, the AI is now doing the actions at the same time. You can mix different actions and add them dynamically to your desired state.

What’s great about this is that you can add a lot of actions and contain them into one state and do them simultaneously. Although it will cause you some performance issues if you’re on mobile. What I suggest is that, when you use it for mobile, just do at least 1 or 2 actions simultaneously just for safety. I haven’t done real tests for mobile though.

So there it is, we have concluded our Dynamic FSM tutorial. I hope that this will become helpful for your games. You could use this in any game, in any way. Whether you use it on UI, GameObjects, or whatever fits your needs. Please do remember to comment if you have any questions, I am happy to send a reply as soon as I can!

FSM is a really big topic to cover in three parts, so here are few of the FSM-related articles and implementations if you want to understand it a little better. I believe these will explain FSM much further:

This is the link for the unity package if you want to see the whole project.

This is the link for the scripts that we made all throughout.

Finite State Machines [Part 2]

Deeper inside FSM

Finite State Machines are a sequential logic that are very low level. They can be used for simple decision-making logic. Let’s give a human example of an FSM:

  • Input: Flips the switch
  • State: Light Bulb is in the state of “On”
  • Output: Light Bulb will now produce light for the room

Inputs are any form of stimulus from the user that can trigger a change of state based on the condition needed to perform that states. Think about switching a light on:

States as you can see, describes the current condition of the FSM. Until the user makes another input, the light bulb won’t change its state to “Off”.

Outputs are linked to the FSM’s state depending on how the FSM is programmed by the programmer.

FSM Implementation

This is my way of implementing a dynamic FSM in Unity. This will require us to have the main FSM class per object that holds the states; FSM State for the object that holds the actions;  and FSM Actions that does the outputs of the state.

Now that we’ve introduced the FSM to you, let’s now do some scripting. Let’s do them one by one. First, let’s organize our unity project.

fsm1It’s up to you where to place them. I always separate my game-only-assets to other assets. We’re going to put this FSM in our common folder(I always have the “Common” folder because I have my own library that I use in every games) because this FSM system will be dynamic and you will be able to use everything to every games.

The reason why we have a folder for actions is to compile all the actions that we make, and create a library of actions for other kinds of games.

Let’s now create our main FSM class, and put it in the FSM folder under common, and let’s call it FSM.cs.

FSM.cs

Couple of things, I’m a namespace fanatic and it’s a great practice to segregate your codes if you’re not using any of them. Again, I have my Common library which is why I placed it under Common. You can create your own namespace if you want to.

As you can see, we’re not inheriting from MonoBehaviour class because we will have an update function that will be called under the AI’s update instead to update the FSM.

Now let’s make some variables and functions for our FSM.

Just a tip, if you think that the code is starting to look dirty because of all the summary, just enable the code colding of monodevelop. Just go to Tools/Options/Text Editor/General, and check “Enable Code Folding”

1f6YhKn0Eab-kWruxMd5SxtZwbhJ3QJ0etcD6jlg

Now we can fold the summaries in the code itself.

142BcsOI5X_HbKXwAr70JOlyX13ApnXzOxFkFyZM

Before we go any further, let’s create the FSMState, and FSMAction because we need to create functions in the FSM that will return them. Let’s start with the FSMAction.

FSM Action Impementation

FSMAction will be the base class of our actions, hence the virtual functions. If you’re not familiar with virtual functions, here’s a Unity Tutorial that talks about Polymorphism.

Initial FSM State Implementation

Let’s now start the FSMState and let’s call this FSMState.cs:

Now that we’ve started on everything, let’s finish up the FSM class.

Finishing FSM Implementation

Let’s add the ff variables in our class.

The name of course will be the name of the FSM. The stateMap will contain a key which will be the event id of the FSMState, and the FSMState itself so that we could bind them together, and transition to another state via SendEvent() function.

Of course the name of the FSM.

We will create an action processor. This will enable us to dynamically call different actions that is inside the state, and do the action. If you’re not familiar with delegates, refer to this.

Let’s now fill up the constructor that we did before and make an initializer for our FSM.

Constructors as you know, makes creating instances of classes easier and much more clean, and less coupled since the variables of this class are set to private. Keeping unnecessary variables unseen for the other programmers.

We will now add a FSMState parameter to ChangeToState(), EnterState(), and ExitState()

Now it’s important to check the states to avoid jumbling them and avoid errors.

Enter, Exit, and Update will be the same and will be handled by our action processor.

Finishing FSM State Implementation

Now that we’ve created our loop. Let’s start writing our FSMState. First its constructor.

Before we go any further, let’s talk about transitions. Transitions by its name, is the change between two states. We’ll use a string to act as a key to change between states. All of these are contained in a dictionary.

Now let’s make a function that adds actions to our state.

Let’s now add the event handlers for the FSM, and the FSMState. Let’s first go back to the FSM.cs and add new functions to the class.

Let’s finalize the FSMState by adding implementations for event handling.

Lastly, let’s create a function that will automatically create states for us under FSM.cs.

By calling this function, this will enable us to create States without creating on the AI class itself.

So there you have it. Our FSM system is now done. Look out for our next Blog tutorial for the implementation. Please do comment if you have questions regarding this topic.

On the next and final part of this tutorial, we will make two kinds of implementations for this FSM engine that we made. We will create one AI class that will write to our console indefinitely, and another AI that will move AND write to our console indefinitely.