[NEW] Karma: An MVC framework for Unity3D

https://github.com/cgarciae/karma

What is Karma?
MVC Framework for Unity3D
Karma is an MVC framework for Unity3D. Because of how Unity is structured, it actually turns out to be an MVCP architecture (Model/View/Controller/Presenter) where the Presenter is a MonoBehaviour that serves as an intermediary between the Controller and the View. You can read more about this in MODEL VIEW CONTROLLER PATTERN FOR UNITY3D USER INTERFACES.

Based on Zenject
It's built on top of Zenject which provides Dependency Injection (DI). DI is mainly used to route the app to the desired view, it also enables us to build composable and testable systems.

Inspired by AngularJS and ASP vNext
Some of the basic constructs and code layout is inspired by other MVC frameworks such as AngularJS and ASP vNext.

Note to Game Developers
Karma uses concepts like views and presenters instead of scenes. The problem with scenes is that they are too heavy weight, there is no good way to communicate between them, changing scenes is slow (especially if you are doing UI stuff), and they aren't composable. The "Karmic" way of doing a game would be to store each level/scene in a prefab, treat it as a MVC View, store all your characters/entities in separate prefabs, and get them instantiated onto the level's view through DI.

Simple Routing System
Karma has a built in routing system that enables you to create isolated views/scenes as prefabs and easily switch between them. Using an http-like flow, a presenter can Request the router to render another view.

As Stateless as possible
Karma aims to be as stateless as possible to try to give you the guarantee that if you entered a view once with certainRequest parameters and reached a successful state, then you will always reach that same state if you pass the the same parameters. Unity3D doesn't provide by default a best practice changing from a view to another. A common way to do this is to have all possible views instantiated in the scene but only enable the current one, the problem is that you maintain state when reusing Game Objects and often end in bad states because of the many paths you need to account for. Karma keeps things simple and functional by just destroying the current view and instantiates a new next view when changing views.

Message Passing
In Karma state is mainly maintained through message passing, being as true as possible to Go's philosophy:

Don't communicate by sharing memory; share memory by communicating.

The added benefit of this is that views become configurable without depending on local storage or static variables, is in turn is very important to keep a system testable.

Pub/Sub System
All Presenters integrate a pub/sub system that enables the communication between entities on different branches and levels in the dependency hierarchy. It's a simple yet powerful message passing mechanism on channels by topic where anyPresenter can subscribe and broadcast. By convention the top level application is used as the main channel.

Folder Structure + Conventions
As many MVC frameworks, Karma tries to keep the developers sane by establishing conventions. Among these conventions are the folder structure, concepts (presenters, controllers, services, etc), code organization, a configuration mechanism (dev, prod, test environments).

Parts

• Views
  • Plain old prefabs
• Presenters
  • Handle the presentation layer
  • Extend MonoBehaviour
  • Are tied to a Prefab
  • Get instantiated on Game Objects
  • Integrate a Pub/Sub mechanism
  • Are Transient
  • Are divided as:
    • Plain Presenter (Routable)
    • Elements (Reusable)
    • Layouts (Provide context)
• Controllers
  • Handle the logic layer
  • Don't extend MonoBehaviour
  • Are Transient
  • Are 100% testable
  • Are usually coupled to a Presenter
• Services
  • Handle Resources
  • Should be Stateless
  • Are Singleton
  • Usually handle communication with a server on a particular resource, local storage, specialized logic for e.g. handling certain user inputs, etc.
• Applications
  • Handle general configuration
  • Are Presenters
  • Contain the current view
  • Can be nested to create subviews
• Router
  • Belongs to a specific Application
  • Tells the application which view to render next
  • Can store request history
• Middleware
  • Each application can configure its one pipeline
  • Each middleware can modify the Request and Response
  • Enables to e.g. create an authentication layer separate from the view itself
  • It's asynchronous so e.g. http requests can be made to the server to get extra information

Why Karma?
Unity3D doesn't give much structure
While good developers do follow certain conventions, new developers struggle to keep their project in order. Karma provides conventions for both code structure and folder organization so you can keep your project clean and productive.

Composable elements
Mainly thanks to Zenject, with Karma you can create composable elements that you can reuses through your application. Defining you all the components in your view/level directly in the hierarchy, with Karma you define each subcomponent in a separate prefab with their own presenter, and get them to you current view through DI. This way you avoid these common problems:

• Finding components in hierarchy (you can stop abusing GameObject.Find)
• Having to update prefabs that are also nested in other prefabs

Testable components
One of the major goals of Karma is testability. This is achieved through these mechanisms:

1. Configurable transient views
2. POCO Controllers and Services that are 100% mockable
3. Dependency Injection

Getting Started
Sample Project
The easiest way to get started is to clone this repository and open it with Unity3D. It contains a sample project layout with anApplication, Presenter, Controller and a Service. Just

git clone https://github.com/cgarciae/karma.git

and open the karma folder with Unity3D. Then open the scene /Assets/App/App.unity and hit play!

Integrating it with your project
The easiest way to integrate Karma with your own project is to clone this repo with

git clone https://github.com/cgarciae/karma.git

and then copy the folders /Assets/App and /Assets/Lib to your project.

Guides
Coming soon!

 

Never been a fan of putting complex frameworks into high performance applications (ie. games). I was never a huge fan of MVC in any regard though.

Most of the time they add a bunch of useless fluff at the cost of performance. I'm yet to see much need for unit tests in game development.

 

How does it compare to StrangeIoC?

 

Games aren't necessarily high performance applications. A well-featured mvc framework could provide a lot of helpful structure for games. This could be useful stuff.

As to Zenject vs Strangeioc: They're very similar these days. I prefer zenject, because I've been using it more frequently. But they both accomplish the same goal: decoupling systems and encouraging modular programming.

 

James, Karma has zero computational cost after it has instantiated a View via Zenject, therefore there shouldn't be a performance issue. In that sense its more like how server frameworks do MVC (request view -> response view -> done) than how e.g. AngularJS does MVC (continuously recomputes the DOM). At the end of the day Karma just brings some structure to the goodies Zenject offers and adds some good practices/facilities to the mix like message passing between Views, a pub/sub system to decouple modules, conventions, folder structure, options for environment configuration (development vs production), well defined layers (Views, Presenters, Controllers, Services).

That said, I use Karma in production on an AR app that uses Vuforia. Augmented Reality is very taxing since it has to do real-time image recognition and Karma has never been an issue. I am very confident it should be a problem in a problem for game development.

 

Karma really sits on top of Zenject, so the comparison here should be between DI frameworks. For Karma I guess it could even be possible to abstract away the DI framework so you can use your own, this might be interesting if there is a need for it. Under the hood Karma just uses metadata you put on your clases (Presenter, Controller, Element, etc) to build the (Di)Container for your, and along with some convention, it helps you instantiate your prefabs/views properly.

Both StrangeIoC and Zenject have a lot of features that I do not use because they overlap with Karma, but it would be interesting to know the opinion of strong Zenject users about Karma.

 

I'll make a video soon with a brief overview of Karma and explain the sample project. The Karma repository itself is the sample Unity project, you can clone it and play with it but the video should explain some the basic stuff. I'll post the video here once I record it.

 

Interesting!
Is Karma open source? How is it licensed?
Also looking forward to more documentation material

 

Explain this concept to me like I am two years old.

Use crayons if necessary.

 

This. I don't see any licensing info anywhere on Github.

 

When licensing info is missing from a public github repository, by default any github user is allowed to fork the project and read source code, but they are not allowed to redistribute the source outside of github.

That's according to github support. I investigated related issue in the past...

 

I have trouble taking people seriously when it's their first time posting and they are suggesting stuff like MVC framework for unity.

You are suggesting more complex code that's going to be harder for beginners and less productive for more experienced programmers.
The second claim is only from my personal experience, so I can't claim it is true for most people.

Anyway sorry for the hate, this code style might work for you and some people, but I doubt it will be too popular in the community.

 

I understand the two year old explanation for MVC, but if somewhere between the simple explanation and implementation you need a framework, I get the feeling the simple explanation explains jack all.

 

I agree with most of the above sentiments that this will only be useful in a few select cases and probably more useful to large teams, rather than solo or small indie development teams. These architectures in the Unity world remind me most of MVP in the web world (which was the mvc pattern built on top of web forms). Web forms like Unity you dragged and dropped controls (usually UI widgets) and you had a code behind for each webpage. The webpage in web forms had a lifecycle with "magic" methods (page load, unload, etc.). This is very analogous to Unity with Start(), Update(), etc. This is also the most similar to MVP because it's not like anything with Web forms changed they just threw the design pattern on top of the older technology it wasn't a new stack (like MVC would be later).

No doubt using Karma or StrangeIOC will marginally slow down the game, but probably not enough to be of consequence (it essentially just adds a thin layer). Unless you have a very UI heavy game (ie. hearthstone, other TCG, etc.) or have so many hands working on the project or huge complexity I can't see the two main benefits being worth it.

1. Decoupling the UI from the rest of your game.
2. More friendly to Unit Testing

For large teams or with a ton of UI screens, the benefits may be worth it. With the decoupling you can mock out the back end and really iterate on your many UIs. Large teams can also have a unit testing suite to help ensure product stability with many hands updating the same source.

For a small indie though (less than a few people) doing this will certainly slow you down and probably isn't worth it (unless you really have this design pattern baked into your brain and can't function as well inside different environments or patterns). The tight coupling in Unity makes things faster to prototype and faster to create. No need to deal with the extra layers and simply have both UI logic and game logic (game state, settings, etc) in the same monobehaviour (or different ones Unity can certainly have multiple components per object). Also, for small indies especially when there is only 1 programmer, the need for unit tests is minimized. I would hope that since a person wrote all the code himself he knows how to test it and knows the code base well.

 

Skimmed through overview. Sounds a lot like unnecessary layer of indirection to me.

Also I really disliked this sentence:

 

It's cool to separate things into dedicated areas / layers such as logic and presentation as well as just generally trying to improve the structure of the codebase. However, what usually happens with these more formal things is they are done so overboard you must learn a whole new architecture and really understand it well to make use of it. And the same basic end result can be achieved much simpler.

This kind of thing has been around for a long time now. We had the classic Three Tier Design (Application Architecture) with the Data Access Layer, Business Logic Layer (often called the Business Objects Layer) and the Presentation Layer (GUI). I actually found that sensible and used it. Then we got a new buzzword and a sort of forced implementation pattern with MVC. I've used that for projects at work as well.

Three Tier Design I think is good. MVC... I am kind of iffy about. It's basically a framework for TTD delivered in a way that made sense to someone else. Not saying it is horrible just saying anyone can do the same basic thing themselves and probably in a more sensible manner.

Still... I am not knocking your efforts. Obviously this is something that is important to you and kudos to you for taking the initiative to implement this in Unity. It probably can't hurt to have another option for people to check into. Personally, I won't use it but that doesn't mean it doesn't have any value. Just that I do not see a need for it in my own Unity work.

 

Thanks for the comment. I coded the same app twice, in the second iteration I coded Karma as a wrapper around Zenject and the results where clear: way less bugs, clear separation of concerns, reusable components made really speed things when it applied. The other thing is clarity, the project is very well structured, I have to worry about less things because architecture is there.

But I'd like to know if I can improve Karma to suite the communities needs. Karma powers my own app and I am REALLY happy with it. Hope it can help other too.

 

Yeah, I get that feeling some times. I'd actually recommend to start only using Presenters and Services at the beginning, and start creating/moving code to Controllers as you need testing. Implementing the full MVCP initially is very costly.

About the quote, it was a reflection about me when I first started to coded in Unity, I consider that I've always had good algorithmic ability, but had no I idea how to structure a project (my formal career is Mathematics), Unity didn't help in that regard.

 

Sorry, forgot the license issue. I am starting to document Karma as I detach it from the project that gave birth to it; it co-evolved with my AR app that is in production. More documentation including a video will come as soon as possible.

 

If its the first time you use the MVC pattern maybe reading about it in a web framework like Ruby or a frontend framwork like AngularJS might help.

At first the pattern looks like its a lot of indirection to do basic stuff, it pays out because organization can help you reduce bugs, its just perfect if you need testing. If you want to add more clarity and structure to your code MVC might be just what you need. Personally I like code quality, Karma has certainly helped me in that regard, I am not saying that not using a framework makes your code bad, its just that following a structure can help you a lot to that end.

 

Usually goes like this:

You have Data. The data is a Model.
You have a Thing that displays a representation of Data. That is a View.
You have one Other Thing that modifies the Data. That Other Thing is a Controller.

In my experience, (in standalone applications) this kind of approach is useful when dealing with databases. You have a relational database that stores, say, your list of employees in some way mortals were not meant to know (though you suspect it was totally programmed in ancient sumerian). You have views that can pull that data and display it as tables, trees, etc, except that views don't necessarily have an ability to mess up the data from the database. And then you have Actions that call Controller to mess up the Data. Those Actions are bound to buttons on forms, etc. Controller is a piece of code that knows how to boss around the database, but doesn't know how the database itself works. This approach allows you to isolate Databse from Controller and Views into separate groups and put different guys to work on each one of them. View can't easily break controller, database can't break a view, etc.

Something like that.
----
I don't see much use for that in unity, because unity pretty much provides a virtual environment for autonomous physics-driven agents that can maintain references to each other. It makes sense not to think in terms of traditional programming. You're not developing a program. You're making a robot swarm, and write a program for every single robot in the swarm. Then you make them act together.

MVC would have limited use in some edge cases, I suppose. I just don't see a use for it in an action game, for example.

In case of Unity, instead of enforcing structure, I would advise to embrace chaos and learn to control it. In this kind of application this approach seems to work better. In my opinion, anyway.

 

You should probably find a real two year old to practice on.

I've yet to use specific MVC frameworks in Unity. Or dependency injection. I can't find someone who can explain why bending unity into such an unnatural structure will help.

MVC thinking, on the other hand, can be a useful technique. Seperating your code into 'getting input', 'doing some calcs' and 'displaying stuff' can be a useful way to keep things modular.

I also encourage MVC thinking for games that are not well represented by Unity's in built stuff. Say a board game or a deck of cards.

 

This.

When I first started using Unity one of the things I started out trying was dependency injection. The sexy syntax made it feel really good, it felt like real code if you know what I mean. The reality though, was it was a crazy elaborate scheme to hide the fact that you were essentially calling GetComponentInParent.

I think the reason frameworks are so popular is that good ones can feel really good to use. But it doesn't mean they're actually useful. Like @BoredMormon says, it's often better to just really understand the principals and apply them sensibly, rather than use a dedicated framework and the formality that they enforce.

 

Karma (partly thanks to Zenject) is good at two things:

1. Easily instantiating correctly configured prefabs. Since there is convention of where prefabs are stored and their names you don't even have to specify where the prefab is, just the type.
   
2. Providing means of communication between the different entities in the view.

I doubts any game lacks those needs. Check out the sample project by just cloning karma and open it in the Unity editor. I'll make a video soon to clarify stuff.

 

In Karma you mostly use DI to instantiate stuff in a correct order, at the same time guaranteeing that components have references to the other components they need. Also Karma builds most of your DiContainer for you since there are certain conventions + metadata you use, you you just put things in the right place and you don't have to deal with configuration phase of DI. Its also incredibly modular since you can e.g. create an interface or super class for certain type of entities (say a LevelEnemyOrchestrator super class) and pass different instances depending on the situation (each type of level implements it differently).

 

You are right. But I actually didn't try to explain because I don't think you can really GET IT by reading about it in a forum. Rather you have to use it and compare it to how you currently code.

 

Just curious, @cgarciae - how long have you been making games, what are some examples of where your work and the challenges involved?

Obviously, different kinds of games have very different needs, I'm just curious what your frame of reference is and what the games you've built are like.

What were the primary challenges you were trying to overcome?

I can't help but think that you may be trying to approach game dev perhaps a bit too much like web dev. Although, for many kinds of games this may not be a bad approach.

 

As I've stated before, I use Unity to create Augmented Reality and Virtual Reality Apps, not games. That said, I believe that you can use the MVC pattern for coding games. Virtual Reality is specially game like and I had no trouble with it. Of course I don't claim to be an expert in coding games, but I've been using Unity3D for 5 years and feel confident about it with Karma.

My primary challenge was to have an easy way to create complex views that involved interactions with 3D and 2D objects in a composable manner, also to have a mechanism to communicate information between views (the router), and communicate information between elements with a view (pub/sub).

 

Having used mvc and other architectures and frameworks (depending whats the right tool for the job) in unity I can say in my case it always saved a lot of time/money in the long run. It is easier to plan, test and maintain if you have a clear separation of concerns and a well structured codebase.
I wouldn't use it for prototyping though.

 

Smells a lot like UE4 scheme, where "prefab" instead of being an Object instance is an object class and object names are unique. I worked with that Unreal scheme before, it makes less sense than unity's prefabbed approach.

I'm not seeing it, sorry.

 

Its actually more akin to how ASP MVC organizes Views (templates) and Controllers. In Karma prefabs are Views, and we have a Presenter layer in addition to Controllers. I am really not reinventing the wheel here. The other things is that Karma doesn't do anything that Zenject can't do, its just helps you build the DiContianer via annotations and conventions on where the prefabs are stored, on top of that it gives you a router to instantiate new prefabs with Zenject and destroy the current one.If you don't appreciate the benefits of DI then I doubt you will appreciate what Karma is doing for you.

"Spawing" new enemies, configuring the player depending on the scene, characters reacting to certain events triggered by other characters, the dash board changing according to the events of the game, even just declaring what time of enemy appear on what level. DI + a Pub/Sub system can help you achieve all this in a well though manner, Karma adds organization on top of this. You could always "just code it", frameworks don't do magic, but then you are going to start seen bugs because you lack an architecture.

 

Any updates?

 

In web development the MVC makes sense, all pages have a view and you tell it how to display depending on the actions the user takes and data they have stored. In games MVC feels unatural because you do not tell a view how to respond or react to user input. You control your characters, shoot bullets, enemies run on AI scripts and whatever happens happens. The camera displays what’s happening. Or at least this is how my games are.


My games have no concept of a view, the camera just display what’s going on and I think a lot of peoples games are like mine. In apps or GUI based games I can see MVC working well but in a lot of games the concept just doesn’t fit.

 

This isn't a thread about the pros and cons of MVC. I think anyone who has worked on larger software projects understands the value of well structured code. It's not surprising hobbyists won't get much out of this.

Someone give this guy a raise.

 

God. I arrived here looking for a way to simplify things and also to learn how to better architect my code so that it'll save time down the road. But Karma is built on top of Zenject.

I just installed Zenject, and loaded the Asteroids 'SampleGame1 (Beginner)'. There are 90 million C# files in there. It'll take me the rest of my life to learn it all.

This must add even more complexity.

 

I've been on more than a year-long quest to learn how to simplify while better architecting my Unity code. But I've only ended up feeling more despair at all the overly complicated DI/IOC/ECS systems many developers are preaching. But the above statement is the best I've ever read about this whole mess. It has shed a bright light on the matter and now I feel enlightened, and at long last, at peace!

 

You're right... ultimately, that stuff is just a way to add more layers of complexity. I used to actually enjoy this kind of thing. Was really into the engineering side and embraced all of this stuff. Then one day... not that long ago actually... I woke up and thought "this is actually a sort of insanity. We keep layering on more and more and more. We then layer on more to fix problems with the things we layered on previously." So I threw it all out. It's damn refreshing really.

So yeah either do like @neginfinity said and embrace the chaos or just throw it all out and simplify.

 

Hobbyist's aint working on corporate sized applications, so hardly relevant to anything nearly anyone here is doing.

Also, why is this in general? I remember it being in scripting... it belongs there more than here

 

LOL, so this MVC is really client - server model re-labeled to make me feel ignorant and that I should consider going into management so the programmers hip to the new lingo can talk about how stupid I am when I leave the room.

But really though, if it's any good I'll use it provided I don't have to read another $50 book from O'Reilly. I'm sure it is. Thanks. I joking with you.

 

I haven't really thought about using the MVC pattern and DI in Unity at all before and have only come across it in web development (angular and/or laravel for example). But I'm certainly intrigued and can see the benefits. I'll check out the sample project for sure.

 

The question isn't if well structured code is a good thing or not, the question is - how often is MVC an appropriate structure for games. I do think it's informative that OP doesn't actually use his software to make games.

I think one very common bias among programmers is the idea that "good code" is some kind of absolute and that good architecture and design is some kind of coding platonic ideal. It's not. Good code and good design is extremely specific to the needs of a project. MVC is a very good model for UI, that doesn't mean that it should be used in all other kinds of code. Game code is often extremely different from UI code and has very different needs, bounds and concerns.

My guess is that OP uses Unity to essentially build 3D UI, so for his needs it may be a sensible model. But when 2/3 of your code base is dealing with complex animation and navigation then you're really going to be shooting yourself in the foot when you try to approach the problem space as if it were something that it's not.

That said, there are a fair number of games that essentially build out 3D UI, but many have very different kinds of focus.

 

Even if you do not need any of the design patterns it is not a bad thing to know about them, how they work and what the problems are they a trying to solve. As developer/programmer chances are that you end up in a team utilising one or more of those patterns (which is pretty common nowadays).

 

You can also flip this, game design has it's own design patterns specific to the domain.

When you change the nomenclature and idioms such that you are relying on standards set in the web development community (this code is very angular based), then you aren't learning the patterns of the game design domain. Instead you're trying to hammer game design into a web development paradigm.

Not everything is a nail, calling a screw a nail and your screwdriver a hammer isn't always a good thing just because you're used to using hammers and nails.

 

In the time it will take you to become proficient with this, you could done with a game.

Frameworks don't make good programmers. They make reliant programmers.

 

Also frameworks make programmers write code other programmers understand. It is not a black and white thing. Always try to choose the right tool for the job.

 

As an application engineer, here are my two cents...

1. The IoC implementation should be abstracted... it's not that difficult to do and you could give your uses the freedom to us Zenject or StrangeIoC as they see fit.
2. Services should not be limited to Singletons. In fact, while they are singletons in AngularJS by default, they are not required to be. There are many instances where services may need to maintain state for a short lifetime. There should be some kind of object lifetime option (like the Lifetime Managers in Unity - the IoC system, not Unity3d). A user should be able to specify whether a service is Transient or Singleton. Attributes are a good way to specify this on a per implementation level.