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).


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!

5 thoughts on “Unity 5.1 Assertion Library

  1. Hello there! Thanks for taking the time to write so interesting article! Great for new programmers 🙂

    What I usually do is something like this:
    if (someObject == null){
    // try to find the object
    someObject = GetComponent();
    // if there is only one in the scene. eg game controller
    someObject = GameObject.FindObjectOfType();

    In this way you are safe and after this you can also put the Assert! 😀

  2. Nice read, but I’d like to mention few additional things:

    You may use Asserts not only through the Assert class
    but also you may use the generic extension methods:
    airport.MustNotBeNull(“Something is wrong!”);

    They are described here:

    Another point – if you’re using debugger, exceptions will be thrown anyways to break the execution and invoke debugging, even if you have the raiseExceptions set to false.

    P.S. You may use the Maintainer asset to scan your projects for potential issues like links to the missing objects and such.

  3. Frank says:

    Great article though I have been trying to use Assert with a GameObject (instead of Airport) and cannot get it to work. I simply cannot get an exception thrown whatever I put in the inspector i.e. leave it at “None” or if I populate it with a GameObject.
    Am I missing something or this doesn’t work with GameObject?
    I even tried Assert.IsFalse(airport!= null) to no luck.

Leave a Reply

Your email address will not be published. Required fields are marked *