What I have learned while developing a game launcher in Unity

This post can be considered partially outdated, since my mind changed quite a bit since when I originally wrote it.
First of all, I would never suggest to write a game launcher in Unity now. Use instead .net or the latest version of mono with xamarin. Mono library embedded with Unity 4 is too outdated and its use results in several problems when using advanced HTTP functions. However, if you decide to use .net, please be aware that your installer must be able to download and install .net from the internet if it is not installed on the machine already. It is also possible to embed mono, more or less like Unity does, but it is quite tricky under Windows.
We also changed our mind about the admin rights. Many of our users use Windows without admin rights, so we wanted our launcher to never ask for any.
I also think Unity now fixed the check of the SSL certificates, but I am not 100% sure about it.
At last, I would search around for libraries that can generate diff patches of binary files, since hashing and downloading files one by one is neither convenient nor efficient.

In case you didn’t know yet, it has been already a while since I co-founded a company called Freejam, in the UK, and started to work on a new game named Robocraft (http://robocraftgame.com). For this indie product we are extensively adopting the Lean startup approach even for the development cycles, so features come as they are actually requested by our early adopters.

Last feature our early adopters were eager to see was a proper game launcher. A game launcher is basically a must for every online game, since, as you all know, in this way is possible to patch and update the game without being forced to install it over and over.

I never implemented a launcher before, so I was completely ignorant about some tricky issues that could arise and their relative workarounds, which I now want to share with you to avoid wasting days trying to solve similar problems.

I started to develop the launcher in Unity just because it needed a graphical interface and I did not want to spend time learning/using new libraries for other development platforms (either c++ or pure c#). Size wise, considering that Unity applications embed the mono libraries and runtimes, the resulting compressed 6MB installer wasn’t too bad.

The graphic interface has been easily developed with NGUI and the information shown are a mix of rss news taken directly from the game blog and images configurable by the artists through an external xml.

The update process instead has been a little bit more convoluted, with a couple of unforeseen tedious obstacles that made my life a bit miserable for few days.

The update process is split into several predefined tasks:

  • check if the game is already running and ask to the user to close it before the update could be launched
  • check if another launcher is running and ask to close the other one
  • check if a new version of the patcher is available and in this case force to update the patcher
  • check if a new game build is available
  • download the list of files built together with the new game build. This list contains the name of the files, the size and a hash as checksum
  • download an asymmetric encrypted digital signature of the game
  • verify that the digital signature is valid using the public key embedded in the client
  • verify that all the files on the server are ready to be downloaded
  • verify which files on the hard disk must be updated, using file size and generated hash (comparing the value with the hash from the file list previously downloaded)
  • if it is needed, files are downloaded, uncompressed and saved (they are stored as gzip on the server)
  • delete obsolete files if there are any

On our side our Jenkins building machine handles two separate jobs (actually more, but I keep it simple for the sake of this article), one to build the patcher, generate a new patcher version and deploy it to the CDN and the other to build the game, generate a new game version, generate the files list with hashes, create the digital signature using the private key that only our building machine knows, compressing the files to upload and deploy everything to the CDN.

The whole development process has been long, but thanks to the .net framework relatively easy. Nevertheless there are two specific features I have to go into detail with, since they are very important to know and not so intuitive:

first one is the reason why I implemented an asymmetric encrypted digital signature verification. A launcher without this kind of protection is vulnerable to man in the middle attacks that could be shown under the form of DNS spoofing. When a hacker successfully spoof a dns node, simply creates a deviation of the normal TCP/IP routing that the client cannot recognize. In this way the client does not know that it is downloading files from unknown sources and since the game includes executables as well, it could be relatively easy for a hacker to attack a specific pool of users and let them download malicious files.

This is one of the reasons why HTTPS has been invented, however HTTPS is effective against this attack only if the client can verify the certificate provided by the HTTPS server (http://en.wikipedia.org/wiki/Public_key_certificate). With my surprise, I found out that while Unity supports HTTPS connections, it does not verify the SSL certificates at all; Therefore using HTTPS in Unity does not prevent Man In Middle Attacks. Luckily the implementation of a digital signature was already planned, so while I was disappointed of the Unity behaviour, we were already ready to face the issue.

Implementing a Digital Signature in C# and .net is very simple and a lot of code is already available around. Just look for RSACryptoServiceProvider on Google to know more.

Once all this stuff was implemented I thought I was finally done with the launcher, but a dark and vicious evil bugger was awaiting me behind the corner: the UAC implementation of Windows Vista+!

After I understood what the UAC implementation of windows actually does, I realized why most of the online games suggest to use the c:games folder to install the game instead of the standard c:Program Files. The Program Files folder is seen by modern windows operative system (excluding XP) as a protected folder and only administrators can write in it.

Our launcher is installed by Inno Setup, which asks to the user to run in administrative mode, so Inno Setup is able to write wherever the user wants the game to be installed in. However, once it is installed, the problems start.

At this point of the explanation, If the launcher is launched directly from Inno Setup, it inherits the administrative rights from the installer and then it is able to update the game folder under Program Files. However, once the launcher is started again by the user, it will not start as administrator, but as normal user changing the behaviour of the file writing.

This is when the things start to be idiotic. If a normal user application tries to write inside a folder under Program Files, the writing of the file does not fail as I initially expected. Instead Windows creates a Virtual Store folder under C:UsersusernameAppDataLocalVirtualStore that virtualises the game folder. The result is that all the files that the launcher tries to write under program files are actually stored in a specific and predefined folder in the virtual store.

Hence, First lesson is: if your Unity application needs to write new files, never write them in to the folder where the application has been installed. Use the application data folder instead! However this cannot be applied to a launcher, since the launcher must be able to update the game wherever the user decided to install it in.

First solution came to my mind was then to embed a manifest in the application to ask to vista to run the launcher in administrative mode. This is easier than it sounds, at least once I understood that a command line tool, that can be found inside the windows SDK, can do it. Once followed the instructions, every time the launcher starts, windows UAC prompts a message box to the user, asking if to give the administrative rights to the application or not.

If the user authorizes the application, the launcher will be able to update the game, otherwise it will throw an error.

However and unluckily, this was not the final solution. The tricky situation here is that the launcher must be able to launch the game as well, but a process launched by another process will inherit its rights. This means that the game launched by the launcher would start as administrator, while if the user decides to start the game on its own, without using the launcher, it runs in normal mode (if the user is not administrator or the UAC is fully enabled).

Launching the game in administrative mode can be a bad idea for several reasons, but the most annoying one is that the user is not used to authorize a game everytime it is launched, so we decided to get rid of this issue.

After some research and after I tried all the possible solutions I could find on google and stackoverflow, I realized that the only working one is to use a bootstrapper to launch the launcher.

The bootstrapper must be a tiny application that runs in normal mode and must be able to launch the launcher as administrator user. This is pretty straightforward since .net allows to raise the application rights (but never allows to downgrade :( ). Once the launcher does its dirty job, it will close itself and it will communicate to the bootstrapper that it is now time to launch the game. The bootstrapper is now able to launch the game as normal user, because the bootstrapper itself has not started with elevated rights.

This solution sounds convoluted, but it is actually quite commonly adopted. Of course I could not use unity to create the bootstrapper, since this must be just few hundred Kbytes. For this reason I downloaded xamarin and mono and I have to say I was quite impressed by it. I have been able to setup a project and run it in few minutes. The bootstrapper itself has been developed in few minutes as well. For this reason we were forced to create a very simple c++ application in order to be .net framework agnostic (that otherwise must be installed on the machine)

Hope all of this can help you one day!

What’s wrong with Unity SendMessage and BroadcastMessage and what to do about it

Unity 3D is a well designed tool, I can say that. It is clearly less painful to use than UDK, no matter what its limitations are. However, as I keep on saying, the c# framework is still full of bad design choices, probably unfortunate inheritances from unity script (why don’t they abolish it and just switch to c#?).

Emblematic example of these bad choices is the communication system built around SendMessage and BroadcastMessage. If you use them, you should just stop already!

In fact SendMessage and BroadcastMessage are so wrong mostly because they heavily rely on reflection to find the functions to call. This of course has a given impact on performance, but performance is not the issue here, the issue is instead related to the quality of the resulting code.

What can be so bad about it? First (and foremost) the use of  a string to recognize a function is way worse than using a string to recognize an Event. Just think about it: what happens if someone in the team decides to refactor the code where the calling function is defined and decides to rename the function or delete it?

I tell you what happens: the compiler will not warn the poor programmer of the mistake is doing and even worse, the code will just run as nothing happened. When the error will be found, it could be already too late.

Even worse is the fact that the calling function can be declared as private since the system uses reflection. You know what I usually do when I find a private function that is not used inside the declaring class? I just delete it, because the code is telling me: this function cannot be used outside this class and I am not using it, so why keep useless code?

Ok, in c# I mostly use delegate events, so I have to be honest, I basically do not use SendMessage, but I still find the BroadcastMessage useful when it is time to implement GUI widget communication.

Since GUIs are usually implemented in hierarchical way (i.e. if you use NGUI), being able to push a message down into a hierarchy could have several advantages, since it is basically not needed to know the target of the message. This is actually similar to Chain of Responsibility pattern.

For this reason I decided to implement a little framework to send a message through a GameObject hierarchy and it works like this:

If the root (or a parent) of the target that must be reached is known, you can use it to send a signal through the hierarchy in a top down fashion. All the nodes of the hierarchy will be searched until a compatible “listener” is found. The code is pretty trivial and, as my usual, relies on implementation of interfaces.

CubeAlone is a MonoBehaviour that is present in a GameObject that is outside the hierarchy to search. It could have been inside as well, but I will reserve this case for the next example.

Through the SignalChain object two events are sent to two different targets. I decided to do so to show you the flexibility of the interface. In fact it is possible to identify events using whatever kind of object, from a string to a more complicated type that could hold parameters.

In the hierarchy of the example that can be found at this address https://github.com/sebas77/SignalChain there are two targets listening the CubeAlone, these are the Sphere and the Cylinder.

In order to be recognized as listener, these two MonoBehaviour must implement a IChainListener interface:

and from the code it is pretty clear how it works. Should I add something? If leftmost cube is clicked, the Sphere and the Cylinder will change color.

Well, let’s see now the case when the dispatching event object is already in the hierarchy. In this case we could dispatch events in the hierarchy without knowing the root. However the root must be signed with IChainRoot interface:

and the dispatching event object can use the BubbleSignal object in this way:

 Try to click on the capsule now, the sphere will change again color but this time will be blue!

TaskRunner library and the SingleTask class

Along the classes of my Task Runner library, there is one called SingleTask, that is a simple implementation of an IEnumerator interface and accepts an IEnumerator as constructor parameter. I’d like to show you why I decided to introduce this class:

Sometime it’s needed to run asynchronous routines (yet single threaded) and wait for their execution before to let something else happen. For a long time I used to use events to solve these problems, but in c# and unity often it’s nicer to exploit the coroutine functionalities.

An example could be this:

The difference is subtle, yet crucial. If the first method is used, the DoSomethingAsynchronously does not wait for the function SomethingAsyncHappens to complete, but returns right after the yield. Instead with the use of the SingleTask class and the TaskRunner library, everything that is written after the yield will be executed only when the inner async routines are completed.

This means that the Debug.Log will output 0 in the first case and 100 in the second case.

How to compress and decompress binary streams in Unity

recently I needed to compress a binary stream that was getting to big to be serialized over internet. I could not find any way to compress files easily, so eventually I used a 3rd party library that works very well in Unity3D (web player included): SharpZipLib

I suppose the following code could be handy for someone:

 

 

 

Unity3D Task Runner Update: Pause and Resume Runner

soon or later I will implement a multithread job scheduler for my task runner library, but lately I spent few minutes to implement an idea I had in mind for long a time.

Being pretty sure that the core functionality of StartCoroutine is to iterate over a IEnumerator routine (although it actually does more), I decided to test the theory doing the same inside a FixedUpdate function. I decided to use a FixedUpdate over an Update just because I am not entirely sure if the polling frequency matters.

The main benefit of this approach is to be able to pause and resume the task sequencer, feature that recently I needed to support for the project I am working on.
The new RunManaged function supports enumerable routines and WWW, but does not support YieldInstruction yet.

The updated  code is available here: http://sebas77.github.com/TaskRunner/

Edit: A needed overhaul of the logic made me get rid of the Update and Fixed update approach, the new version now let pause routines managed through StartCoroutine. Simpler and more effective.

My First Flash Multiplayer Game with Photon Cloud

For a long time I wanted to make some experiments with Photon Network Engine at home.
During my professional experience, I worked on several multiplayer games, therefore I was pretty curious about it.

Exit Games provides two versions of Photon Network Engine: the traditional Photon Server edition and the new Photon Cloud edition.

Photon is a server-client network engine dedicated to game development and, while the marketing department pushes the Unity3D version a lot, it has got APIs for most of the most famous development platforms existent.

Compared to the competitors, Photon Server has the advantage to be written in c++ and therefore be fast; however the server version has the limitation to work on Windows platform only, which could honestly be a problem.

Surely I would have not bothered to install the server for a tutorial, but luckily Photon comes with an amazing Cloud version with a very smart pricing model, including a free version that supports up to 20 simultaneous connections, more than enough to create the first prototype of whatever game, or a tutorial ;)

Of course Photon Cloud comes with some limitations as well. While Photon Server allows the server logic to be extended, the cloud version does not let any kind of extension, forcing to use authoritative clients while the server becomes just a simple message router (and lobby manager).

Let’s start right away

First thing first: you need to create your development account; once done you can create immediately your first server application with very few straightforward steps.

With the app generated, you get also an unique App ID, which is the only information needed to link your application to the cloud server.

Now, before to start your first Photon project, download the Photon flash SDK, this includes all the client code you need to create your game.

As usual, I use flashdevelop as IDE, but you can do everything with your favorite one as well. Download my code from https://github.com/sebas77/PhotonDemo and open the file mmo.as3proj (although it is not a MMO :P).

The project needs to include the library PhotonCoreAS3.swc as well as the source folder photon_loadbalancing_lib from the Photon SDK, so verify that everything is set correctly.

The load balancing version of the Photon client is the modern superstructure created on top of the Photon Core and, even if you do not need load balancing, I strongly suggest to use it, since it abstracts the Photon API even more and make everything easier to use.

Note that the code I released with this tutorial is based on my Entity Framework, however I never published it and the version used is just a work in progress, so do not focus on it. I think using this framework helps to highlight just the multiplayer logic implemented if everything else is used as a black box.

The code folders structure includes the startup files, the bullet folder, the character folder and the photon folder (plus my framework code). The Photon folder includes all the files to customize the events needed to control the game. The code I used to start is the chat example included in the SDK.

Where everything starts from

Looking at the code you will notice that all the server logic starts from:

pay attention to the fact that while the game starts immediately, your avatar will not appear until the game is not connected to the server. This is the standard logic of a multiplayer game: the graphical representation of your character will appear on the screen only when the server-client communication is setup.

The ConnectToServer class contains the APPLICATIONID value that must be filled with your AppID previously generated before to execute the game.

The ConnectToServer class provides also a series of useful callbacks that can help having a better understanding of the network engine logic.

The first thing your application must do as client, is to connect to the master server. The connection flow starts with a CONNECTING_TO_MASTER event and the Photon Core handling of the server connection. If all the data entered so far is correct, in few (milli)seconds the client receives the answer from the server as a CONNECTED_TO_MASTER event.

Once connected to the server, our code sets, in a simple and naive way, the properties of our actor; in our demo the properties set are limited to the name of the actor only. The actorID will be automatically set successively, but be aware of the fact that the actorID, unique for each player, is fundamental for every operation I will show you next.

Once the connection has been authorized, the client automatically connects to the lobby (all these operations are done “behind the scene”, so you relatively need to worry about it). The Lobby is a special “room” that contains the list of all the active games available.

A Game must be seen like a “chat” room where users connect to and exchange messages in.

the Photon flows continues retrieving the games list from the server, this is when our class ConnectToServer must decide again what to do:
If the list of games is empty, our client will create a new game; if the list is not empty, it will simply join the existing game. So, in total, our demo will never have more than one active Game running.

Even though I do not use special features for this demo, you will find out with your experiments that each game, as well as each actor, can come with special properties that can be set and broadcasted to all the clients.

Left the Lobby and Joined our Game, finally the flow reaches the event we care most, that is the LoadBalancedJoinEvent, but before to continue, let’s take a step back for a moment.

Getting deeper into the code

I explained what happens just calling server.connect(), but now that the user joined the room it’s our turn to act.

An important class used to listen to the network events is the LoadBalancedPeer that I extended in our demo and called PhotonPeer. For convenience, it is used as Singleton, however as you know, I am not a fan of this pattern and in fact the use of this singleton makes some part of my code awkward, but this is not a big issue for this tutorial purposes (beside, LoadBalancePeer has been designed as a Singleton).

PhotonPeer is used both to listen and dispatch data throughout the demo code. The classes that use it are:

  • ActorSpawner, used to create and destroy avatars
  • BulletSpawners, used to create and destroy bullets
  • CharacterEngine, used to manage avatars
  • BulletEngine, used to manage bullets

Let’s spawn this Actor

ActorSpawner listens to user joining and leaving games thanks to the following lines:

once a user joins a game, and I mean whatever user (so both the local player or a remote player), a new character Entity is created. However depending if the player who joined is the local player or a remote player, the code behaves differently creating a local or a remote character entity.

As previously mentioned, the ActorID is important because it is used to recognise if the joining user is the local user or a remote user thanks to the following code:

However, since a user can join after other users joined already, the code must be able to query the existing list of users and recreate them on the local client as well. This is done through this function:

That’s it, now the user avatar is shown and it’s time that the client can run all the game logic!

Character Movement

CharacterEngine is a System for my Entity Framework, as far as possible, let’s use it as a black box.

CharacterEngine both listens and dispatches custom remote data. The way I used to handle this data is exploiting the ActorEvent.TYPE event. Remember that our server does not have any logic, so all the custom events must come from another client. In order to dispatch a custom event, I used the function opRaiseEventWithCode like the following example:

The function needs the event ID (GameConstants.EV_SENDPOS) to recognise the type of data sent and a Dictionary with the data itself. For example, to send the character position and rotation, I use the following dictionary:

at the same time, to receive the same data from other players, the relative event is listened through this code:

CharacterEngine handles the death of the character in a similar way.

Bullet Shooting

BulletSpawner and BulletEngine logic follow the same principles. When a character “shoots” the GameConstants.EV_FIRED event is dispatched from one client and broadcasted to all the other ones through the server.

Homework: how to improve the demo

This little demo can be a start point to more interesting experiments, however I would start improving two issues:

  1. I sample the position update at 25 fps. Honestly the sampling can be less frequent if an interpolation method is used to avoid jittering, saving precious bandwidth
  2. as said the hit should be sent from the client that has been hit and not checked locally

In this game no client is authoritative, however only local clients can dispatch “death” as well as “shoot” events, since the remote clients cannot determine these events by themselves. This is not ideal since the local client should dispatch the “hit” state too, otherwise the hit count could be mismatched between the local and remote client.

Conclusion

With this demo I showed the basic concept of Photon Cloud. The client can connect to the server, then to a specific game. All the clients can receive and dispatch data through events. It is important to notice that the data can be handled differently depending if the sender is the local user or a remote user.

To conclude, two words about the Photon documentation: it is OK, but not great. However if you have any question, the photon forum is a great way to get answers quickly.

 

 

My version of the game can be played from here (use wasd + mouse, kinda fps style ;) )

And now good luck with the rest of your experiments!

 

On Commands and Events

Events and Commands are two object communication tools that I use really often. I have planned more exhaustive articles on the topic, but now I want to write a short post about one rule I apply when I use them.

Sometimes it occurs to me the question: should the listener class know the dispatcher  class or the dispatcher class know the listener class? (of course this is without the use of a Mediator)

Generally I answer in this way:

If I use event listeners, I inject the dispatcher inside the class which defines the method callback, ie:

In this way I do not need to expose the private members of the listener.

On the other way around, if I use the command pattern to achieve object communication (and I do it at lot), I usually invert the logic.

This because the Command Pattern add an extra layer of abstraction that does not let the dispatch and the listener know each other directly.

Using this rule I often end up with tidy code, so I hope it can help you as well.

IoC Container for Unity3D – part 2

In my previous article I briefly introduced the problems related to inject dependencies using Unity 3D Framework.
I did not give an in depth explanation because only who understood the problem on its own can really understand why to look for a solution.

Before to discuss the example I built on purpose to show the features of the framework, I want to share with you my experience with the IoC containers I used before to write mine.

As pure game developer, IoC container was a weird concept to me, although I probably used Inversion of Control without knowing what it was and what it was called.

My experience with other IoC containers

When I was introduced to the concept of Dependency Injection and all the problems related to it, the IoC container was among the most used solutions.
That’s why, when I shifted from traditional C++ programming to actionscript game development, I started to use Robotlegs. Robotlegs is an actionscript IoC Container.

After I used it for a couple of small personal projects, I decided to abandon it. This is because eventually I ended up convincing myself that manual Dependency Injection through setter and getters was a better practice.

However after some time, when I moved to C#, I started to experiment with Ninject and discuss the practices with its author.
As result of these discussions I realized that I was not appreciating the use of an IoC container because I did not understand its principles.

Composition Root

The most important concept to understand is the Composition Root. The Composition Root often coincide with the application entry point, but in practice it is the place where the IoC container must be initialized before everything else starts to use it. Since an application could use more IoC containers, it could have more composition roots as well.

Object Graph

When your classes design is created (without using singletons), your classes start to form a graph of dependencies. Let’s say that there is a class A and a class B, then there is a class C that uses A and a class D that uses B and C. This waterfall of dependencies is called Object Graph.

How to use an IoC Container

Now, as long as the objects do not need to be created after the application has been initialized, all the dependencies can be solved right at the begin of your application, within the Composition Root context.

This is very important to understand, in fact my first error was to inject the container itself inside the objects to be able to fill their dependencies that I used to create explicitly using the new keyword.

The rule instead is that the container should be explicitly used only in the Composition Root. Exceptions, most of the time, mean that there is something wrong in the design.

In our example the Composition Root looks like this:

container will not be used in any other part of the example, except for the factories. Factory is a special case and I will explain it later.

What is happening? Inside the SetupContainer method, we are not simply registering the classes into the container, but we are actually setting up the flow of our dependencies. Dependencies that are solved lazily (that means only when requested) through the metatag [IoC.Inject].

In our case, the application flow starts from this method:

After the MonsterSpawner is built, it will have the dependency IMonsterFactory injected because it has been declared like this:

[IoC.Inject] public IMonsterFactory monsterFactory  { set; private get; }

and because IMonsterFactory has been previously registered (and bound to a valid implementation) inside the container. In this specific case is simple to understand how the MonsterSpawner dependencies have been explicitly injected by the container. However the container will not be explicitly used anywhere else, so the other dependencies will be injected thanks to the Object Graph.

This means that monsterFactory on its turn will have (automatically) injected the dependencies:

[IoC.Inject] public IoC.IMonoBehaviourFactory monoBehaviourFactory { set; private get; }
[IoC.Inject] public IMonsterSystem                   monsterSystem             { set; private get; }

If monsterSystem had some dependencies too, they would have been injected as well and so on….

In a complicated project scenario this system eventually will give the impression that the [IoC.Inject] metatag becomes a sort of magic keyword that would solve all our dependencies.

Of course there is nothing of magic and, differently than Singleton containers, our dependencies will be correctly injected ONLY if they are part of the Object Graph.

The Object Graph itself is the main difference between the use of an IoC container and a Singleton container. The dependencies are not scattered without any condition among the classes, but they must follow the Object Graph flow.

If, using Singletons and Singleton containers, your code starts to feel like a game of Jinga, than it is probably the time to start to look at the Inversion Of Control solution.

IoC container and the keyword new

it is called Inversion Of Control because the principle is that the code should not use the keyword new at all. The control (of the creation of the objects) is not anymore on the user, but on the framework that will create and inject the objects for him.

The most powerful benefit behind this concept is that the code will not rely on the implementation of the classes anymore, but always on their abstractions (if interfaces are used).

Relying on the abstraction of the classes gives many benefits that can be fully understood when practices like refactoring and unit testing are heavily used. Regardless these concepts, coders should anyway use interfaces to create clean and well designed code.

all that said, one could ask: if I should not use new, how is it possible to create objects dynamically, while the application executes, like for example spawning objects in my world?

My answer is to use Factories. Factories, in my design, can use the container to inject the object that they create.

your class could have something like:

Beside, if you wonder why your class should not be able to create objects on its own, remember that this is not over engineering, this is separation of concerns.

Creating bullets and handle them are two different responsibilities and respecting the Interface Segregation Principle (part of the SOLID principles that should be your coding commandments) is one of the most important design rule in order to not have humongous and cluttered classes.

IoC container and Unity

The use of an IoC container, similar to the one I am showing in this article, will help to shift the coding paradigm from an intensive use of Monobehaviour to the use of normal classes that implement interfaces.

However Monobehaviour, on its pure form, is a totally useful tool and its use must be encouraged when appropriate. Still our Monobehaviours need dependencies that must be injected.
Now, if the Monobehaviours are created dynamically through factory, as it should happen most of the times, then the dependencies will be solved through the Object Graph.
However, if monobehaviour are created implicitly, their dependencies cannot be solved within the Composition Root because of the nature of the Unity Framework.

For instance, in my example, the turrets are not created dynamically (they could have been though), as well as the monsters counter shown on the top left corner.

There is no proper way to find a workaround to this limitation. My personal solution has been to create an extension method, called Inject, that can be used with Monobehaviour scripts.

the Monobehavior classes, created implicitly by the framework, that need dependency injected, use the extension in this way:

After this function is called, all the dependencies will be injected. There are conditions though:

  • The GameObject must be in a hierarchy where one of the parent GameObject has one valid UnityContext monobehaviour set.
  • The UnityContext must be initialized before the extension method is used. This can be achieved using Start or changing the Script Execution Order.

IoC Container and MVC (MVP, MVVM)

IoC container become also very useful when patterns like Model View Controller (or the more recent Model, View, Presenter and Model, View, ViewModel) are used.
Theoretically the triad should not be known outside the triad itself, since the way to communicate outside is to use services or command injected. The explanation of this case is not part of the scope of this article, so maybe I could write about it in another one.

However it is interesting to highlight how I also use these patterns to uncouple the data that we want to be edited through the editor and the logic that must use this data.

Usually what happens is that, just because we want to let the designer edit some public variables of a class, it becomes a Monobehaviour without any other reason. The way to get around this problem is to create a Monobehaviour that just handles this data and so become a sort of Model. This is what happens in our example with the PathModel class.

While you can change the way I exploited the idea in several ways, the main concept is that the monobehaviour is totally uncoupled from the logic (pathController) and it could even be destroyed since it is not needed for our purposes anymore.

IoC Container and Unit Tests

Often IoC container is associated to Unit Tests. However there is not any direct link between the two practices. In fact very often Unit Tests do not use IoC containers at all.
Instead the point is that the use of an IoC container, against the use of static classes, will help the coder to write Unit Test friendly classes.

In fact Unit tests must test ONLY the code of the testing class and NEVER its dependencies. Using Dependency Injection will make very simple to create dumb mockup to inject valid dependencies that cannot ever break or affect the tests of the main class itself. This can happen thanks to the use of interfaces, where the mockups become just one different (often empty) implementations used for the scope of the tests only.

Unit testing is also outside the scope of this article and maybe I will write one on purpose in future.

Conclusion

before to conclude, I want to quote two answers I found on StackOverflow that could help to solve some other doubts:

from http://stackoverflow.com/a/2551161

The important thing to realize here is that you can (and should) write your code in a DI-friendly, but container-agnostic manner.

This means that you should always push the composition of dependencies to a point where you can’t possibly defer it any longer. This is called the Composition Root and is often placed in near the application’s entry point.

If you design your application in this way, your choice of DI Container (or no DI Container) revolves around a single place in your application, and you can quickly change strategy.

You can choose to use Poor Man’s DI if you only have a few dependencies, or you can choose to use a full-blown DI Container. Used in this fashion, you will have no dependency on any particular DI Container, so the choice becomes less crucial in terms of maintainability.

A DI Container helps you manage complextity, including object lifetime. Used like described here, it doesn’t do anything you couldn’t write in hand, but it does it better and more succinctly. As such, my threshold for when to start using a DI Container would be pretty low.

I would start using a DI Container once I get past a few dependencies. Most of them are pretty easy to get started with anyway.

and from http://stackoverflow.com/a/2066827

Pure encapsulation is an ideal that can never be achieved. If all dependencies were hidden then you wouldn’t have the need for DI at all. Think about it this way, if you truly have private values that can be internalized within the object, say for instance the integer value of the speed of a car object, then you have no external dependency and no need to invert or inject that dependency. These sorts of internal state values that are operated on purely by private functions are what you want to encapsulate always.

But if you’re building a car that wants a certain kind of engine object then you have an external dependency. You can either instantiate that engine — for instance new GMOverHeadCamEngine() — internally within the car object’s constructor, preserving encapsulation but creating a much more insidious coupling to a concrete class GMOverHeadCamEngine, or you can inject it, allowing your Car object to operate agnostically (and much more robustly) on for example an interface IEngine without the concrete dependency. Whether you use an IOC container or simple DI to achieve this is not the point — the point is that you’ve got a Car that can use many kinds of engines without being coupled to any of them, thus making your codebase more flexible and less prone to side effects.

DI is not a violation of encapsulation, it is a way of minimizing the coupling when encapsulation is necessarily broken as a matter of course within virtually every OOP project. Injecting a dependency into an interface externally minimizes coupling side effects and allows your classes to remain agnostic about implementation.

The Example

The framework and the example can now be found on GitHub (I use bitbucket only for temporary or personal projects) at: https://github.com/sebas77/Lightweight-IoC-Container-for-Unity3D. You are very welcome to modify it and share your improvements to the other users.

Note: you can add more turrets if you want using the Editor, thanks to the IoC everything will work without touching code.

IoC Container for Unity3D – part 1

Unity is a very good game development tool, although while I like most of the features (and trust me it is very hard to make me happy), the code framework is still awkward to use.
Let me explain why I say awkward. Unity is born as rapid application development tool and due to its nature, it has been soon adopted by many “indie” developers. However Unity is now trying to make a leap forward toward the triple A development, but while the company is mainly focusing on adding new editor features, there aren’t many news about the framework itself, which code design is currently too much “one-man band” oriented.

The considerations in this article do not really apply to simple projects or projects developed by one or two persons. For these specific cases, Unity is perfect. The arguments in this article apply instead to medium-big projects developed by a medium-big size team.

I will not talk about all the flaws I found, but I will focus on specifically one, that is how awkward is injecting dependencies inside Unity entities.
To be clear, a dependency is defined as an object needed to another object to execute its code. If a class A needs the instance of a class B to execute its code, B is a dependency for A.

The problem

Unity is based on a modern concept of “Entity Framework”. Out there several implementations of entity framework exist and I am even creating one in actionscript 3. Entity framework is a very powerful concept and has many advantages: pushes the users to favor composition over inheritance, keep the classes small and clean focusing on single responsibilities, promotes modularity. This is in a perfect world…

In Unity, the Entites are called GameObjects and the Components are based on MonoBehaviour implementations. Personally I have some golden rules I want to follow when I implement MonoBehaviours for GameObjects:

  1. MonoBehaviours should always operate on the GameObjects where they are attached to.
  2. MonoBehaviours are reusable, single responsibility classes.
  3. GameObjects should not be created without a view (that would be a mesh, collider or something that is really an entity in the game, the only exceptions are for empty GameObjects used as “folders” and other specific cases I will illustrate another time).
  4. MonoBehaviours can know other components on the same GameObject using GetComponent.
  5. The behaviour of a GameObject should be extended adding MonoBehaviours instead of adding methods to a single MonoBehaviour.

The problem is, as many of you know already, that Unity does not really allow to follow most of these rules because of the way the dependencies must be solved. In fact what happens if my component needs to communicate with other classes? Let’s say there is a Level class and for some reasons this class must know the monsters that are still alive. When a monster dies, how is it possible to communicate the fact to the Level object?

Currently there are 3 simple solutions to this problem:

  1. Level is a Monobehaviour created inside a GameObject that has no view. All the monsters will look for the Level class using the GameObject.Find call inside the Start or Awake functions.
  2. Level is a Singleton.
  3. Like 1, but Level is found through Object.FindObjectOfType.

Howbeit, I reckon there are problems in following all the three possible solutions:

What’s wrong with GameObject.Find

The first solution breaks my golden rules, which would be not a big issue since they are actually more guidelines for good design. Instead the real problem is the use of GameObject.Find. GameObject.Find is one of the example of how awkward the Unity Framework is for big project development.

What happens if someone in the team decide to rename the GameObject? Should be imposed that the GameObjects once created must not be renamed (or deleted) anymore? GameObject.Find can lead to several run-time errors that cannot be caught in compiling time. This scenario could be really hard to manage when dozens and dozens of GameObjects are searched through this function.

What’s wrong with the Singleton

Singleton is a controversial argument since the pattern has been invented. I am personally against the use of Singleton. However if you ask me why I am against the Singleton I will not answer you with the usual answers (break encapsulation, dependencies hiding, many issues to test the code through unit test, being bound to the implementation of a service instead of its abstraction), but with the hindsight of the practice: your code will become a big pile of crap after a while. This is because Singleton does not involve any design constriction that, while make apparently the coder life easier, will make it a hell later on, when the classes design become an incomprehensible blob of code without a structured flow.

What’s wrong with the Object.FindObjectOfType

How should the Level object be injected inside the Monster class then? There is actually a third solution, that is calling the function Object.FindObjectOfType. But, what is FindObjectOfType? Object.FindObjectOfType could be seen as a wrong implementation of the Service Locator Pattern, with the difference that it is not possible to abstract the implementation of the service from its interface. This is another problem of Unity framework, Unity seems to hate the concept of interface. Interface is the most powerful concept at the core of every well designed code. Instead to push the coders to use interfaces, Unity pushes the coder to uses Monobehaviour, even when the use of Monobehaviour is not necessary.

The solution

Mainly there are 3 ways to resolve dependencies: using the Service Locator pattern, injecting dependency manually through constructor or setter and using an Inversion Of Control container. I do not like to use the Service Locator Pattern because the SLP itself is a singleton (or a static class) and this could lead to some severe limitations compared to the IoC container solution. However using an IoC container in Unity is not simple because Unity does not specify a place where the application can be initialized.

Explain what an Inversion of Control container is needs probably another article, so I will be simple with it. An IoC container is a…..container that contains the dependencies that must be injected. It is called IoC because the design is created in such a way that the objects are never created by the user (in fact you can also forget the use of the new keyword), but they are lazily created by the container when they are requested.

There are several IoC containers out there, a lot written in c# as well, but practically no one works in Unity and most of all, they are damn complicated. For these reasons I decided to create an IoC container for Unity trying to keep it as simple as possible. Actually creating a basic IoC container is pretty straightforward and everybody can do it, my implementation has just a few tweaks that makes it simple to use with Unity projects.

Conclusion (for this article)

I decided to conclude this first article here because before to continue I want to know the interest of the people in using an IoC Container in Unity. If the interest is low I will just keep on using it for my personal and professional works only. So if you are interested in knowing more, please leave a comment.

The second part of this article (including source code) is now available here: http://blog.sebaslab.com/ioc-container-for-unity3d-part-2

Develop HTML5 games without JS and DOM for flash developers – Part 2: Jangaroo

The reason why I called the first tutorial of this series Part 1 is because I knew there were other alternatives around to develop HTML5 games, carefully avoiding javascript.

However after some researches it turned out that the only really working alternative suitable for actionscript developers is Jangaroo.

Let’s talk a little bit about it. Jangaroo is an open-source project mainly used by the German company Coremedia. The smart guys from Coremedia hate javascript so much that they decided to create a compiler capable to convert actionscript 3 to javascript and they called it Jangaroo.

However Jangaroo has not been created with the intent to support Flash libraries (including the display list), what the developers had in mind was just to have a way to create web applications with a language different from Javascript.
Jangaroo is for actionscript 3 what HaxeJS is for Haxe, that is a way to entirely map a language into another. In fact Jangaroo is mainly used with pre-existent and remapped javascript libraries, that is more or less what happens with HaxeJS.

This part of Jangaroo is supposed to be quite stable, in fact it has been already used for several internal projects at Coremedia. It is also interesting to note that several open-source applications have been made with it. Among these projects we can find the porting of the 2D engine Flixel and the physic engine Box2D.

The main source code of Jangaroo and all the applications can be found on several github repositories.

The first impact I had when I read the clear (but a little bit outdated) tutorial was: woah woah woah, what? Do I have to install Maven to run it?! Seriously?! It must be a pain!

Thus, since for a long while now I wanted to try Realaxy IDE (man, it is not really easy to remember how to spell it) and since I knew that the beta version 1.1 is supporting jangaroo to convert the actionscript code to JS, I decided to install it thinking it would have been a smart decision.
Instead few minutes using it were enough to understand that it was a big mistake! First it is java based = a pachydermic piece of software as slow as the other incredibly overrated IDE Eclipse (and its cousin Flash Builder), second it lightly decided to delete my project folder, including all the code I have manually converted from the previous Haxe version of my experiment, that of course I did not back up urggghhh.

By the way, this is something that could be interesting: I actually tried to convert the Haxe code to actionscript 3 using the automatic method that Haxe provides, but it failed in several ways and so I had to spend more or less an hour to manually convert the source code.

At this point I decided to go for Maven and surprisingly everything worked out smoothly and painlessly. What Jangaroo asks to install in order to work is just the last version of Java Runtime Environment and Maven, nothing else.
The only thing to pay attention to (as explained in the tutorial) is to set the JAVA_HOME environment variable that must point to the folder where the JRE is installed.

Now everything is set to follow the aforementioned Jangaroo tutorial, which explains in few steps how to create the first “hello world” application without using flash libraries.

With the knowledge gathered so far, you will be able to create a javascript based application using actionscript 3, but you will not be able to use the display list to make games.

Although the goal of this tutorial is to show to the reader how to use the Display List in jangaroo to make HTML5 games, let’s be clear: I am not a fan of the Display List and I do not think it is a good data structure to use for HTML5 games. So even if Jangaroo, as we will find out, has some flaws in converting the display list related code, I would not say this is a great limitation.

The real problem is that from now on the documentation become very scarce. Your main source of information will be GitHub and the Jangaroo group on google. They are both managed by Frank Wienberg, who is the most active Coremedia employee developing and maintaining the project.

Honestly, while Frank is a great guy willing to help as much as he can, the fact that he is alone is another relatively big limitation of the project. In my opinion Jangaroo needs a bigger community to become really successful and I think it even deserves it. More people should at least give it a try, that’s also why I am happy to write this article.

In order to work with the DisplayList, the next step is to extend the pom.xml file. The pom.xml is a config file needed by Maven to understand what to do and which libraries to use.

I do not think it is necessary at this point to explain every single node inside the XML, since the jangaroo tutorial is quite simple to understand. However in order to get more information two options are available:

One is to use the template example in github, the other one is to use FlashDevelop and download the template to create a working jangaroo project.

Once the template is installed and the project is created, the pom.xml will be generated automatically inside the project folder; just be careful that Flashdevelop uses the JAVA_HOME variable as well, but it is NOT compatible with the 64bit version of JRE. In case you have both the 32bit and the 64bit versions installed and you decided to use the 64bit version to run maven, I suggest to edit the FD jvm.config file to instruct it to use JRE 32bit.

Do not be afraid to open the xml file, it is quite self-explanatory. The only attributes you need really to take care of are jangaroo_version node and jangaroo_libs_version node. The value inside must be kept updated with the latest version of the libraries available. Maven will automatically download it the first time the project will be compiled. Totally awesome!
I guess that the Maven repository is a good place where to check the latest Jangaroo version (the preview versions seems to not support the flash libraries yet).

Other two important nodes of the Pom.xml file are the dependencies and the resources nodes.

The dependencies node tells Maven which other libraries to use while compiling the source code. For this article sake, it is important to know that the jooflash extension, which enables the flash library, is not part of the standard jangaroo library, but it is among the extra ones and so it must be included inside the dependencies node.

<dependencies>
   <dependency>
     <groupId>net.jangaroo</groupId>
     <artifactId>jooflash</artifactId>
     <version>${jangaroo_libs_version}</version>
     <type>jangaroo</type>
   </dependency>
</dependencies>

Jooflash is a side project developed exclusively by Frank Wienberg, therefore it is not as stable or as complete as the main Jangaroo library.

the resources node is instead useful if you want to embed resources using the meta tag [Embed(source = “…”)]

<resources>
     <resource>
       src/main/assets
       <includes>
         <include>**/*.png</include>
         <include>**/*.jpg</include>
       </includes>
       joo/assets
     </resource>
     <resource>
       <directory>webapp</directory>
     </resource>
</resources>

Ok, I think I have said everything is needed to say to let you work with Jangaroo. Now let’s talk about my results.

My intent was to compare the performance of Jangaroo against the Jeash performance using the incredibly bad code I wrote for the shoot’em’up I have created for the first tutorial of this series.

However in this case bad code adds value to the experiment, because it can be used to gauge how good the compiler is.

The results are quite interesting:

At first it seems that Jeash beats Jangaroo in every aspect. Jeash is infact much faster (60fps against 30fps) and much more compatible across the browsers (the game works on every modern browser known using Jeash, while the Jangaroo version behaves quite differently and in some cases wrongly). Jeash seems to use pretty neat CSS tricks to incredibly optimize the performance.

However there is a very important aspect to take in consideration: Canvas blitting. In this case Jangaroo seems way better than Jeash.

Both version of FlashPunk and Flixel, as the flash coders know already, use only bitmap blitting to render the entire screen without using the flash display list at all. It is pure old school 2D blitting.

@teormech on Twitter is currently porting Flixel to Haxe and experimenting with Jeash as well. He found out that the Jangaroo Flx invasion demo runs 3 times faster than his Jeash porting. According my profiling the Jangaroo version of the game takes approximately 3ms to render the 640×480 screen, while the Jeash version takes about 12ms!!!

That means that for pure canvas application currently Jeash performance is very disappointing.

This is all! And this is very likely my last article regarding HTML5 technology. I have always been skeptical about HTML5 as platform for videogame developers and the current performance on desktop, but especially on mobile, demonstrate that HTML5 is not ready for professional game development.

Note: My first article and the considerations about Jeash written in this second one are based on the last version of Jeash (0.8.7) before it has been merged to HaxeNME. Unfortunately as today, the jeash version included in HaxeNME appears to be broken. Jeash seems to be sensibly worse than the previous version I worked with.