Debugging Web Services With Fiddler In Unity

In order to empower your Unity game with useful features like user accounts, leaderboards, achievements, and cloud saves, you are going to need a web service. Of course, you wouldn’t write one on your own, so most probably you’re thinking of using services like GameSparks or App42. If so, you should learn how to debug it.

Having a REST

If you’re not familiar with what REST is, then it’s the best time to acquire new knowledge. It’s not difficult and no, it’s not another language. It’s just an architecture, a set of rules to follow to make a good API. Thanks to REST all API services look very familiar and are easy to learn. Here’s a good place to start.

Now, when you know that REST calls are nothing else but regular HTTP requests, you may find monitoring all the http traffic between your game and web service as very useful. You may want to do this because:

  • This may be the only way to see the client-server communication
  • Client request may not be what you’ve expected it to be
  • Server response may tell you about other things than client library errors
  • Client library may have bugs that can be revealed in this way

Let’s be honest, you will encounter issues. How fast you will deal with them depends on your debugging skills. If there’s a possibility to peek into client-server communication, why you not just do it?

Wireshark?

wireshark

Most people when asked about looking into client-server communication think about Wireshark. It’s the easiest way to get hands on the full communication and while Wireshark does his job very well, I’d like to recommend something else for debugging.

Fiddler!

fiddler

Telerik Fiddler is available for free for Windows and at the time of writing of this article there’s also OS X beta version available.

What makes Fiddler so special? Especially the fact that it debugs your http traffic using build-in tools so easily. It also has a very simple user interface that is easy to understand and use. Requests and responses can be displayed as a raw text or formatted one as JSON or XML if you expect this kind of data to be in there. On top of that you can customize the requests/responses view to see the data that you’re concerned of and you do this without any trouble.

Fiddler inspectors makes debugging experience really pleasant.

Fiddler inspectors makes debugging experience really pleasant.

Do not confuse Fiddler with the packet sniffer. It does not listen to your web interface, instead it installs itself as a default system proxy. It has its pros and cons. By doing that, it can easily decrypt HTTPS communication (yeah!), but on the other side not all applications accept the default system http proxy settings.  One of these applications is…

Unity

Of course by “Unity” I also mean all apps running on Unity engine. I cannot tell for sure why Unity does not work well with Fiddler, but I know how to make it work with it. There’s a great blog post about it written by Bret Bentzinger. The steps go as follows:

Windows

  1. Make sure Unity is not running
  2. Navigate to UNITY_INSTALL_DIR\Editor\Data\Mono\etc\mono\2.0
  3. Edit machine.config file and inside <system.net> add the following:

OS X

  1. Make sure Unity is not running
  2. Locate the Unity application icon
  3. Right-click on it and choose “Show package contents”
  4. Navigate to Contents/Frameworks/mono/etc/mono/2.0
  5. Do step 3 from the Windows instructions

Important: Make sure to undo these changes after you’re done with debugging!

More about Fiddler

Did I help you make your mind? If yes, you might want to see some more learning resources about Fiddler.

Happy debugging!

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.

How to create cheat codes for games in Unity

How to Implement a Game Cheats Subsystem Within Unity3D

When you’re creating a game, you have to play it again and again, repeat some scenarios or create new ones. Also, you have to do it fast, because if any kind of scenario requires from you playing your game or any level from the beginning just to get the desired result, you’re wasting your time doing so. To solve that issue, you should cheat. In a positive way of course! And to do that, you need a game cheats subsystem.

In-game cheats are very old aspect of many games out there on the market. These exist to help developers and testers to test the game and are left in the final production mostly because they can add value to the game. Removing already implemented cheats may compromise the product stability, because this requires another change in the code. There are also some cheats that were implemented as Easter eggs! The best known cheat code that is used as an Easter egg is the Konami Code. You can activate this one even on some websites!

konami code

Konami Code

Usually you won’t find out how to use cheats in the game’s manual, because the game authors don’t want you to play using the cheats from the very beginning. Yet you can find cheat codes in the paper magazines or on the Internet.

Implementing game cheats subsystem

Here we will talk about how to implement easy game cheats subsystem that will work on PC and mobile devices. The main requirement is that it should work without using a keyboard. We will treat touch and mouse inputs as equal to make things simpler. Then we have to create any type of GUI. For this task we will use old, but still usable IMGUI. So, let’s start!

Activating cheat codes list

Let’s make it easy to activate the cheat codes list, but not as something that can be done by accident. The list should be activated if you touch/click top-right screen corner 5 times within 2 seconds.

I know that this is quite a lot, but this is the basic implementation. It will:

  1. Listen for all clicks and touches
  2. Check if a click/touch has been done within the desired screen area.
  3. Check if last 5 clicks have been done within the desired timespan.

And it is configurable! Yet what is missing here, is the GUI code and the cheat activation code.

Now this is really simple. Game cheats are displayed as clickable buttons. If the button is pressed, the callback delegate is executed. The first cheat is a “cheat” that will close the game cheats list. Now, if you click 5 times in the top-right corner, the cheat list will become visible.

game cheats list

And if you were wondering if it works… 🙂

inverse gravity cheat

The package

Feel free to download, and use however you want, the package that includes the script from above and a test scene. The package has been prepared with Unity 5.3.0, so please be sure to import it using the mentioned Unity version or a newer one.

A Story of NullReferenceException [Part 2]

This is a story of NullReferenceException part 2. If you haven’t read the part one, you can still do it here.

Don’t trust GetComponent()

GetComponent() is a commonly used function to access current GameObject’s component. Here’s a code snippet showing how to disable object’s renderer, so it is no longer visible in the game view.

Of course GetComponent() will return null if current object doesn’t have the requested component.  That is a serious risk, because components can be easily removed by the designer at any time without any warning.

Use [RequireComponent]

First you should use [RequireComponent] annotation whenever it is possible.

Note that [RequireComponent] will not guarantee that given component is always available. What it actually does, is adding missing component during object setup. Nothing fancy, but it lowers the risk of NullReferenceException a little.

Decide what to do on failure

Yes, you definitely should do a null check. But you have to decide what you want to do if the component happens to be missing. You have three options in general.

  1. Display an error and ignore.
  2. Report the incident as bug.
  3. Try to recover.

As you can see there’s no option for throwing an exception. That’s because we want our game to be as stable as possible.

1. Display an error and ignore

This is the easiest way to handle these kind of bugs. If you encounter them when working in Unity Editor then you will have a good opportunity to fix it before it is even released. Yet your situation will not be that comfortable if this issue appears on your player’s devices that usually you don’t have direct access to.

Please note that on line 7 I wrote if (renderer) instead of if (renderer != null). That’s because the UnityEngine.Object is overriding the (bool) operator and under the hood this is a nice shortcut to do a null check.

2. Report incident as bug

If you have the opportunity, you may want to report this incident as a bug. Automatic bug reporting helps you to fix bugs in production, so you should seriously consider this kind of implementation. Of course you have to ask your player for a permission to send a bug report, because otherwise it may violate the agreement with Google Play or App Store and as a result your application may get banned.

I am personally using a script called SRDebugger from the Asset Store. It allows to display an overlay form that enables sending a bug report to my e-mail address.

Alternatives:

3. Try to recover

This is the third option and the only one that allows your game to work properly. I believe it should never be used, because if there’s a smoke then there’s a fire. Recovering is only hiding the smoke while you should start looking for the fire.

Assert GetComponent()

Remember that you should look for any issues as soon as possible. If your script is using a component sometime in the future, make sure to check at the beginning if this component is available.

Watch out for callbacks!

If your game includes callbacks that are called from external code and/or from another thread you may find yourself in a situation, when NullReferenceException is thrown out of nowhere. It can happen with Social API when callback may be invoked seconds after making a request. And at that time the object that made a request may… no longer exist.

OK, that’s not really true, but we can run into fake null issue here that we were talking about before. Let’s consider a scenario like this:

  1. Results scene is loaded.
  2. ResultsScreen script is requesting Social API for current player’s score.
  3. The player clicks on “main menu” button.
  4. Results scene is unloaded.
  5. Main menu scene is loaded.
  6. Social API callback is being invoked inside ResultsScreen script.

So if Results scene is unloaded, all of its objects should be destroyed at the time of executing sixth step. That’s not true, because the reference to ResultsScreen object is still valid and object exists, but it reports itself as null by faking its own null check as I explained in the previous article. It may look like this:

Can you guess where you will receive a NullReferenceException? On line 10 and it really doesn’t matter if ScoreLabel has been assigned or not. You won’t be able to access it at this point.

How to protect yourself from this kind of situations? The answer is strange but simple. You should do a null-check of this.

Yes, that’s right! Current object won’t be null because it simply cannot be, but since Unity is faking null checks, this is the best way to check if the current object can be still used!

Of course you can null-check all your objects that you’re about to use, but in more complicated scenarios this may be simply too much. Checking this for null should be good enough.

Keep calm and singletons

Singletons are often perceived as anti-pattern. Still singletons are widely used because of the simplicity and ease of implementation.

In the Unity most common type of singletons are:

  1. Singletons created on demand
  2. Singletons created by the engine (derived from MonoBehaviour)

Let’s look at the second type of singleton.

First, you should make sure that singleton Instance field is assigned as soon as possible, so I’m assigning it in Awake() method. But that’s not enough. There’s a serious risk that Awake() will not be called even once. This risk is caused by the assumption that Singleton object exists on the scene.

Knowing that, you have to create an assert in each class, where you intend to use this singleton:

Note that I’m assigning a singleton in Awake() function, but I’m testing it for null in Start() function instead of OnEnable() function.

That’s because Awake() and OnEnable() functions are called one after another for every enabled GameObject. It’s not explained too well in the official documentation, so I will try to clarify that.

There are scripts: ScriptA and ScriptB both with Awake(), OnEnable(), and Start() functions. The call order may look like this:

  1. ScriptA: Awake()
  2. ScriptA: OnEnable()
  3. ScriptB: Awake()
  4. ScriptB: OnEnable()
  5. ScriptA: Start()
  6. ScriptB: Start()

So as you can see, you cannot be sure that when you’re in OnEnable() that all singletons are assigned. The risk is even greater that sometimes singleton may be assigned, and sometimes not!

You can force your script to be initialized before anything else using Script Execution Order, but to be completely safe, don’t use singletons in Awake() and OnEnable().

Suggestions?

Do you have any other interesting suggestions on how to make your project robust by securing your code against NullReferenceExceptions? Please share your suggestions using the comment form below! We will appreciate it!

A Story of NullReferenceException [Part 1]

Once upon a time there was a little boy living with his mother alone between the mountains. They lived a peaceful life. One day the boy’s mother got very sick. The boy called for a doctor, the best in the valley. When the doctor finally came, he examined the woman. Unfortunately, there was only one medicine for her illness and this medicine was very hard to get. The only known location was far away from there, on very dangerous lands, full of traps and monsters. Without thinking too much, the boy took his wooden sword, backpack and he went on a trip where… NullReferenceException.

NullReferenceException

If there’s one thing that is common for most of Unity games, this thing is NullReferenceException. This little fella can be quite a nuisance, especially on mobile platform, where you most probably want to have a script call optimization set to Fast But No Exceptions. That’s because any exception will cause your application crash immediately. Is this worth the risk? It depends on the time your game requires to execute all the scripts in each frame.  The more time it needs, the more you will benefit from enabling the optimization.

What NullReferenceException is?

Before killing the dragon, we must fight the dragon. Before fighting the dragon, I would say that we have to get to know the dragon. NullReferenceException is so common issue, that is has its own Unity documentation page! But let’s compare it with official .NET documentation definition.

Official:

In this article we will talk about techniques that will help you minimize NullReferenceException occurrence possibility.

Unity:

A NullReferenceException happens when you try to access a reference variable that isn’t referencing any object. If a reference variable isn’t referencing an object, then it’ll be treated as null.

So this means that if you have a reference (field or variable) that is not pointing to any object (is null) and you try to access it (access parameter, field, or execute a method of this non-existing object), then you will receive a NullReferenceException.

But… there’s one subtle, yet important, difference with NullReferenceException when working with Unity objects. Normally, you may do a check if an object is null before trying to do anything with it:

But Unity objects are a bit different. Unity objects can report themselves as null even if they are still referencing an object!

No, that’s not a bug! Some referenced objects are scene objects. Imagine what happens if a scene is being replaced by another scene – all regular scene objects have to be destroyed. Since Unity cannot update your valid references inside your code (they still will be valid after destroying the scene), it is faking a null check for those that you are still referring to, so it will (should) stop you from use these any longer. In case you do try to use any of these objects, you may receive a message like this one:

reference object destroyed

It is also an exception that will crash your app, so be warned!

Fail Fast

The worst and yet the most common case of NullReferenceException is when your component expects some other objects to be passed into it through the inspector, but for some reason somebody didn’t do it.

The example above is a simplified situation when you want to display a label when player touches the star. Collider other is guaranteed to be a valid reference (based on documentation), but what we cannot be sure about, is the scoreText field that should be visible in the inspector. What if somebody forgets to assign it? You will know about it only after trying to touch the star. That’s definitely too late!

We can handle these kind of situation using Asserts (we talked about asserts before). Asserts will tell us if something is wrong, and it’s a wise choice if all the checks can be done right after the scene is launched. Let’s try to add an assert like this:

This code will yield an error right after the scene is started. We no longer have to wait for the player to touch the star. That way we can check if everything is OK with the scene just by launching it!

Do I have to add an assert for each inspector object? Yes! You cannot trust that someone  doesn’t break your scene references.

Public field is not bulletproof

Have you noticed that public fields can be accessed from any place? Yep, this can be bad. This means that any other script may get to it and set it to whatever it wants to. Assert won’t help us if other script will decide to replace our reference in the middle of playing the game.

To make it a little more bulletproof, we can make it private. Private fields can be displayed and assigned within the inspector, but a field like that needs a [SerializeField] annotation:

Now, the field cannot be accessed outside the current object what makes the risk of unexpected NullReferenceException significantly lower.

To be continued…

You can read the second part of this article here.