ECS Game Architecture with Unity and Entitas

[sschmid]

ECS Game Architecture with Unity and Entitas

This is my mental model based on which I decide where to put my code.
Feel free to comment so we can improve this model further

[sschmid]

If I strictly apply this model to Match One, I'd have to remove the EmitInputSystem and turn it to a MonoBehaviour that emit input entities.
I would have to remove the AddViewSystem and the ViewComponent and have a ViewController or ViewService that listens to AssetComponent, then creates a view and binds it to an entity. The View would update itself with position listeners and destroyed listeners.
If I'm really strict I'd also remove the AssetComponent and have a mapping from entity type to asset name in the View Service, eg. isPlayer -> "Views/Player.prefab"
In my other games I'd also have to replace the PlayAudioSystem with and AudioController or AudioService. There would be no audio context and no AudioComponent anymore.

How does this sound? Am I going crazy? :)

[sschmid]

UI and Views visualize the current game state. They don't affect the game simulation. They can emit input like button clicks, but the game simulation doesn't know if this input came from a button, from the network or from some other program. That's why we don't need Entitas systems for them and can decouple them from the core logic as observers of the game state. UI and Views know how to represent the current game state. This allows us to start with placeholder assets which later can be replaced with the real game assets without touching the game logic.

[ghost]

We are doing it exactly like shown in the graphic. Furthermore we splitted the game logic into different parts: Action -> Command -> Core -> View. The View or other external inputs are able to create actions. The systems there are doing checks if it's possible and emit commands. The command systems will change the state of the core. Core systems only change core state. View is reacting on core and creating view state. Listeners are getting called, because something changed directly in core or in view. We also have a meta context which is just loaded balance values (from json just for easier access). This is done because action and view are part of unity (client side). Command and core are part of the simulation and will run not only on the client, but also on the server (we have a simulation game).

[sschmid]

1st result of applying this strictly with TDD (Audio):
Before:

• AudioComponent
• PlayAudioSystem
• AudioService
• no abstraction, dependency to unity

After:

• No Component / System / IListener / EventSystem
• AudioService (half the code)
• Abstraction (IAudioService, IAudioClip)
• Testable and no dependencies to Unity

Less complex and almost certainly more efficient

I guess I'm going down this road further :)

[RomanZhu]

Can you post your experiments into some repository?

[chiuan]

i thinks it's good to use react system to tell ui & view logic.
by the way , sometimes good to use event + iListener to make it better right now. good !

[c0ffeeartc]

Model looks nice and very intuitive, should be in wiki somewhere 😄

I wouldn't place Physics Collision alongside Button Click, because Unity runs physics in separate cycle N times before Update FixedUpdate > InternalPhysics > OnTriggerXXX > OnCollisionXXX > yield WaitForFixedUpdate.
Bullet may bounce of wall during few physics cycles before it gets destroyed in Game Logic, if we mark Bullet as trigger it gives no collisionInfo, and if we add BounceComponent to Bullet marked as trigger, it will travel a bit inside objects before GameLogic corrects its direction.

[sschmid]

I also refactored my views now. All testable and very nice :)

• removed ViewComponent
• Removed all view systems
• Views updated themselves using the new Entitas events
• ViewService listsnes to asset event and creates view from object pool
• View reacts to destroyed and pushes itself back to the object pool
• Added IView and IViewInstantiator to wrap monobehaviours and view creation. This was a result of TDD with TestView impl and TestViewInstantiator impl. The game uses UnityView (wraps MonoBehaviour) and UnityViewInstantiator (loads from Resources but can be swapped with UnityAssetBundleViewInstantiator). This way you can simply swap from creating view from resources to creating views from asset bundles at a later point of time. Object pooling is in ViewService

[sschmid]

I really start loving the new events. It feels so clean now :)
(We introduced the idea in 2016, but now that we can generate it's even nicer)

[optimisez]

Awesome. Btw @sschmid does it support loading some game objects first at loading time? For example, I want to load 10 enemies into game object pool first before starting game. I expect there is an API to preload the game object first into game object pool.

[sschmid]

Yes :)

[sschmid]

Updated diagram to include commands.
External input should be checked first and if valid creates commands which affect the simulation.

Invalid input could be for example buying an item, but you don't have enough resources. Commands don't verify, they only act.

[sschmid]

I recently built a few smaller games following the "Game Architecture with Entitas" diagram very strictly and I was really happy with the results. After the latest Video Tutorial about TDD #611 I started with strict testing again, and I have to tell you:
TDD really had a big impact on my apis and the general outcome. I'm so much happier with the result now. The code is way more reusable, which I was aiming for to be able to reuse as much code as possible in the next game. The apis are much cleaner and I got rid of unnecessary complexity. Plus, It just feels so much better to see all the green passing tests :) Really happy now! TDD FTW!

[sschmid]

As another consequence I could get rid of the following contexts: Input, UI, Audio. I only have game and command context left.
Feels like everything becomes simpler 👍

[sschmid]

ViewService, AudioService and all the other services are all less than 50 lines of code. Things became veeery simple now :)

[cruiserkernan]

@FNGgames What is your tag on UnityGameView for?

[FNGgames]

@cruiserkernan it's an enum tag i give to all entities - similar to unity's tag system, so i can find entities with tag or check a tag for something when i have a collision or whatever. It's just a component with an enum field.

[sschmid]

@FNGgames

I don't mind having these systems that talk to views because they're only ever talking to my interfaces

That's exactly how I did before, too. If you think about, using the events, that's still exactly the same: a system will call a method that's implemented from an interface. The only difference is, these systems are now automatically generated and you don't have to write them + those systems work on all kinds of things, not only views.

[sschmid]

@FNGgames Btw, thank you very much for your post. I love it :) Thanks for taking the time, I think it will help a lot of people who are new to all of this.

[FNGgames]

@sschmid good point RE: the events - there's still something talking to the views, but it's all hidden away.

No problem on the article, tbh i probably wrote it all in chat a couple of times before - it's nice to just be able to give some a link now :).

[sschmid]

To answer a question from the chat:

My only question is about the Input -> Command -> Process. Is there an example of this because I have a hard time differentiating it from normal Inputs in the Input context then picked by Systems to be applied to Entities

This is an optional idea that some of use to streamline adding new features and inputs.
Every game has a finite set of inputs like jump, shoot, buyItem, etc. This diagramm is a suggestion how to deal with those inputs. The input action layer is validating them, the command layer is applying them to the game logic.
To be specific (Shoot example):

• You create a ShootComponent with 2 contexts: InputAction and Command
• InputController : MonoBehaviour creates new InputEntity with ShootComponent when mouseDown
• Reactive ShootInputActionSystem is validating the input (e.g. can shoot? hasAmmo? is bullet cooldown complete?) and creates CommandEntitiy with ShootComponent (or not)
• Reactive ShootCommandSystem does whatever needs to be done, e.g. create a new bullet entity that spawns in the game

[sschmid]

the larger the game and the more inputs you have, the more important it becomes to have a defined way how to handle those inputs. This approach helped me managing this even with lots of inputs

[fayte0618]

I just want to make sure if I understand it correctly. This would mean I have an Input, Command and Game context version of the components? Then, I have an InputSystem to filter the Input entity which creates a Command Entity, then have a CommandSystem to operate on the Command entity which it applies to the Game entity?

[sschmid]

see comments above
#610 (comment)

[sschmid]

Yes, that's the idea. Most of it can be generated as described in the comment above. So all I implement is just the execute of the input system and the command system. Everything else will be generated

[optimisez]

I removed InputActionService which is now replaced by individual systems.

@sschmid I wonder how you can like emits InputActionEntity.BuyItem from a UI that has MonoBehaviour since when linking entity to its MonoBehaviour, it will only pass Game Context? Have u use something like EntityService in Match-One?

[OmiCron07]

What do you think about physics interaction with ECS/Entitas? If we need to interact with the physics, where would you put the "logic"?

Here my example :

I have a plane controlled by physics (Rigidbody.AddForce) and a PID controller to calculate the right amount of force to apply.

1. Would you make a system to calculate the force and vector to apply to the rigidbody and a PID component to save some values between calculation? You need to know the current velocity too in the calculation... So, with the final force calculated, apply and trigger an event for the view to add that force to itself?

2. Would you make an event with the view listening the force rate needed to apply and the View/MonoBehaviour do the calculation with its PID controller and apply the calculated force on the rigidbody?

3. Would you put the rigidbody in a component and add the force directly from the system to that rigidbody, like the endless runner example?

With various Entitas examples, I see that the views listen the position component to update its transform values, because it easy to see the position of the view as a state of the view. But with physics, like the velocity, is it a view state controlled by the rendering engine or is it part of the game logic and it could be unit tested?

[c0ffeeartc]

@OmiCron07 I'd say it's up to the developer to decide. There is a balance what data to put into ECS layer and what to keep in View layer.
Physics is a special case, cause FixedUpdate runs right before Update [0..N] times (Unity Events Order, Physics.Simulate).

I'd handle most of physics interaction inside View layer(or create FixedSystems to run in FixedUpdate). And occasionally send data through ECS components so that systems and eventSystems could react.

[c0ffeeartc]

1. Would you make a system to calculate the force and vector to apply to the rigidbody and a PID component to save some values between calculation? You need to know the current velocity too in the calculation... So, with the final force calculated, apply and trigger an event for the view to add that force to itself?

Sounds ok to create system to calculate something and another system to apply calculations.

2. Would you make an event with the view listening the force rate needed to apply and the View/MonoBehaviour do the calculation with its PID controller and apply the calculated force on the rigidbody?

It would work, could be tempting and easier to make but sounds more fragile in the long run.

3. Would you put the rigidbody in a component and add the force directly from the system to that rigidbody, like the endless runner example?

Often ViewComponent is already attached, it's fine to add/access other MonoBehaviours through entity components. Unless you have some architecture restriction on using monoBehaviours in systems

4. With various Entitas examples, I see that the views listen the position component to update its transform values, because it easy to see the position of the view as a state of the view. But with physics, like the velocity, is it a view state controlled by the rendering engine or is it part of the game logic and it could be unit tested?

Physics changes unity transform values. It's possible to sync changes afterwards by checking Transform.hasChanged or some other trick. Or keep all transform calculations inside unity View layer and use unity values inside systems

[OmiCron07]

Thank you for the responses, will check it out how it turns out.