UnityMVC

UnityMVC is a library for MVC Pattern, which is almost behave like ASP.NET MVC. This library is intentionally made to work mostly with User Interface management, but possible to work on other scenerio.

<p align="center"> <img src ="https://i.ibb.co/8079VMG/xs-optimized-social-banner.png"/> </p>

Here are the key features of UnityMVC:

• MVC pattern implementation for user interface management
• Convention-based routing for navigation between views
• Support for passing data to controllers and views
• Automatic loading and instantiation of view prefabs
• Reflection-based execution of controller actions
• Support for partial views
• Middleware support for executing operations before processing routes or instantiating views
• Navigation Events (OnNavigated, BeforeNavigate)
• Layout functionality for handling common UI layouts
• Easy creation of controller classes using the provided context menu
• Scaffolding feature for generating view classes and registering view prefabs
• Zenject (DI Library) Support
• Route History Debugger

Installation

• Open Package Manager in Unity (Windows/Package Manager).
• Click on Plus Icon -> Add Package from git URL.
• Paste the following link - https://github.com/SrejonKhan/UnityMVC.git
• Click Add.

Sample Project

If you are interested in exploring practical examples and use cases of the UnityMVC library, we have a dedicated sample project repository available. The UnityMVC Sample Project provides a collection of samples that showcase the features and capabilities of the UnityMVC library in action.

In the sample project, you will find demonstrations of various features of the library. It's a great resource for getting hands-on experience with UnityMVC and understanding how it can enhance your Unity projects.

To access the UnityMVC Sample Project repository, please visit this repository.

We encourage you to explore the sample project and leverage the provided examples as a reference for your own UnityMVC implementations. If you have any feedback or suggestions regarding the sample project, feel free to open an issue or contribute to the repository.

History

MVC (Model-View-Controller) is a widely used Software Design Pattern. It is commonly used for developing user interfaces that divide the related program logic into three interconnected elements.

As name suggests, there is 3 main components in MVC. They are -

Model

Model represents an object that contains data. It contains no logic describing how to present or process data. It just contains data.

View

View is the representation of Model's data, aka User Interface. View knows how to access Model's data.

Controller

Controller exist between the view and model. It listens to events triggered by the view (or another external source) and executes the appropriate reaction to these events. Controller handle user interaction, work with model and ultimately select a view to render.

MVC in Unity

MVC in Unity acts same as described above. In term of View, the View actually is prefab of User Interface, loaded by addressable. Model and Controller acts the same as described above.

Navigation/Routing

For navigating to different views, we use convention based routing like ASP.NET MVC. For example, if we want to navigate to Settings in Main Menu, routing path would be like -

MVC.Navigate("Menu/Settings");

The convention of this routing URL is - "ControllerName/ActionName/Id". Each Action is basically a view of that particular controller. In the following example, the Controller is Menu Controller, View is MenuSettingsView and Model can be Settings.

In UnityMVC, you can pass other data as arguments also, which can be processed/manipulated in corresponding Controller action.

MVC.Navigate("Menu/Settings/en-bn", new Settings(defaultValue));

Getting Started

If you want to get started quickly, it would be recommended to at least skimming through this example section, which will cover most of the features. You can consider reading Creating a Main Menu with MVC section for step-by-step guide.

Or, If you want see all available reference, please jump to Reference.

How does it work?

UnityMVC makes it easier to load User Interface (it can be anything, any prefab), a.k.a Views without making many references or boilerplate work. Simply, if you want to load Settings panel in Main Menu, you just have to call MVC.Navigate("Menu/Settings"); to load/instantiate Settings UI.

This is a diagram that is TL;DR of the explanation -

As Conventional Based Routing refers, first part of the URL is Controller name. So, MVC will try to resolve first part of the URL when Navigate() get called. UnityMVC will look for that Controller class, in our case MenuController. UnityMVC uses Reflection behind the scene to execute most of it's task. UnityMVC caches all MonoController classes from all available assembly, at the very first Awake() call of Scene lifetime. It also try keep all instances of all controller classes in the scene, as MonoController (MonoBehaviour) can't be instantiated with new keyword. This finding instance query happens in a particular order to avoid full hierarchy combing for a instance. MVC will first try to get reference (GetComponent()) from MvcContainer gameobject, which has MvcInitializer as it's Component. If the reference is not there, it will then search in childs (GetComponentInChildren()), even if not found, it will search whole scene (FindObjectOfType()). In worst, if the scene also doesn't have any instance, the following instance will be created by UnityMVC while resolving particular request in Runtime. To avoid overhead, it's recommended to keep instances of Controller classes in Scene, as a child or flat level component of MvcContainer GameObject.

This is how UnityMVC resolves first part of routeUrl, that means UnityMVC has now corresponding Controller class to proceed further. After resolving first part, it's time for resolving the second part of the Url, which basically is the Action name of corresponding Controller. Actions are methods in Controller class, that returns ViewResult object. Action basically handles all sort of work for that particular call, select view, load and return it. In our case, our action method is Settings(). In this part of resolving, UnityMVC will invoke Settings() in HomeController. Settings() action can perform some task, prepare model (optional) and select proper view*. Yes, Action method can select any View to show. View() in MonoController has some overloaded methods, where some of them accept View Name in their argument. If any view name has not passed, UnityMVC will take CalledMethod name as View name, in our case it is Settings.

View() in MonoController now tries to load view from Addressable by generating address. Generation of address is simply done by concatenating Controller Name and View Name, combined by a forward slash (/). In our case, the address would be Home/Settings.

After loading view from Addressable, UnityMVC will instantiate it under MVC.RootCanvas or provided transform argument. After instantiation, UnityMVC will resolve the View Class, which is generally a class attached to root of View as a component. View Class is important, and it is responsible for all view oriented work for that following view. UnityMVC will first try to get it from instantiated view, if it's not added, UnityMVC will add that ViewClass to View as a component.

If there is any Model for that particular view has been passed as argument in View() method, it will be injected to View Class in Model field. Note that, all view classes are derived from ViewContainer base class, and ViewContainer has a object field of Model. So any particual View Class doesn't need to explicitly declare field for Model.

As the final step, UnityMVC invoke all methods in View Class, that has InvokeAttribute placed on them.

For Partial View, it is mostly same. In Partial View, view is not pushed to History and no Active View is being destoyed.

Controller

All Controller class should derives from MonoController. On the other hand, MonoController derives from MonoBehaviour, which let MonoController's derived class (Controllers) to be added to GameObject as Component and receive Unity messages (Awake, Start, Update, FixedUpdate).

Example -

using UnityMVC;

public class MenuController : MonoController
{
    // Start is called before the first frame update
    void Start()
    {
        // Do something in Start
    }

    // Update is called once per frame
    void Update()
    {
        // Do something in Update
    }

    // This is an Action Method
    // calling MVC.Navigate("Menu/Index");
    // will instantiate MenuIndex View
    public ViewResult Settings()
    {
        return View();
    }
}

Please note that, Index() is an Action Method for MenuController. This method will invoked when we call MVC.Navigate("Menu/Settings"). Every action method must return ViewResult object. ViewResult can be returned by calling View() method in any Controller class that derives from MonoController. This View() method also accept other arguments, please visit Reference for details.

There is a Context Menu for creating a Controller Class. It can be also done manually. For doing it quickly and without any mistakes, use Context Menu.

Create a Controller class with MVC Context Menu -

1. Right click on any empty space in Asset window.
2. Click MVC -> Create Controller Class
3. Write Contr