How I build games with Entitas (FNGGames)

This post is an explainer for how I structure my projects using Entitas. It assumes a decent undestanding of how entitas works, it is not inteded as a tutorial for any particular feature of Entitas. Instead it's meant to explain how one can structure code using Entitas to maximise clarity, stability and flexibility, especially in larger projects. I certainly do not claim this to be authoratative, it just the way I have learned to do things over my first few projects with Entitas. As always, YMMV.

I'm going to try to cover the following topics. I will use Unity to illustrate the concept of views and view controllers, but this way of thinking should apply regardless of the engine you're using.

Defining Data, Logic and View layers

Maintaining separation between them

Abstraction via Interfaces

Inversion of Control

View layer abstraction (views and view controllers)

Definitions

Data: The game state. Data such as health, inventory, experience, enemy type, ai state, movement speed etc. In Entitas these data live in Components.

Logic: The rules for how the data can be transformed. PlaceInInventory(), BuildItem(), FireWeapon() etc. In Entitas these are Systems.

View: The code responsible for displaying the game state to the player, rendering, animation, audio, ui widget etc. In my examples these will be MonoBehaviours living on GameObjects.

Architecture

The core of any game is just a numerical simulation happening in a CPU. Every game is just a collection of data (the game's state) undergoing periodic numerical transformations (the game's logic). Game state includes things like score, health, xp, NPC dialog, inventories etc etc etc. The game's logic dictates the rules of the transformations that these data can undergo (calling PlaceItemInInventory() alters the game state in a defined manner). The entire simulation can exist without any additional layers.

In general, the difference between a game and a pure simulation is that there is an external user in the loop, with the ability to use the simulation logic to change the game state manually from the outside. With the addition of user, there also comes the requirement of communicating the state of the simulation to her. This is the "View Layer". The part of the code base that is responsible for communicationg the game state by rendering actors to the screen, playing audio, updating UI widgets etc. Without this layer there is no way the user can understand or meaninfully interact with the simulation.

Most game architectures aim to actively maintain a distinction between the logic and data layers and the view layer. The idea is that the simulation layers shouldn't care or even know that they are being drawn on a screen. The method that determines how a player's health should change when they take damage should not contain code for rendering a blood effect on the screen or playing a pain sound effect.

The way I maintain this separation is by structuring my project following the diagram below. I'll try to describe each part of the diagram and broadly how concepts like abstraction, through the use of interfaces, helps to acheive this.

Abstraction in action

Abstraction (in this specific case) is the process of removing strong coupling between what you want to do and how you want to do it. As a very simple example, let's imagine a function for writing out debug text somewhere the user can see it.

Naive approach

The most naive approach, which i'm sure most readers will know to avoid already, would be to place a call to Debug.Log inside every system that needs to write a log message. This immediately introduces strong coupling all over our code base and makes it a nightmare to maintain.

Problems with the naive approach

What happens when you want to stop using Debug.Log in favour of a proper log-to-file solution? What about when you get around to adding an in-game debug console and I want to print messages to that as well? With the naive approach you have to go around your entire code base and start adding or replacing these method calls. This is a truly nightmarish problem in even a medium sized project.

You also have unreadable, confusing code. There is no separation of responsibilities. If you've ever completed one of Unity's example projects you'll probably have seen this and thought it's ok because Unity do it. I'm here to tell you it's not ok. Your character controller shouldn't be parsing raw user input, tracking inventory, playing footstep sounds and posting messages on facebook as well as making your character move. It should just be making your character move. Separate your concerns.

Decoupled code - the Entitas approach

You probably came to Entitas in the first place because you're all too familiar with these sorts of problems. So let's do it the Entitas way now to show how much better it is:

In Entitas we would probably acheive this by creating a LogMessageComponent (string message) and designing a ReactiveSystem that collects these messages and does the actual work. With this setup we can easily create an entity, hang the component on it and have it print the message to the console.

Now whenever something wants to create a log message it just creates an entity and the system takes care of it. We are free to change our implentation as many times as we like and we will only ever have to change the code in one place (inside that system).

Problems with (pure) Entitas approach

This approach will be sufficient for some users, especially in smaller projects like MatchOne. But it is not without problems of its own. We have added a strong dependency on UnityEngine because we are using its API inside our system. We have also written our implentation directly into our system.

While this is no problem in the case of Debug.Log(), which is one line of code, what if part of your logging involved parsing a json file or sending the message over a network? Now you have lots of implentation-specific boiler-plate code in your systems. You also have a ton of dependencies and using statements all over the place (UnityEngine / JSON library / Networking Library etc). The code is more difficult to read and more resistant and error prone with respect to changes to your toolset. God forbid you ever have to change engine, that's a complete re-write of your game code.

Interfaces by example

The way to solve these dependency and clarity problems in C# is through the use of interfaces. An interface is a like a contract. By telling the compiler you class implements an interface, you are saying "this class has the same public API as this interface".

When i write interfaces I am thinking "what information or functionality does my game need from this thing?", then I try to come up with a descriptive, simple API for it. For a logging service we might only want one method, a simple LogMessage(string message). Expressed as an interface that looks like this:

By saying your class implements ILogService you are guaranteeing to the compiler that it has the method void LogMessage(string message). This means you can use it in the reactive system as before. This system only sees the interface ILogService. If we pass in a JsonLogService to the system, we will get a json file with our log messages in it, but we won't be able to access the public string fields of the JsonLogService class since they're not included in the interface. Note that now we have pass in an instance of ILogService to the system's constructor. I'll return to this later.

// the previous reactive system becomes publicclassHandleDebugLogMessageSystem : ReactiveSystem<DebugEntity> {
ILogService_logService;
// contructor needs a new argument to get a reference to the log servicepublicHandleDebugLogMessageSystem(Contextscontexts, ILogServicelogService) {
// could be a UnityDebugLogService or a JsonLogService_logService=logService;
}
// collector: Debug.Matcher.DebugLog// filter: entity.hasDebugLogpublicvoidExecute (List<DebugEntity> entities) {
foreach (vareinentities) {
_logService.LogMessage(e.DebugLog.message); // using the interface to call the methode.isDestroyed=true;
}
}
}

A more complex example from my projects is IInputService. Again, I am thinking, what do i need to know about the user input? Can i define a simple set of properties and methods that would get me what i need? Here is part of my interface:

I can now write an EmitInputSystem to pull the input data into Entitas. Now it is game data that can be reacted on to do other things. The beauty of this approach is that i can swap out my unity implentation for one that uses an asset store solution such as InControl without changing any game code. Notice that in the system below the code only queries the interface.

By now I hope you can see what I mean when I say "abstraction". I am abstracting the logic from the implentation, the what from the how. For the input service I am saying that all I care about is that I can query whether the user has pressed ButtonA, i dont care whether this comes from a keyboard or a mouse or a smartphone through a network connection. None of that matters to the part of my game where I'm actually reading the input.

For the time service I am saying "give me the time delta", i dont need to know if it was Unity or XNA or Unreal that provided it, i just need to know what it is so i can figure out how much to move this guy around on the screen.

Inversion of control

We have introduced one complication into our code which we didn't have before: now we have to get a reference to an instance of the service interface into the system somehow. In the above examples I've passed it in via the constructor, but this would lead to lots of systems with different constructors. What we'd like is to have our service instances to be globally accessible. We'd also like to have only one place in our code base, somewhere near application start, where we decide which implementations of these interfaces we will use. From there we need to create instances of them and make them globally accessible so they can be queried in systems without having to pass them into every individual constructor. Luckily this is super-easy to do with Entitas.

My approach to this is to first create a helper class that has a reference to each service in it:

Finally I have a Feature, the very first to run in my systems heirarchy, called ServiceRegistrationSystems. This takes in an extra Services argument in its constructor, then passes the services down to initialize systems. These systems simple assign the instances in Services to the unique components in the meta context.

The result is we now have global access to the service instances through the Contexts instance (_contexts.meta.timeService.instance). We also created all of them in one place, so it is trivial to go back, change implentation or mock up dummy implentations for tests. You could also easily use compiler directives to give you platform specific, or debug-build specific implentations. We have "inverted control" of dependency resolution, from deep within our systems classes to right at the top of our applciation.

View Layer Abstraction

So far, we've looked at the service interfaces from left of the diagram, now let's take a look at the View interfaces from the right hand side. The work in much the same way. As we've said, the View layer is the stuff concerned with displaying the game state to the player - animations, sounds, sprites, meshes, renderers etc. The goal here is again to remove concrete dependencies on a particular game engine or 3rd party library, and also to have clean, descriptive code inside our systems without any nitty-gritty implentation details.

A naive approach would be to have a ViewComponent with a reference to a gameobject on it. Then perhaps a simple flag component AssignViewComponent to indicate we need to create a new gameobject to act as the view for this entity. To use this you'd write a reactive system that reacts on AssignView and filters for !entity.hasView to ensure we don't add a view where it's not needed. In this system you'd have to use the unity API directly inside your system code and even inside your components. This of course fails to acheive all the goals we have set for ourselves.

Here we can make use of the service patten described above, along with a further set of abstractions for the views. Again, think about what data and functionality you actually need from your views, and write an interface for it. This will be how your systems code sets or gets data from your views. I call this a "ViewController" - that is the piece of code that controls the View objects directly. Typically this will contain tranform information (position / scale / rotation) as well as things like tags, layers, names, enable / disable status.

The view, by its nature, is bound to an entity, and it may need to do work with information from both that entity and other parts of your game state. For this I want to pass in references to the entity and the Contexts instance when i set up the view. I will also want the ability to destroy the view from inside my entitas code. Here is a simple example:

There are no dependencies to Unity engine in our code, components and systems reference only the interfaces we've written. There is no detailed implentation in the code (don't have to worry about accessing gameObjects and trasnforms, we are simply setting a property in an interface).

Problems with this approach

There is one obvious flaw - that you are now writing systems in your game code which are responsible for talking to the view layer - this breaks one of our earlier prinicples - that our simulation should not need to know that it is being drawn. There is another way to do set things up in Entitas that does more to enforce fully decoupled views - that is the Entitas "Events" functionality.

Events

In Match-One, Simon has no ViewComponent. In fact, nothing in the game code even knows it's being drawn at all. Instead his View MonoBehaviours are just event listeners. I will recreate the above example using events to show how this can simplify your game logic even further and fully decouple the simulation layer from the view layer.

First we need a component tagged with the [Event] attribute to generate the listeners and event systems we'll need. Let's use the Position example again.

The new attribute will generate a PositionListenerComponent and an IPositionListener interface. Now I will write another interface that will apply to all event listeners so that i can safely intialize them when they're created:

We will now have no further need for the view component or the return value from our LoadAsset method in the view service, so we can remove them. Finally we will add some code to the view service to identify and initialize these event listeners if it finds them on an asset:

If we add this script to a prefaband generated EventSystems to the game controller, the gameobject transform will stay perfectly in sync with the entity's PositionComponent without any help from systems. The view's position is fully decoupled from the entity's position in the simulation layer. You can easily add events to any component you like, recreating all the functionality you had in the original IViewController interface, getting rid of it all together in favour of event listeners.

This pattern of loading assets through a service also gives us the ability to control the initialization of and information flow to our views. You could add as many as you like (IAudioPlayer, IAnimator, ICollider etc) and pass each of them references to the contexts and / or the entity they are associated with. You control the order and timing of the initialization (no more wondering when Start() and Update() will get called by Unity, no need to null check everywhere in case Start() got called too early).

Now you can have views handle things on their own - view controllers become simple event listeners, reacting to changes in components of interest, but with no need to ever send information back to the simulation layer (except perhaps to hang an xxxListenerComponent on an entity during intialization). You can implement an entire animation system in Unity through monobehaviour event listeners without having any reference to it in your simulation layers. The same goes with audio, particles, funky shaders etc.

Summing up

This is ideal. We have now acheived all the goals we set out at the start.

We have fully decoupled our entitias code from our game engine and any 3rd party libraries we've got lying around.

We have a simulation layer (data in components and logic in systems) that is completely engine agnostic. There is now just one folder in our project containing the actual Unity implentations of our various interfaces. This is the only folder we will have to touch if we decide to move everything out of Unity to XNA tomorrow.

We have one place at the top of our application where we decide which implentations we will use. We can use this to mock up test situations, try out new 3rd party solutions, or simply change our minds about how things should work, without touch the game logic in any way.

Our simulation layer is fully decoupled from the view layer, and once we've got events up and running we have a code base that doesn't event know it's being drawn. The entire simulation could run happily on a headless server, leaving the view code to run on the client machines.

Finally, when we look at our game logic, it is clean and easy to read. Complex implementation is hidden away and replaced with simple calls to descripively named methods and properties. We can design our interfaces to only contain fields of interest, we no longer have to see huge intelli-sense dropdowns filled with irrelevant information. We will only have access to what we need.