Object construction with factory method

How to structure your code to produce loads of objects? Learn the Factory Method and how to implement it in Unity3d!

One of the most common things to do in making a game is instantiating objects at runtime. Be it bullets from a gun, enemies rushing forward or instances of software classes, sooner or later you’ll need to do it.

This is one of those classic problems of computer science that have been solved over and over again. The solution to it I’m going to talk about today is the Factory Method (not to be confused with the Abstract Factory, which is way more general in its application).

What’s a Factory Method?

factory-method-pattern

Basically it’s when you use an inherited method (either from a superclass or an interface) to create for you an instance of a Product. The Product will be set up just as you specified with the arguments that are given to the Factory Method.

For instance if you have an EnemyFactory superclass, you could have a OgreFactory implement the FactoryMethod() for it. Then you could have an Ogre orc=datOgreFactory.FactoryMethod(100) to have orc‘s hit points set to 100.
Of course the GoblinFactory is another subclass of EnemyFactory but will still give you a 100 hp hulkling of a goblin if you ask for it with a Goblin hobGoblin=datGoblinFactory.FactoryMethod(100). It’s important to keep in mind that both Ogre and Goblin are one same kind of superclass: Enemy. This means they will share a common usage in their DieForLoot() function so that the kill procedure doesn’t need to know their specifics.

If you want a more technical definition, the internet is filled with it but I’d rather recommend to cut to the source and read it straight from the book written by the Gang of Four.

When to factory?

That’s more of a critical issue worth discussing. My personal answer would be to use it every single time you have more than exactly one thing to instantiate and most of the times you actually instantiate just one thing.

If you want dem clones, make a factory!
If you want dem clones, make a factory!

When you construct an instance of something twice, you are duplicating code and sure as hell it’s better not to write the same thing twice.

As for the reason I’d recommend to write one even if you are doing an instantiation just once:

  • if it’s something that will be a part of gameplay are you really sure you won’t be putting another one somewhere else?
  • Are you really sure you don’t need to test the instantiation itself indipendently?

Chances are, you will, and copy-pasting a bit of boilerplate code upfront is way better than refactoring after.

Also, it helps with respecting the single responsibility principle in the code: if instantiating that object was the only job of the class it’d be a factory, wouldn’t it?

But be careful: in some cases you might need to move even further and go full Abstract Factory. You might ask yourself:

  • Do I need to abstract everything or is it ok to work on concrete instances?
  • Do I need to hide my concrete code (i.e.: with a .dll)?
  • Do I need a factory of factories?

If you answered no to that, there’s no need for too much abstraction and you can just use the good old Factory Method.

blueprints-1837238_1920

How to build one in Unity3d

When working with Unity we have the usual problem of handling the references, which entails serious design decisions over how the factory should be realized. Plus in this case we have an additional issue: interface references won’t show up in the inspector, not even with a SerializeField .

Why? because just as generics (with the exception of the hardcoded List<T> ) interface references don’t get serialized in Unity, unless you write a workaround or pay sixty bucks …or at least five.

So this code:

public class FactoryUser : MonoBehaviour
{
    [SerializeField]
    IFactory thisWontSerialize;
    [SerializeField]
    MonoBehaviour factory;

will be rendered in the inspector like this:

immagine

So how to do a factory? Let’s begin with the interface (of course you can also make a superclass and skip half of the issues).

public interface IFactory 
{
    GameObject FactoryMethod(object[] parameters);
}

Why an array of objects? because we don’t know what we’ll need, so better have the thing that can do everything. A more type-safe approach would be to define a dedicated struct or class.

To have a working example we’ll implement a concrete factory that instantiates a number of childs of a main prefab:

public class ConcreteFactory : MonoBehaviour, IFactory
{
    [SerializeField]
    GameObject mainPrefab;
    [SerializeField]
    GameObject childPrefab;

First of all,  we add the references so that they can be seen in the inspector. Of course we’re going to make this class a MonoBehaviour, because to use the inspector is either that or ScriptableObjects and this is not a ScriptableObject tutorial. And I love the inspector.

inspector unity
He obviously prefers a platonic love 🙁
    public GameObject FactoryMethod(object[] parameters)
    {
        GameObject mainObject = Instantiate(mainPrefab);
        int amount = (int)parameters[0];
        for (int i = 0; i < amount; i++)
        {
            GameObject childObject = Instantiate(childPrefab);
            childObject.transform.parent = mainObject.transform;
        }
        return mainObject;
    }

This is the method that implements the IFactory interface. What we now do is:

  1. Instantiate a copy of the main prefab.
  2. Dumbly take for granted that the first parameter really IS an int
  3. proceed to a runtime error to instantiate and reparent his child objects
  4. witness in horror as performance sinks since we didn’t use pooling here

Now that the concrete factory is done let’s see it in action:

public class FactoryUser : MonoBehaviour
{
    [SerializeField]
    MonoBehaviour factory;

Wait, why a MonoBehaviour reference? We don’t want any runtime checks, do we? This should be type-safe and checked at compile-time!

    public void OnValidate()
    {
        if (!(factory is IFactory))
        {
            Debug.LogError("Wrong reference type");
            factory = null;
        }
    }

Well, not really at compile time, we just need it to be done while the game isn’t running. So here’s a check that runs every time the field is modified in the inspector. Of course if you want to inject the factory instance or have it passed some other way, you can use an IFactory variable instead.

This is just a workaround to have both type-safety and serialization after all, here’s another one if you don’t like it this way.

workaround unity interface serialization

But we’ll also avoid having to write a cast every time we use it:

    IFactory Factory { get { return factory as IFactory; } }

So we now can write:

    public void Start()
    {
        object[] parameters = new object[1];
        parameters[0] = 2;
        Factory.FactoryMethod(parameters);
    }

And finally, here it’s at work. Easy as pie. So easy it will be a pleasure to test and spam everywhere (provided you pooled everything).

Where’s the advantage of using this approach? Say your level designer wants to change the enemy type that is spawned in front of the castle gates, he can do it in the inspector simply by changing the factory that is referenced in the castle gate spawn component. No coding required, just a drag&drop.

That’s all folks!

Here’s a Unity project where you can grab al the code and see it in action, plus scroll down for a copy-pasteable version of it.

I hope you liked this tutorial, please tell me if you find this kind of guide interesting or not, either here or on my Twitter. If you don’t want to miss my next thing consider subscribing to my newsletter.

P.S.: I’m currently looking for a job, if you are interested here’s my portfolio.

public class ConcreteFactory : MonoBehaviour, IFactory
{
    [SerializeField]
    GameObject mainPrefab;
    [SerializeField]
    GameObject childPrefab;

    public GameObject FactoryMethod(object[] parameters)
    {
        GameObject mainObject = Instantiate(mainPrefab);
        int amount = (int)parameters[0];
        for (int i = 0; i < amount; i++)
        {
            GameObject childObject = Instantiate(childPrefab);
            childObject.transform.parent = mainObject.transform;
        }
        return mainObject;
    }
}
public interface IFactory 
{
    GameObject FactoryMethod(object[] parameters);
}
public class FactoryUser : MonoBehaviour
{
    [SerializeField]
    MonoBehaviour factory;
    IFactory Factory { get { return factory as IFactory; } }

    public void OnValidate()
    {
        if (!(factory is IFactory))
        {
            Debug.LogError("Wrong reference type");
            factory = null;
        }
    }

    public void Start()
    {
        object[] parameters = new object[1];
        parameters[0] = 2;
        Factory.FactoryMethod(parameters);
    }
}
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

The singleton follow-up – a deeper look into singletons in unity3d

This post it’s a bit different than usual. This is not just a tutorial but rather “the talk”… or a grownup discussion depending on your degree of advancement. And yeah, for some of you it’s going to be like “Look kiddo, I’ve been doing this shit long before you even saw your first keyboard”, for those of you, I’m sorry, I hope this won’t be extra cringy and just jump to the “What’s the solution?” paragraph.

We’re now going to discuss a little bit of architecture, or as some of you were thinking in last post “why singletons can break everything for everyone”.

sex-talk-kids-know-more

The reasons behind

Up until now maybe you thought that the problem is doing stuff with code, hitting up on the keyboard until the pixels behave properly, but hacking a system until it does what you want with the least possible effort is the aim of all of us, including those of us that are seen using some more exoteric stuff like zenject.

The thing is: not everyone deals with the same time horizon. If you are just doing a short game jam, a single megalithic script with all your code in it could even be a good idea (i.e.: if your problem is writing fast enough and alt-tabbing it’s too slow for you).
But let’s say you are going to develop a project that’s going to stay 10 years, better believe that spending one month just planning ahead may not be enough. And if you are using an engine, with a 10-yr horizon you could bet that maybe not even the engine is going to stay all that time. The engine developer may shut down and you may have to change it 6 years from now for all you know.

So in some cases you just need to plan for maintenance a lot and do stuff that it’s not that immediate because of issues that would come up only a few years into development.

afterburner-inspection-897513_1280

How in hell are singleton involved?

The thing is, when I think singleton in unity, I think static class with an inspector. This is since the other ways to use singletons have quite serious issues that a long term project cannot ignore. And by the way, even that won’t be good in many cases.

The most important issue here is maintenance. Maintenance cost is sometimes so high that it’s just cheaper to throw everything away and build it from scratch again. And for maintenance there’s an important concept that every dev should tatoo on his right arm memento-style: dependency management.

When class A uses class B, A depends on B meaning that if you make changes to B you are going to have to change A too.

This doesn’t render justice to the issue. Let’s put it another way:

In a project where every class depends on every other, just change one function and you’ll have a fun time rewriting almost all of it.

And what do singletons have to do with this? As I said in last post, they are basically a global variable on steroids, so they put hidden dependencies in your code. This means:

In a project where every class hiddenly depends on every other, just change one function and you’ll discover by surprise that you now must have a fun time rewriting almost all of it.

So when you plan your architecture you better mind it and ask yourself “how is this class going to affect the others when I change it?”

that's quite unstable
that’s quite unstable

Instantiation issues

One of the big problems with singletons is their instantiation (or rather, the dependencies it entails). Who instantiates a singleton and when? If you do it like I’ve shown in my last tutorial, you’ll leave that to unity by just putting a GameObject with a component in your scene and keep it there forever. But the singleton pattern allows for a host of other solutions.

Another solution is called Lazy loading, which means that you load the singleton when is first used, something like this [DANGEROUSLY WRONG EXAMPLE]:

public class LazySingleton {
    static LazySingleton instance;
    public static LazySingleton Instance 
    {
       get 
       {
          if (instance  == null) 
          {
              instance = new LazySingleton();
          } 
          return instance;
       }
    }
}

Now, with current Unity implementation and without ever thinking of multi-threading that may not sound too much of a problem. But let’s say that 4 years from now they go on hard on multi-threading (or that you just don’t want to waste those many extra CPUs), then you won’t know if two classes that try and access the instance get the same one or not.

Why you don’t know? because they might both do the if (instance==null) at the same time and therefore get two instantiations done. You therefore have to lock your code and make it thread-safe.

Loading time(s)

Using MonoBehaviour and putting it on a GameObject in your initial loading scene takes this issue away from you, but still leaves one window open for troubles: what if you want to use that singleton in one of your Awake functions in that same scene?

If you remember my Event System tutorial that’s one issue that could require quite extreme solutions, but there is a more general issue here that is explained in Sebastiano Mandala’s blog better than how I can do here in a few words.

Let’s just say that Unity hides away a quite crucial step: the code’s entry point. You’ll never have the pleasure of being sure that the row X of the class Y is really the first thing that’s executed, at least not by just looking at the code. You’ll have to tamper with Script Execution Order settings, hope the next update won’t screw it up, do it every time you want to import your code base on a new project, hope it’s bug free.

Spoiler: that’s bad.

455252569_7b5bcdff02

What’s the solution?

So, we’ve come to understand that what’s bad in singletons is (mainly) two things:

  • they hide dependencies
  • they need to be instantiated carefully

About the hidden dependencies, that’s more than anything a matter of implementation inside your singleton: if you make it so that his state needs management and coordination across its users, that’s where the hidden dependency creeps in. And that’s the symptom of a bad design. If that is the situation you are in, consider using command pattern and having another class manage explicitly the singleton’s state, so that the users can just make a request without needing any coordination among each other.

While the hidden dependency is a universal problem, the instantiation is quite hard to manage in Unity. Luckily there are solutions. Yeah, plural. Which means there’s no best and safest here, I’ll highlight just two of them, but I encourage to seek for more (and to write about it in the comments if you want to share).

ragecomic

Option A: automate everything

One solution is to take away from Unity the control and go all in with frameworks like the aforementioned Zenject or Svelto.ECS.

What it does is to manage for you the instantiation of classes, of course you need a solid understanding of what Inversion of Control and Dependency Injection are and why they’re needed or you’ll end up in a horrible mess, but on the other side you get to have your code layout practically already decided with a safe and sound architecture that’s Unity-independant. This will also enable you a lighter maintenance process.

On the con’s side there’s now a framework running in the background that will consume resources, will cache information and generate garbage without you even noticing. In these conditions keeping up with memory budget gets harder, in some cases this is therefore just not an option. Also, readability of your code takes a hit, since now you must mind unwritten implications of using a reference and since the system forces you to make a bit more boilerplate code.

In this solution you just don’t use singletons because you don’t need them. You already have global access to services (the framework does it for you) and as for uniqueness you can just use a static class.

art-1837073_1280

Option B: handcrafting

One other solution is to carefully think about dependencies and manually manage instantiations (AKA filling the dependency graph). This means again to take away control from Unity, but by using the tools that it gives you. This also means that you just define an entry point for your code (for instance by using a dedicated scene that gets loaded for first) and use a dedicated script to manage all the objects’ instantiations, so now the singleton doesn’t manage his own instantiation, it just wards off against duplicates.

This has of course the big advantage of readability: everything is laid down clearly in your code, nothing stays hidden any more and you know what gets done when. Another big plus is performance, since you are in charge of doing everything you can put that extra care in it to avoid wasting a single bit.

The problem here is that now you are in charge, there’s no standard to protect you from bad decisions. Maintenance gets a bit harder and if you work in a team it requires surveillance to check that no-one caves in to deadline pressure and starts cutting corners. It also means that you will have to plan ahead and consider the implications of your design, wich means time shall be devoted to this.

In this scenario you can use singletons but you’ll have to care for everything and be mindful of the risks they carry. Again, my approach here is to think static class with an inspector, but the good way to go may also extend further, you just need to remember that a singleton is no excuse for not abstracting what can be and not to follow the SOLID and IoC paradigms.

keep-calm-and-hakuna-matata

 

Some non-problems

Sometimes I also heard as an argument against singletons something along the lines of : “it breaks solid because it has to deal with its own instantiation, which by definition violates the Single responsibility“. Now, technically, that’s undeniably true. Practically it isn’t. The only reason we’ve got to write boilerplate code to get a singleton is because this is not a feature of the language.

If we were in a world where static classes were not a thing and only static fields existed, to create a static class would imply some tinkering, just the same way. Would that violate the single responsibility? Abso-fucking-lutely. Would anyone argue that therefore we shouldn’t use static classes? probably someone, this doesn’t mean we should consider it a good reason not to use static classes.

If you decided to have a singleton, that’s on the same level of deciding to have a static class. The only difference is that you can’t do it with just one word in your language. The real issue is when you instantiate it, but that procedure is not what makes a singleton a singleton. You can delegate instantiation to another class and only check for uniqueness in the singleton itself (something that you wouldn’t need to do if there was a language keyword). If someone doesn’t delegate this responsibility on another class, is not due to the pattern but to implementation.

Another quite widespread criticism is that singletons carry state around the application’s lifetime and that makes automated testing harder. Again, this is undeniably true: they do carry state and state does make tests harder.

But the thing is that it’s not just singletons that have this issue! You would get this problem with any interaction with external components that just don’t always give every single time the same result. So except for pure functions you already deal with this for all external dependencies you have in any class.
Also, if you have given the singleton a state it’s probably because you needed to represent something that will still need a stateful representation even if implemented elsewhere.
You’ll therefore get the same result with any other pattern in terms of testing problems.

So, why I did it that way?

Now it should be more apparent why I picked that specific design to implement singletons within Unity:

  • inheriting from MonoBehaviour delegates the instantiation to the engine, so no thread-safety measures and locks are needed
  • making it a component of a GameObject enables to use the inspector, which means a designer can tweak the parameters
  • using Awake to initialize the reference leaves room for other classes to use it on Start
  • creating a class from which to inherit the singleton-ness helps to keep different responsibilities in different files and enhances readability

In other words, although I didn’t use a great deal of Unity’s features, it’s a very Unity-dependent code in its design.

And by the way, if you don’t make the instance variable publicly accessible and write all your public functions as static functions that access the instance, you’ll really basically get a static class with an inspector.

public class StaticWithInspector : MonoBehaviour
{
    static StaticWithInspector instance;
    public static StaticWithInspector Instance
    {
        set
        {
            if (instance == null)
            { instance = value; }
        }
    }

    void reallyDoIt() { }

    public static void DoSomething() {
        instance.reallyDoIt();
    }
}

See? here we have it, the Instance property allows to check for uniqueness and the usage will be exactly the same of a static class. Of course you can use this in combination with the script of the last time.

That’s all folks!

I hope that in this post there was something of value even if this time there was no script to grab. Last tutorial left so much untold that I felt the need to write about it. I’ve also received a lot of useful feedback, wich by the way has shown me that there’s interest even in something that’s not just a basic coding how-to.

Special thanks go to Sebastiano Mandala’, Christian Meneghini, Claudio Freda and Lars Kokemohr for their remarks.

As usual, if you want to keep up with my stuff, consider registering with my newsletter. For any comments discuss down here or hit me up on Twitter.

P.S.: I’m currently looking for a gamedev job, if you are interested have e look at my portfolio.

  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Input management with Dependency Injection

Object oriented programming has a lot of patterns that can be very useful for making games. One of those patterns is the Dependency Injection, a pattern that helps to decouple classes that would otherwise be tightly connected. So let’s take something that’s really connected and see how dependency injection can help us: the input management.

Wait what’s this Dependency Injection?


Usually if you have a thing (call it client) that uses another thing (call it service), when you change the service, then you have to also change the client. And that’s bad. Let’s say the client is your game logic and you are porting your game from pc to mobile, and that therefore you need to switch from a keyboard + mouse input to a touch one. Since all inputs are changed (perhaps radically since your WASD is now a UI element) you now need to change some input-read line in your game logic even if you used an intermediate class to get those button inputs.

The Dependency Injection way to do it instead is to have the input manager call the game logic functions. Without it knowing whose functions they are. You just set them as callbacks and call them when needed. Who sets the callbacks? The naive option is: the client. But then you still have a direct dependency between the classes. Enter the DIC: Dependency Injection Container. He takes the callbacks from the client and gives them to the service, thus eliminating the dependency between them (and adding another class to your code, that’s not a free lunch).

And what are those de-leee-gates?

Delegate

A delegate is just a way to pass a function as an argument, it can also be stored as a variable and given a type name to be checked so that only the functions that match a certain signature can be stored or passed as a delegate of a specific type.

Let’s read some Input!

    [SerializeField]
    string XbuttonName = "Fire1";
   
// other button names 

    [SerializeField]
    string LeftStickHorizontalName = "Horizontal";
    [SerializeField]
    string LeftStickVerticalName = "Vertical";
//other axis names

First of all we’ll need the names of the input buttons and axis we’re going to read, for this example I’ve used a regular xbox controller. We’ll do this with the old unity input system, not the (currently) experimental one, so we’ll need a string name for it. If you’ve read my other tutorials you know I’ve a personal feud with strings, but this is one of the few cases you really have to use them: if you are building an input manager you don’t want to force whoever uses it to edit code just to rename an input field, so you really want to have that in the inspector, which means a serialized string. Notice that for thumbsticks we’ll need two axis per stick, so two thumbsticks means four axis.

    public static InputManager instance;

    [SerializeField]
    InputManagerDIC inputDIC;

    [SerializeField]
    float triggerSensibility = 0.2f;

As for the other variables, the instance reference will be used to make this class a singleton, the inputDIC is needed to ask for the injection, and the trigger sensibility trashold will be used to get a button behaviour from an axis, because back in my days triggers were fucking buttons and I like it that way.

public delegate void buttonReaction();
public delegate void axisEffect(Vector2 axisVal);

Although we could make this all with predefined System Actions, I’d rather estabilish a more specific interface that reminds whoever writes the game logic code what is supposed to act as a button and what is supposed to act as an axis. It’s just a reminder, nothing more.

good old controller
good old controller
    public static buttonReaction XbuttonPress = delegate () { };
    //other press callbacks ...
    public static buttonReaction XbuttonPressContinuous = delegate () { };
    //other continuous callbacks 
    public static axisEffect leftStickEffect = delegate (Vector2 a) { };
    public static axisEffect rightStickEffect = delegate (Vector2 a) { };
    public static System.Action InputStartRead = delegate () { };

Each callback is initialized to an empty delegate because if for whatever reason we don’t want to use something, we don’t want a nullreference exception to pop out after the change.

Now, we can define a lot of callbacks for each Input since every button has four relevant conditions:

  • just pressed
  • pressed (continuously)
  • just released
  • released (continuously)

In this example I’ll use four buttons and the triggers and read only two condition for the buttons (just pressed and continuous press) and one for the triggers (continuous press), for each of the conditions I want to read I need to define a callback.

The same goes for what to do with thumbsticks, but in that case I just want to read a direction out of them and let the game logic interpret it.

The last callback isn’t really needed but for this tutorial I’ve also built a public repository where you can download a test scene and I need to clean the UI state at the beginning of every frame, so I want a callback for that too.

void Awake()
    {
        if (instance == null)
            instance = this;
        else
            Destroy(gameObject);
        inputDIC.LoadInputManager();
    }

As I said before this is going to be a Singleton. And at the beginning of execution we want the DIC to inject his callbacks in the InputManager, so we’ll call his loading function here.

    void Update()
    {
        InputStartRead();
        if (Input.GetButtonDown(XbuttonName))
        { XbuttonPress(); }
        //read other buttonDowns
        if (Input.GetButton(XbuttonName))
        { XbuttonPressContinuous(); }
        //read other buttons
        if (Input.GetAxis(leftTriggerName) > triggerSensibility)
        { leftTriggerPressContinuous(); }
        if (Input.GetAxis(rightTriggerName) > triggerSensibility)
        { rightTriggerPressContinuous(); }

        leftStickEffect(new Vector2(Input.GetAxis(LeftStickHorizontalName), Input.GetAxis(LeftStickVerticalName)));
        rightStickEffect(new Vector2(Input.GetAxis(RightStickHorizontalName), Input.GetAxis(RightStickVerticalName)));
    }

And at last here’s the action. At first we call the “start reading” callback, then for each button we check the relevant states. Notice that for the trigger we read an axis input and only when it’s over the trashold we’ve set before we call a callback just as if it were a regular button. From the game logic standpoint that trigger will be undistinguishable from a button, it even uses the same delegate type for the callback. For the thumbsticks instead we’ll read the two axis in a single Vector2 variable and use that to call the appropriate axisEffect callback.

How about a UI class for testing this?

a really simple ui
a really simple ui

I’ve made it as basic as it gets, sorry but no fancy stuff here:

    [SerializeField]
    Toggle xButton;
    //other toggles
    [SerializeField]
    Text rStick;
    //other texts

For each button I’ll set a toggle on and off, while for the sticks I’ll show the direction in a text. All the references are passed with serialized fields in the inspector.

    public void LogCallTLCont() { ShowLogButton(lTriggerButton, "TL Cont"); }
    public void LogCallTRCont() { ShowLogButton(rTriggerButton, "TR Cont"); }
    public void LogCallA() { ShowLogButton(aButton, "A "); }
    public void LogCallB() { ShowLogButton(bButton, "B "); }
    public void LogCallX() { ShowLogButton(xButton, "X "); }
    public void LogCallY() { ShowLogButton(yButton, "Y "); }
    public void LogCallACont() { ShowLogButton(aButton, "A Cont"); }
    public void LogCallBCont() { ShowLogButton(bButton, "B Cont"); }
    public void LogCallXCont() { ShowLogButton(xButton, "X Cont"); }
    public void LogCallYCont() { ShowLogButton(yButton, "Y Cont"); }
    public void LogCallL(Vector2 direction) { ShowLogAxis(lStick, "L stick with dir", direction); }
    public void LogCallR(Vector2 direction) { ShowLogAxis(rStick, "R stick with dir", direction); }

    void ShowLogButton(Toggle toggle, string text)
    {
        toggle.isOn = true;
        Debug.Log(text);
    }

    void ShowLogAxis(Text field, string text, Vector2 direction)
    {
        field.text = direction.ToString();
        Debug.Log(text + direction);
    }

All the callbacks are actually using the same couple of functions, logging and setting an UI element each time. But who’s going to reset all those toggles when we didn’t read the button’s release? Our reset function of course:

    public void ResetUI()
    {
        xButton.isOn = false;
        yButton.isOn = false;
        aButton.isOn = false;
        bButton.isOn = false;
        lTriggerButton.isOn = false;
        rTriggerButton.isOn = false;
        rStick.text = Vector2.zero.ToString();
        lStick.text = Vector2.zero.ToString();
    }

 It’s Injection time

dependency injection input time
dependency injection input time

Also the DIC is really simple, all it does is to set the callbacks in the InputManager, so it only needs a load function and a field to specify from which class instance it should take the callbacks:

    [SerializeField]
    UserExample target;
    public void LoadInputManager()
    {
        InputManager.XbuttonPress = target.LogCallX;
        InputManager.YbuttonPress = target.LogCallY;
        InputManager.AbuttonPress = target.LogCallA;
        InputManager.BbuttonPress = target.LogCallB;
        InputManager.XbuttonPressContinuous = target.LogCallXCont;
        InputManager.YbuttonPressContinuous = target.LogCallYCont;
        InputManager.AbuttonPressContinuous = target.LogCallACont;
        InputManager.BbuttonPressContinuous = target.LogCallBCont;
        InputManager.leftStickEffect = target.LogCallL;
        InputManager.rightStickEffect = target.LogCallR;
        InputManager.leftTriggerPressContinuous = target.LogCallTLCont;
        InputManager.rightTriggerPressContinuous = target.LogCallTRCont;
        InputManager.InputStartRead = target.ResetUI;

    }

So, as you can see the InputManager has no dependecy towards the client class and the UserExample doesn’t even know that his functions are linked to an input. Any maintenance change on either class will stop here in the DIC and will be as trivial as just changing wich callback is assigned to what variable since that’s all that can happen here.

But what if I just changed Input Settings instead of doing all that?

That’s cool and that’s also the proper way to do it (until you are not porting from pc/console to mobile). Really, until you are not changing between radically different input sources in unity, you’re better off using Unity3d’s input system to remap controls and avoid changing code. I only used the Input management as the easiest-to-explain example, if one thinks this technique is just for that, he’s totally missing the point. This technique can (and according to some people should) be used for absolutely everything.

That’s all folks

Thanks for the read. This time no copy-paste, you get a repository with the whole project already set up and ready to use here. If you have any questions or comments please do express that either in the comments here or just hit me on twitter. And if you don’t want to lose my future stuff, consider my newsletter.

P.S.: I’m currently looking for a job, if you are interested take a look at my portfolio.

  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Pooling in unity3d – a simple tutorial

We’ve been through it: instantiations at runtime can be a huge problem. It can cause a spike in the workload of any game, and then you have to find ways to fix that when it happens. Or you can use a technique called pooling, like pros do.

you can have a lot of pools
you can have a lot of pools

What’s pooling in unity3d?

The same it should be anywhere else: instead of instantiating objects wherever and whenever you need them, you create a pool beforehand (while the loading screen is on) and then when it’s needed you grab an object from the pool.

To make a pool you’ll need 3 things:

  • a pool script
  • a pool interface
  • a pool host
    Let’s start with the trivial stuff first.

Pool interface iPoolable

It's objects in a pool, got it?
It’s objects in a pool, got it?

When an object is “in the pool” it’s better if it’s inactive in all conceivable ways. But of course the pool script should not be required to know how to inactivate every single object because that would be a maintenance nightmare. Therefore we’ll need this simple interface to be implemented by one script at the root of the pooled gameobject:

public interface iPoolable
{
  Pool source { get; set; }
  void Initialize();
  void Deactivate();
}

The source property is a reference to the pool script that holds the object’s pool, oviously. Why should the pooled object need to know that? So that it can return to the pool by itself by calling:

source.PutInPool(gameObject);

The Initialize function’s duty is to prep the object to enter the scene in an active state, just as if it was actually instantiated at the very end of the function.

The Deactivate function instead is called when the object would have been removed from the scene weren’t we pooling it. It has to minimize the impact on both memory and cpu/gpu for holding the object in the pool. This usually involves at least a SetActive(false) and a stop on all coroutines on the object if any, but one can get creative and also switch layers and stuff like that.

The pool host

This isn’t a strictly needed element for pooling to work, but if like me you don’t enjoy having a bunch of gameobjects floating around in your game’s hierarchy, you want to do this:

public class PoolHost : MonoBehaviour
{
    public static PoolHost instance;

    void Awake()
    {
        if (instance == null)
            instance = this;
        else
            Destroy(gameObject);
    }

    public static void Hold(GameObject poolable)
    {
        poolable.transform.parent = instance.transform;
    }
}

It’s just a singleton with one static function to hold the pooled gameobject inside the one this script is attached to. You could, of course, separate the pools by type, but why?

but why?

The actual Pool script

This script is designed to be used as a field in another script. This approach enables you to do all sorts of customizations, for instance your weapons can have a pool of bullets, so that you can make more weapons by changing the bullet prefab reference in the pool field.

[System.Serializable]
public class Pool
{
    Stack<GameObject> pool;
    [SerializeField]
    int initialPoolSize;
    [SerializeField]
    int expansionPoolSize;
    [SerializeField]
    GameObject prefabReference;

    public void Populate()
    {
        //stuff..
    }

    void ExpandPoolPopulation(int amount, GameObject prefabReference)
    {
        //stuff..
    }

    public GameObject Allocate()
    {
        //stuff..
    }

    public void PutInPool(GameObject handled)
    {
        //stuff..
    }
}

As you can see it’s entirely serializable, so that we may edit its parameters from the inspector when we use it as a field. The initialPoolSize variable is used to set how many gameobjects we should instantiate in the Populate call, while the expansionPoolSize indicates how many should be instantiated when the pool is empity and an allocation is requested.

Guess what the prefabReference is. Right! It’s where you drag-and-drop your prefab from the project explorer.

drag-and-drop

So, the idea is that the object using this pool needs to Populate it at first, then it can Allocate instances from it and when it’s done it (or the pooled object itself) can PutInPool back the pooled thingy.

Now, let’s see the single functions:

    public void Populate()
    {
        pool = new Stack<GameObject>();
        ExpandPoolPopulation(initialPoolSize, prefabReference);
    }

This one is damn easy. It initializes the pool variable with a brand new Stack (of course you can use my garbageless list instead!), then calls ExpandPoolPopulation to instantiate the very first objects in the pool.

    void ExpandPoolPopulation(int amount, GameObject prefabReference)
    {
        for (int j = 0; j < amount; j++)
        {
            GameObject result = GameObject.Instantiate(prefabReference);
            result.GetComponent<iPoolable>().source = this;
            PutInPool(result);
        }
    }

This one is really straightforward too. It just instantiates the prefab a number of times, sets the source for the object and then puts it in the pool. It’s as obvious as it gets.

    public void PutInPool(GameObject handled)
    {
        handled.GetComponent<iPoolable>().Deactivate();

        handled.SetActive(false);

        handled.transform.position = Vector3.zero;
        handled.transform.rotation = Quaternion.identity;
        handled.transform.localScale = Vector3.one;

        PoolHost.Hold(handled);

        pool.Push(handled);
    }

Here the first thing to do is to call the Deactivate function through the iPoolable interface so that it performs the object specific stuff, then we take care of the operations that can be done on every single gameobject, like moving it in the poolHost so that our hierarchy is clean. Obviously you don’t necessarily have to reset the transform values, but if that’s something that causes you problems, well, you are doing something very wrong.

Last thing we do, is to put the reference to the gameobject inside the pool stack, so that its ready to be used.

    public GameObject Allocate()
    {
        if (pool.Count <= 0)
            ExpandPoolPopulation(expansionPoolSize, prefabReference);

        GameObject result = pool.Pop();

        result.SetActive(true);
        result.GetComponent<iPoolable>().Initialize();
        return result;
    }

Now that we know how the stuff gets inside the pool we can look to how it’s taken out of it. The allocate function first of all checks wether the pool is empity or not. It it’s empity you need more stuff, so you have to expand it.
If this allocation is too much for you, just raise the initialPoolSize and put an error message here, but you are more likely to be better off this way.

Then it recovers the gameobject instance from the pool and initializes it so that it’s prepared just as if it was instantiated right now and returns it to whatever script called this function.

That’s all folks!

Thanks for the attention, copy-pasteable code is just ahead. Remember that the populate function is quite expensive so you’ll probably need to use it behind a loading screen, if you don’t need to then you probably don’t need pooling either.

For any question please don’t hesitate to contact me on my twitter account, and if you don’t want to miss my next tutorial consider subscribing to my Newsletter!

And by the way, I’m currently looking for a job, if you think you may have one for me, take a look at my portfolio!

public interface iPoolable
{
  Pool source { get; set; }
  void Initialize();
  void Deactivate();
}


public class PoolHost : MonoBehaviour
{
    public static PoolHost instance;

    void Awake()
    {
        if (instance == null)
            instance = this;
        else
            Destroy(gameObject);
    }

    public static void Hold(GameObject poolable)
    {
        poolable.transform.parent = instance.transform;
    }
}


[System.Serializable]
public class Pool
{
    Stack<GameObject> pool;
    [SerializeField]
    int initialPoolSize;
    [SerializeField]
    int expansionPoolSize;
    [SerializeField]
    GameObject prefabReference;

    public void Populate()
    {
        pool = new Stack<GameObject>();
        ExpandPoolPopulation(initialPoolSize, prefabReference);
    }

    void ExpandPoolPopulation(int amount, GameObject prefabReference)
    {
        for (int j = 0; j < amount; j++)
        {
            GameObject result = GameObject.Instantiate(prefabReference);
            result.GetComponent<iPoolable>().source = this;
            PutInPool(result);
        }
    }

    public GameObject Allocate()
    {
        if (pool.Count <= 0)
            ExpandPoolPopulation(expansionPoolSize, prefabReference);

        GameObject result = pool.Pop();

        result.SetActive(true);
        result.GetComponent<iPoolable>().Initialize();
        return result;
    }

    public void PutInPool(GameObject handled)
    {
        handled.GetComponent<iPoolable>().Deactivate();

        handled.SetActive(false);

        handled.transform.position = Vector3.zero;
        handled.transform.rotation = Quaternion.identity;
        handled.transform.localScale = Vector3.one;

        PoolHost.Hold(handled);

        pool.Push(handled);
    }
}

 

  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  

Event system: tutorial for Unity3D & C#

  • Part 1: basics event system [you are here]
  • Part 2: event picker drawer for in-editor usage
  • Part 3: debugging with platform dependant compilation
  • Part 4: multiple dispatchers
  • Part 5: optimization

Today I’ll start presenting you the single most useful piece of code that I’ve ever written. Since writing it I used it in every single project I’ve made, however simple. Even in game jams.
I’m speaking of an Event System. A class with no other purpose than to let other objects communicate with each other, with as little overhead as possible. And it’s implemented with delegates.

And it’s way better than SendMessage, if you ask me.

event_driven_programming

What’s an Event System?

Those of you who already know, just skip this paragraph. Still with me? good. The main problem you’ll have with SendMessage is that it needs to use a method’s name as an input. So the object sending the message not only needs to know what method should be invoked by the receiver, but also his name. In a case sensitive way. Want to change that name? too bad, the IDE won’t change the string for you. You’ll have to remember every single one of those and do it by yourself… or never change a function name ever again. Or remove one.

Sounds bad? it is. It’s a maintenance nightmare. Plus, it uses strings. Fuck strings. Strings are evil. They use your memory, trigger your garbage collector and spit on your mother. Never use them unless at gunpoint… and even then think twice about it and instead use an enum.ToString() if you can.

So what’s the solution? we need something more like this: you need to send a message between objects (or scripts) when a “thing” happens. So the scripts in the other object react to the “thing”. The caller script doesn’t need to know who or how will do anything in reaction to the “thing”. It just needs to shout out “Hey! I have a thing here!” and eventually how big the “thing” is. For instance, “Hey! I have a 3.5 Damage here!”. Then the health script subtracts the damage and the particle script spills blood everywhere. But the collider doesn’t need to know that. The “thing” is an Event. Shouting is a Broadcast. The reactions are called Callbacks or Handlers.

But this is nothing I invented, you can just study it here or here, or even here.

What’s a Delegate?

As before, if you know already, just skip ahead. Delegates are something I wish they did teach me in university, because they are just awesome. To put it bluntly: in C# you can treat functions as if they were variables and pass them as an argument to other functions. This means that you can change behaviours of an object at runtime. Or have an object hold and call a function without it even knowing what it does. Absolute decoupling. A maintenance heaven.

Before you can use a delegate, you first need to declare its type. Which means telling the compiler which return type and what arguments will be assigned to it. Not its name. Not its content. Just the signature structure. Of course, if you use as a signature something like:

public delegate object nameFunct(object o);

you can then pass anything and get anything (but say goodbye to compiler type-checks).

After you have declared a delegate type, you can then declare a delegate variable and assign to it a function with a matching signature. Just like you would do with any other variable. If you still need to delve deeper you can go here or here.

Get on with it!

gowi-2

Now, if you have seen my portfolio the event system there can be quite intimidating, but don’t worry, we won’t be doing that version right now. We’ll start with version 0.0.3 while that one is 1.0.1 [edit: this was before optimizing for the last part of the tutorial]. That makes about 100 rows of code and 20 headaches of difference.

Before we get to the main class, the event dispatcher, let’s define some stuff we’ll use there.

public delegate void gameEventHandler(eventArgExtend e);

This will be our event signature. Nothing to return because we don’t want the event sender to have anything to do with the receivers. The event type is this thing here:

public class eventArgExtend : System.EventArgs { }

Why didn’t I use directlySystem.EventArgs? Because in the future I may want to add something between those parentheses and when it happens it will cost me nothing to do so. Had I used directly that type it could require more work to do it.

Now, let’s get to something more interesting: defining the events themselves. To do so I’ll use something infinitely superior to strings: enums.

public enum eventChannels
{
    inGame
}
public enum inGameChannelEvents
{
    thing
}

Now we’ll need a comfortable way to pass this information to the dispatcher. For this I just created a class with a static function:

public class ChannelEnums
{
    public static Dictionary<eventChannels, System.Array> getChannelEnumList()
    {

        Dictionary<eventChannels, System.Array> enumChannelEventList = new Dictionary<eventChannels, System.Array>();
        enumChannelEventList.Add(eventChannels.inGame, System.Enum.GetValues(typeof(inGameChannelEvents)));
        return enumChannelEventList;
    }
}

Notice: adding a channel requires to add a new enum type, and there is no automated way to set a link between an enum value ineventChannelsand an other enumtype. So for each channel you need to add, you’ll have to write a new row of code like the one just before thereturn.

What we did here is to create a static function for the dispatcher. The function will recovery every event channel and every corresponding array of values, so that we can initialize the list of listeners in the dispatcher. All in the nice form of a Dictionary.

Now let’s get to the Event System

Our event system needs to be usable at EVERY stage of game play. This includes the Awake function of the first objects to be present in the first scene. Which means that I can’t use the Awake function to initialize the event system, or I would get in a race condition. That’s fucked up. But years of Unity3D ninjutsu allowed me to discover a precious thing: default values are initialized before Awake, and you can get them with static functions.

public class eventHandlerManager : MonoBehaviour
{
    static Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> ListenerFunctions = initializeDicts();

What’s thatinitializeDicts? we’ll see later. For now just look at the type of ListenerFunctions: it’s a dictionary of dictionaries. It allows us to index gameEventHandler delegates first by channel and then by event.

Now we can write the key functions of the dispatcher: one to raise an event, one to add a delegate as listener, one to remove it.

public static void Broadcast( eventChannels evType,Enum ev,eventArgExtend e) 
	{
		ListenerFunctions[evType][ev](e);
	}
	
	public static void AddListener(eventChannels evType,Enum ev, gameEventHandler eventListener)
	{
		ListenerFunctions[evType][ev]+=eventListener;
	}
	public static void RemoveListener(eventChannels evType,Enum ev, gameEventHandler eventListener)
	{
		ListenerFunctions[evType][ev]-=eventListener;
	}

Why are they all static? because that way you don’t need to get the other classes to find the instance. Yes, this is limiting: you can’t have a damage event that only gets notified to one character. But for something more selective we’ll need to make a lot of changes, for the time being just add an identifier as field in the argument. Then have the receivers check that value. We’ll get back to that in future tutorials.

This is all that’s needed on the outside to use this event handler. Other classes that want to react to an event just need to declare a function that matches thegameEventHandlersignature and then invoke theaddListenerfunction giving that function as the last argument (without parentheses), and do the same for removal like this:

eventHandlerManager.AddListener(eventChannels.inGame, inGameChannelEvents.thing, onThing);

The broadcast use is even simpler:

eventHandlerManager.Broadcast(eventChannels.inGame, inGameChannelEvents.thing, new eventArgExtend());

So, now we’re almost done. There is just one last detail for the magic to fully work: how do we initialize and cleanListenerFunctions?

    public void OnDestroy()
    {
        ListenerFunctions = initializeDicts();
    }

    static Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> initializeDicts()
    {
        Dictionary<eventChannels, Array> enumChannelEventList = ChannelEnums.getChannelEnumList();
        Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> result = new Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>>();
        foreach (var val in (eventChannels[])Enum.GetValues(typeof(eventChannels)))
        {
            result.Add(val, new Dictionary<Enum, gameEventHandler>());
            foreach (var ev in enumChannelEventList[val])
            {
                result[val].Add((Enum)ev, new gameEventHandler(delegate (eventArgExtend e) { }));
            }
        }
        return result;
    }

Wait a minute: did I initialize ListenerFunctions on destroy? Yes, because that is a static field. It will survive to the existence of the eventHandlerManager instance. And since that should only happen on a scene load, I can be sure that nothing should stay in the dictionary and that the new scene has a ready new clean slate to work on when the first Awake is called.

The initialization works by first getting the enum data from the static function we defined before in ChannelEnums, then using that data to initialize every field of the dictionary with an empitygameEventHandler; this way we can later add the Handlers with a+=instead of checking for a null field every time.

That’s all folks!

Not really. Actually there is a lot more that we can add to this class, mainly for debugging purposes, plus the “local” version of the event dispatcher that I mentioned before. But this tutorial is already huge, so maybe it’s better to deal with that stuff next week. If you want to be sure not losing it, subscribe to my newsletter. For any feedback comments are below or you can just add me on twitter.

using System;
using System.Collections.Generic;
using UnityEngine;

public class eventHandlerManager : MonoBehaviour
{
    public static Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> ListenerFunctions = initializeDicts();

    public static void Broadcast(eventChannels evType, Enum ev, eventArgExtend e)
    {
        ListenerFunctions[evType][ev](e);
    }

    public static void AddListener(eventChannels evType, Enum ev, gameEventHandler eventListener)
    {
        ListenerFunctions[evType][ev] += eventListener;
    }
    public static void RemoveListener(eventChannels evType, Enum ev, gameEventHandler eventListener)
    {
        ListenerFunctions[evType][ev] -= eventListener;
    }

    public void OnDestroy()
    {
        ListenerFunctions = initializeDicts();
    }

    static Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> initializeDicts()
    {
        Dictionary<eventChannels, Array> enumChannelEventList = ChannelEnums.getChannelEnumList();
        Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>> result = new Dictionary<eventChannels, Dictionary<Enum, gameEventHandler>>();
        foreach (var val in (eventChannels[])Enum.GetValues(typeof(eventChannels)))
        {
            result.Add(val, new Dictionary<Enum, gameEventHandler>());
            foreach (var ev in enumChannelEventList[val])
            {
                result[val].Add((Enum)ev, new gameEventHandler(delegate (eventArgExtend e) { }));
            }
        }
        return result;
    }
}

public enum eventChannels
{
    inGame
}

public enum inGameChannelEvents
{
    thing
}

public class eventArgExtend : System.EventArgs { }

public delegate void gameEventHandler(eventArgExtend e);

public class ChannelEnums
{
    public static Dictionary<eventChannels, System.Array> getChannelEnumList()
    {

        Dictionary<eventChannels, System.Array> enumChannelEventList = new Dictionary<eventChannels, System.Array>();
        enumChannelEventList.Add(eventChannels.inGame, System.Enum.GetValues(typeof(inGameChannelEvents)));
        return enumChannelEventList;
    }
}

 

  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •  
  •