{"id":355,"date":"2021-05-08T20:13:12","date_gmt":"2021-05-08T20:13:12","guid":{"rendered":"https:\/\/bronsonzgeb.com\/?p=355"},"modified":"2021-05-08T20:13:13","modified_gmt":"2021-05-08T20:13:13","slug":"model-view-controller-pattern-for-in-game-ui","status":"publish","type":"post","link":"https:\/\/bronsonzgeb.com\/index.php\/2021\/05\/08\/model-view-controller-pattern-for-in-game-ui\/","title":{"rendered":"Model View Controller Pattern for in-game UI"},"content":{"rendered":"\n

This article describes an approach to structuring UI in Unity. This approach is based on the Model View Controller (MVC) pattern, but it’s slightly adapted for Unity. This isn’t the only way to structure your UI, but it has worked well for all my previous Unity games.<\/p>\n\n\n\n

Model View Controller Pattern<\/h2>\n\n\n\n

In case you’re unfamiliar with the MVC pattern, I’ll summarize it. MVC is a pattern used to separate UI, Data, and functionality. The Model holds the data to display, the View manages the layout, and the Controller handles the functionality. This separation (theoretically) makes it easier to change each part independently. For example, you could quickly redesign the layout without touching the data or the functionality. That’s MVC in a nutshell, so let’s look at how we can adapt this pattern for Unity UI.<\/p>\n\n\n\n

MVC for Unity<\/h2>\n\n\n\n

First off, let’s talk about the Model. The Model is nothing but a big data container. There are several different ways you could achieve this, and to be honest, they’re probably all valid. It depends on your use case. However, I prefer to use a Scriptable Object.<\/p>\n\n\n\n

Scriptable Objects as a Model<\/h2>\n\n\n\n

The advantage of using a Scriptable Object (SO) as your Model comes down to flexibility, testability, and ease of use.<\/p>\n\n\n\n

Scriptable Objects can either be created at runtime or in the editor. This feature allows you to test different scenarios with very little code. For example, if you wanted to try several different UI scenarios, you could create a new Scriptable Object to represent each one. Then, it’s just a matter of switching between them and viewing the result. Additionally, if you need to pull data from a spreadsheet or database, you could accomplish that by creating an SO at runtime and filling it with the retrieved data. In other words, using an SO as your Model won’t force you into an awkward place down the line. It’s adaptable to any scenario. <\/p>\n\n\n\n

Finally, Scriptable Objects are first-class citizens in the Unity Editor. What I mean by that is that they interact well with the Editor ecosystem, especially the Inspector. As a result, it’s easy to manipulate your data, which isn’t the case for databases or raw JSON. By the way, your Model could be as simple as an object with a list of variables:<\/p>\n\n\n\n

public class DataModel : ScriptableObject\n{\n    public int Coins;\n    public int Gems;\n    public int Tickets;\n    public int Friends;\n    \/\/...etc\n}<\/code><\/pre>\n\n\n\n
The View Controller<\/h2>\n\n\n\n
As for the view controller, it’s a MonoBehaviour<\/code> at the root of our prefab. If you haven’t read my previous two articles on the Main Loop and Structured Prefabs, I recommend you do so. The way I structure View Controllers is a Structured Prefab. The view controller is in charge of binding all your UI pieces to their corresponding variables. By the way, there are essentially two strategies for hooking up UI, polling or event-based. Both approaches are valid so let’s look at the pros and cons.<\/p>\n\n\n\n
Polling-based UI<\/h2>\n\n\n\n
If you have a simple UI, using a polling-based method is much simpler. This works by simply setting the UI to the most recent data every frame. For example, if you have a coin counter in your in-game UI, just set the current number of coins in Update<\/code>.<\/p>\n\n\n\n
public class GameViewController : MonoBehaviour\n{\n    [SerializeField] CoinCounterPanel _coinCounterPanel;\n    [SerializeField] GameViewModel _model;\n    \n    public void Update()\n    {\n        _coinCounterPanel.SetText(_model.coins);\n    }\n}<\/code><\/pre>\n\n\n\n
This type of polling-based UI system is easy to read and understand. Additionally, you don’t have to worry about managing state, and your UI will always be in sync. There are some disadvantages though. For one, you may be wasting CPU cycles to set data that hasn’t changed. Also, depending on the UI, the code might become very lengthy. However, given that this code tends to be straightforward, this may not be an issue.<\/p>\n\n\n\n
Event-based UI<\/h2>\n\n\n\n
In an event-based system, the UI updates whenever an event occurs that changes your data.<\/p>\n\n\n\n
public class CoinCounterPanel : MonoBehaviour\n{\n    GameViewModel _model;\n    [SerializeField] Text _text;\n\n    public void OnCreated(GameViewModel model)\n    {\n        _model = model;\n        _model.OnCoinsValueChanged += OnCoinCountChanged;\n    }\n\n    void OnDestroy()\n    {\n        _model.OnCoinsValueChanged -= OnCoinCountChanged;\n    }\n\n    void OnCoinCountChanged(int previous, int current)\n    {\n        _text.text = $\"Coins: {current}\";\n    }\n}<\/code><\/pre>\n\n\n\n
This system is a little more complicated because you have to bind the data to the UI. In other words, you need to make sure that a specific method executes every time the bound variable changes. In the above example, we need OnCoinCountChanged<\/code> to run every time the coins<\/code> value changes. To do that, you need to keep track of every time the coins<\/code> value changes. In my example, I did this by wrapping coins<\/code> in a Setter that calls an event. So the Model code changes from this:<\/p>\n\n\n\n
public class GameViewModel : ScriptableObject\n{\n    public int Coins;\n}<\/code><\/pre>\n\n\n\n
To this:<\/p>\n\n\n\n
public class GameViewModel : ScriptableObject\n{\n    [SerializeField] int _coins;\n\n    public int Coins\n    {\n        get => _coins;\n        set\n        {\n            int previous = _coins;\n            _coins = value;\n            OnCoinsValueChanged?.Invoke(previous, _coins);\n        }\n    }\n\n    public event Action<int, int> OnCoinsValueChanged;\n}<\/code><\/pre>\n\n\n\n
Hopefully, this example demonstrates the added complexity of the event-based approach. Not to mention, using this code, you could still modify the _coins<\/code> value in the Inspector, and it wouldn’t notify the UI, so it’s not even a comprehensive solution. This is a lot of code to manage just one variable, so this won’t scale. Let’s build a better system.<\/p>\n\n\n\n
I created an ObservableVariable type, named after the Observer pattern:<\/p>\n\n\n\n
[Serializable]\npublic class ObservableVariable<T>\n{\n    [SerializeField] T _value;\n\n    public event Action<T, T> OnValueChanged;\n\n    public T Value\n    {\n        get => _value;\n        set\n        {\n            T previous = _value;\n            _value = value;\n            OnValueChanged?.Invoke(previous, _value);\n        }\n    }\n}<\/code><\/pre>\n\n\n\n
It’s a generic version of the same code we used to make our coins<\/code> variable observable earlier. Now we can modify our Model to look like this:<\/p>\n\n\n\n
public class GameViewModel : ScriptableObject\n{\n    public ObservableVariable<int> _coins = new ObservableVariable<int>();\n}<\/code><\/pre>\n\n\n\n
By the way, you may have noticed that I haven’t shown the GameViewController<\/code> code for our event-based system. That’s because it no longer does any work beyond initialization. Once the UI is bound to the data, it’s completely passive. In other words, it just waits for changes to occur rather than actively looking for modifications. So it ends up looking like this:<\/p>\n\n\n\n
public class GameViewController : MonoBehaviour\n{\n    [SerializeField] HealthPanel _playerHealthPanel;\n    [SerializeField] CoinCounterPanel _coinCounterPanel;\n\n    public void OnCreated(Health playerHealth, GameViewModel model)\n    {\n        _playerHealthPanel.OnCreated(playerHealth);\n        _coinCounterPanel.OnCreated(model);\n    }\n}<\/code><\/pre>\n\n\n\n
Relationship Inversion<\/h2>\n\n\n\n
Right now, GameMain<\/code> initializes GameViewController<\/code> through a direct reference. As a result, if GameViewController<\/code> is missing, then initializing the game will fail. However, depending on the situation, you may find that you want something more flexible. Let’s modify the GameViewController<\/code> to register itself with GameMain<\/code> rather than the other way around.<\/p>\n\n\n\n
public class GameViewController : MonoBehaviour\n{\n    [SerializeField] HealthPanel _playerHealthPanel;\n    [SerializeField] CoinCounterPanel _coinCounterPanel;\n\n    public void Start()\n    {\n\tGameMain.NotifyGameViewControllerWasCreated(this);\n    }\n    \n    public void OnCreated(Health playerHealth, GameViewModel model)\n    {\n        _playerHealthPanel.OnCreated(playerHealth);\n        _coinCounterPanel.OnCreated(model);\n    }\n}<\/code><\/pre>\n\n\n\n
And here’s a stripped-down version of GameMain<\/code> to illustrate how this works:<\/p>\n\n\n\n
public class GameMain : MonoBehaviour\n{\n    public static event Action<GameViewController> OnGameViewControllerCreated;\n\n    void Awake()\n    {\n        OnGameViewControllerCreated += InitializeGameViewController;\n    }\n\n    void OnDestroy()\n    {\n        OnGameViewControllerCreated -= InitializeGameViewController;\n    }\n\n    public static void NotifyGameViewControllerWasCreated(GameViewController gameViewController)\n    {\n        OnGameViewControllerCreated?.Invoke(gameViewController);\n    }\n\n    void InitializeGameViewController(GameViewController gameViewController)\n    {\n        gameViewController.OnCreated(_player.Health, _model);\n    }\n}<\/code><\/pre>\n\n\n\n
The idea is that when the GameViewController<\/code> awakes, it’ll notify GameMain<\/code> who will then initialize it through the OnCreated<\/code> method. I chose to orchestrate this through static events, but you may have a solution that’s more suited to your game. Now, no matter when GameViewController<\/code> gets added to the scene, it’ll be initialized correctly. However, it’s worth mentioning that this flexibility leaves room for mistakes because the game won’t throw an error if the GameViewController<\/code> is missing.<\/p>\n\n\n\n
I brought up the idea of inverting the initialization relationship to demonstrate that when designing software, or anything for that matter, every decision has benefits and drawbacks. There’s never a universally perfect design decision; there are only decisions that best suit your given constraints. In this case, we gain flexibility but introduce the possibility of human error.<\/p>\n\n\n\n
One last thing before I go, you may be wondering what happened to the View part of MVC. Well, given that the View is in charge of layout, the View is your UI Canvas and all the accompanying UI elements. In my case, I usually make this a child of my View Controller prefab.<\/p>\n\n\n\n
If you’re interested, check out the <\/strong>accompanying project<\/strong><\/a> on Github. If you <\/strong>join my mailing list<\/strong><\/a>, I’ll notify you whenever I post a new article. If you’d like to see more ways to architect events, this time using Scriptable Objects, check out <\/strong>this Devlog<\/strong><\/a> from Unity’s Open Projects initiative.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"
This article describes an approach to structuring UI in Unity. This approach is based on the Model View Controller (MVC) pattern, but it’s slightly adapted for Unity. This isn’t the only way to structure your UI, but it has worked well for all my previous Unity games. Model View Controller Pattern In case you’re unfamiliar […]<\/p>\n","protected":false},"author":1,"featured_media":359,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[28,32,1],"tags":[30,29,33,5],"class_list":["post-355","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-architecture","category-ui","category-unity-programming","tag-architecture","tag-scriptable-objects","tag-ui","tag-unity"],"_links":{"self":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/355","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/comments?post=355"}],"version-history":[{"count":3,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/355\/revisions"}],"predecessor-version":[{"id":361,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/posts\/355\/revisions\/361"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media\/359"}],"wp:attachment":[{"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/media?parent=355"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/categories?post=355"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bronsonzgeb.com\/index.php\/wp-json\/wp\/v2\/tags?post=355"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}