How to Use Unity’s Resources Folder

Unity has several kinds of special folders. One of them is the Resources folder. Simple concept of storing assets is well-explained in the official documentation:

Generally, you create instances of assets in a scene to use them in gameplay but Unity also lets you load assets on demand from a script. You do this by placing the assets in a folder called Resources or a sub-folder (you can actually have any number of Resources folders and place them anywhere in the project). These assets can then be loaded using the Resources.Load function.

Still the reason why we might want to use the Resources folder may be a little confusing. First you have to understand how Unity build process is works and how Unity is able to access game assets.

Unity build process

Before you will build your game, you have to declare what scenes your game consists of. All of this can be done in Build Settings window.

build settings window

There are at least two reasons why Unity asks you to do this:

  • It needs to know what scene should be loaded first (the top scene)
  • It needs to know what assets should be included in your build (dependencies)

What are scene dependencies? They’re assets which are connected to the scene hierarchy in any way, usually as a component field.

Unity Logo object contains Sprite Renderer object that references Unity Logo asset.

Unity Logo object contains Sprite Renderer object that references Unity Logo asset.

The dependency diagram may look like this:

dependency diagram 1

In this case there are two scenes. Scene 1 is using Asset 1 and Asset 2. Scene 2 is using Asset 2 and Asset 3. What happens if you decide not to build Scene 2?

dependency diagram 2

Only Asset 1 and Asset 2 will be included in the build since Asset 3 is referenced only by Scene 2, that is no longer included in the build. Thanks to this dependency tracking Unity will include in your build only these assets, which are actually used. Needless to say that you don’t have to worry about storing assets you’re not using at the moment. It will not affect your build size in any way.

Override!

There’s a way to get around this process. If you put your assets into a Resources folder, they will be always included in your build. But be careful! You need a really good reason to do so!

As I said before, in most cases when you need to use an asset, you make a reference to it within a scene. It’s really easy to use any kind of attached asset this way. So why would you need to use an asset without keeping a reference to it? There may be several reasons and each one depends on specific needs of the, but let’s look at one case what is quite common for most games.

When an asset is directly referenced from the scene, it will be loaded into the memory before your scene will be launched. Thankfully to that, player will not experience any frame-drops related to assets loading (with small exceptions). The price is of course the time needed for these assets to be loaded. Sometimes it may be not acceptable.

Example – loading screen with different backgrounds

Many game loading screens are displaying random images to be less boring.

Many game loading screens are displaying random images to be less boring.

Loading screen is something that usually is also a scene. Let’s think of a case when you want to display a random image on the background while your actual game level is loading. You’ve collected 15 images and you add these to loading scene images rotation script. It is working great, but when you play your game you realize that your loading scene requires more time to load than you need to pass your actual game levels!

This is caused by assets pre-loading mechanism and can be easily fixed using Resources folder. First remove all the references to your textures from the scene. Then put your images into Resources/LoadingImages directory like this:

resources images

Then somewhere in the code you can use a code like this one:

Note that Random.Range() returns a random number between first argument inclusive and second argument exclusive, that’s why there’s +1.

If you will need to attach this texture to an Image component, you can do it like this:

A word of caution

Use Resources folder only when you really need to. Loading assets on demand will make your FPS rate drop, and having indirect dependencies is makes your work much more difficult.  It’s worth to mention again that these assets will always be included in your build, even if you don’t use them. You have been warned!

How to Use Multiple Cameras in Unity3D

Understanding the Importance of Using Multiple Cameras in Unity

From what I observe, many Unity users do not grasp the concept of using multiple Unity cameras on a single scene. “If I want to look from only one perspective, why do I need more than one camera?”. Saying that it makes perfect sense when more than one camera captures the scene from the same perspective makes it even more confusing. So why even bother? The reason is somewhat complex, but it’s really worth learning. It will help you create great visual effects, that are hard to accomplish with the use of only one camera, in an easy way.

What is the Unity camera?

Before we can continue, you have to understand what Unity Camera actually is. When Unity renders the scene it needs much of important information to be set up, but let’s simplify that list to make it easier to understand. Let’s consider:

  • List of objects to render
  • Camera’s perspective (position, rotation, scale, field of view, clipping etc.)

If you’re already experienced in that matter you might’ve noticed that I’m not speaking about matrices. Let’s just ignore math-related stuff for now.

List of objects to render is a list of all objects on the scene, right? Wrong! Each camera renders only the objects visible to it (field of view, frustum culling) and those on the layer which actually seen by the camera (Culling Mask.)

camera culling mask

Culling Mask can be set to Everything, or you may set which of the layers should be seen. This is one thing what layers are for.

This camera sees everything.

This camera sees only the Default layer (ground) and the Red layer (red sphere).

This camera sees only the Default layer (ground) and the Red layer (red sphere).

The conclusion is that different cameras can render different objects. This is important information even if you don’t know yet how to use it in practice. It also means that adding second camera will not re-draw your scene two times. Only objects visible to the second camera will be rendered. Knowing this having multiple cameras rendering different layers will result in similar efficiency as rendering all these layers using only one camera.

Let’s then answer the main question: Camera is an instruction to render specific list of objects from given perspective.

What do cameras render?

Wait, haven’t we just answered that question?! Well… not exactly. There’s a visible and an invisible part. What you can see is a result image (let’s call it color buffer). And of course there’s a thing that you cannot see. This thing is called a depth buffer (called also z-buffer).

Depth buffer can be easily described as a game screen sized gray-scale image, every pixel of which represents how close that pixel is to the camera (to be honest this is not 100% true but let’s not think of more complicated cases now.) It is used by the GPU to decide whether to-be-rendered pixel should be processed or rejected from rendering. As a result, pixels that are obstructed by other pixels are not going to be visible (just like in the real world.)

depth buffer

Camera order and clearing

Before rendering anything into color buffer and depth buffer, camera can clear both buffers or only the depth buffer. Did you notice that the default Unity 5 scene camera clears buffers to Skybox?

clear flags skybox

There are some more options there:

cb969ef8-2866-4689-9026-e95e0c8c39f2

  • Skybox replaces color buffer with your skybox and completely clear depth buffer
  • Solid color does the same, but color buffer becomes solid color
  • Depth only leaves color buffer at is, but your depth buffer becomes clear
  • Don’t Clear doesn’t clear anything.

What will happen if we will try to set the default camera Clear Flags to Don’t Clear? Well, the effect may be interesting (I moved the camera a little after entering the Play mode).

camera don't clear

It looks like our sphere duplicated itself so many times, that it turned into some kind of wired, rounded pipes thing. Besides that there’s still one red sphere on the scene (note that Blue layer is still not visible to the camera), the game scene image looks valid. There are no graphical artifacts of any kind. Yet we managed to create an effect of many duplicated objects with only one object.

This happened because color buffer was not cleared between frames (colors rendered previously were transferred to the next frame), also the depth buffer. Depth buffer remembered that something has been rendered and it was keeping this information when Unity tried to render another frame. When sphere was about to be rendered behind already rendered sphere image, invisible pixels were discarded. The same thing applies when there are many objects on the scene rendering one after another.

If you still don’t understand what just happened, please stop reading now and try doing it yourself! Make a new scene, add an object, set camera Clear Flags to Don’t Clear and move either your object or your camera.

What is it good for?

I assume that you don’t want this kind of effect in your game, so what’s the clearing good for? Let’s now try to create two cameras.

  • Blue Camera
    • Clear Flags: Skybox
    • Culling Mask: Default, Blue
    • Depth: 0
What Blue Camera sees.

What Blue Camera sees.

  • Red Camera
    • Clear Flags: Don’t Clear
    • Culling Mask: Red
    • Depth: 1
What Red Camera sees.

What Red Camera sees.

There’s one new parameter: Depth. Depth defines the order of rendering of the cameras. Camera with lower depth will be rendered before the camera with a higher depth.

Let’s see how Unity will render this scene step by step (again not 100% accurate, but it’s only to understand the process):

  • (Blue Camera context)
  • Color buffer is cleared to Skybox
  • Depth buffer is cleared
  • Plane (Default layer) and blue sphere (Blue layer) are rendered
  • (Rex Camera context)
  • Nothing is cleared
  • Red sphere (Red layer) is rendered

As the result you get a scene that looks exactly like rendered using a single camera:

a5d5727e-b210-41a1-b6c8-7e28373c5a02

So why bother? Let’s try one thing. Let’s switch Red Camera Clear Flags from Don’t Clear to Depth only:

depth only clear

Whoa, do you see that? Since depth buffer has been cleared, the red sphere doesn’t know that its pixels are obstructed, so it’s rendering like there’s nothing on the scene. That means that clearing the depth buffer brings rendered objects to the front. This may be super-useful when you’d like to render 3D UI elements.

In Skyrim you can see inventory items as 3D objects. These are rendered correctly even if background object appears closer to the camera.

In Skyrim you can see inventory items as 3D objects. These are rendered correctly even if background object appears closer to the camera.

Another interesting option is applying camera effects only to specific layers. Let’s try to apply blur to the Blue Camera, just like on the screenshot below:

camera blur effect

Let’s now switch  Red Camera Clear Flags back to Don’t Clear and apply a different effect to the Blue Camera: Grayscale.

5e5efe4a-6ae5-4877-8027-0969ccc1b002

Finally, keep in mind that if you want to move the camera, you may want to move all cameras at once (that’s why keeping all the cameras as a child of one game object is quite common.) But moving only one camera may be somewhat desired…

moving two cameras

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.

Mobile Optimization – Garbage Collector

What is the Garbage Collector? Let’s look at a definition on MSDN:

The .NET Framework’s garbage collector manages the allocation and release of memory for your application. Each time you create a new object, the common language runtime allocates memory for the object from the managed heap. As long as address space is available in the managed heap, the runtime continues to allocate space for new objects. However, memory is not infinite. Eventually the garbage collector must perform a collection in order to free some memory. […]

If C# or JavaScript is your first (and only) programming language then most probably you are not aware of how difficult is to manage application memory. In languages like C/C++ you have to decide when memory is allocated and when it is freed. Make one mistake, and you will either have a memory leak or your application will crash in an instant.

Of course if something is difficult to manage then it requires time to think about it. Now, we live in the world where we want to release our products to the market as soon as possible, so we’re trying to find a way to make everything as simple as possible. One of these things is allowing garbage collector to take care of freeing the memory.

Sounds great, doesn’t it? Yeah, garbage collection is a real life saver, but it has a downside too. Garbage collector runs from time to time and it requires your application to freeze for the time being (There’s a garbage collector mode that allows to run without freezing the app, but you’re not allowed to tune the Unity garbage collector settings.) and you have little control when the garbage collection should be launched. This is not an issue for a business application where the interface usually static, but may be an issue for a game where even a short pause can cause the player to loose the game. And what players hate the most is losing when it’s not their fault…

Garbage collector and games

Last time we talked a little about Unity profiler and garbage collection.  The rule is simple – we don’t want the garbage collector to start its job. To do so, we have to stop generating garbage. Of course it’s impossible not to generate garbage at all, but we can significantly reduce amount of generated garbage, so garbage collector will run once per ten minutes instead of once per ten seconds.

Using Pools

One of techniques to minimize the garbage is to reuse existing objects instead of creating new. This technique is called object pooling and we talked about it last time. In most cases you will benefit the most by using this technique, so this should be the first thing you should take care of.

There’s a great free library that you can use to build your own pools. It’s called Smooth.Foundations and it is available on the Asset Store. Unfortunately the website with its documentation is down, but the code is really simple to understand. Here’s an example pool that creates a pool of GameObjects with SpriteRenderer component.

From line 6 to 10 we create a delegate that defines how pool object should be created. From line 11 to 15 there’s code responsible for resetting the object to its original state (after releasing it).

Then the pool can be used this way:

Using Arrays

You may use arrays, but remember not to allocate these during the runtime. If any function needs to return an array of values, use an existing array and pass it as an argument.

Usual approach

GC-friendly approach

As you may have noticed, using gc-friendly code requires some more effort. First, you have to know the upper limit (in this case 32). You have to be sure that this limit is not exceeded, because your game will crash. Then if you want to iterate through these items, you have to use the size value instead of the size of an array.

Note that I used the ref keyword here. Ref means that this value should be passed by reference but since arrays are always passed by reference, it is not required in this case. The only reason it was used, was to increase the readability of GetNumbers() method call. If you see a ref then you know that something will get out that function using the passed parameter.

Using Lists

Using arrays directly may be not the best choice. Instead, you can use a List. The List in fact is an Array wrapped by a quite useful handling code, that guarantees you safety and you don’t need to worry about array sizes to much (and some other things too).

Yet you have to be careful. If you exceed the List array size, it will allocate a new bigger array. Since we want to minimize the number of allocations, always create lists using constructor that takes the capacity:

What about iterating through a list? You may know that or not, but Mono compiler that comes with Unity (Current Unity version at the time of writing this article is 5.2.3) has a bug that allocates memory when using foreach loop on collections. It’s not much because it is “only” 24 bytes, but executed many times will quickly exhaust your memory and trigger garbage collection. Instead, use for loop whenever possible.

Here’s an example code. Note that this time we don’t need a size variable.

Consolidating strings

There are some things that you simply cannot get around. One of those things is consolidating strings. When done, it will always allocate a new string. You can optimize this process a little by using StringBuilder instead of the add (+) operator.

The add (+) operator approach:

The StringBuilder approach:

Have you noticed that I used a using instruction to get a Disposable object from the pool? This is another method to use the pools. It’s much safer, because you won’t forget to take the borrowed object back.

Is that everything?

Of course it isn’t! One note though. Please, keep in mind that running your code in Unity editor will generate more garbage than running it on the target device. You may find yourself in a situation when you try to optimize the garbage when it is not generated at all on the target device. This is because the Unity does some nice optimizations when your game is build, and you always should run the profiler on already built game to know what should be optimized and what not.

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.