Morpeh

🎲 ECS Framework for Unity Game Engine.

Adapted for the development mobile games like:
    📕 Hyper Casual
    📗 Idlers
    📘 Arcades
    📚 Other genres

Features:

Simple Syntax.
Simple Integration with Unity Engine.
No code generation and any C# Reflection in Runtime.
Structure-based and Cache-friendly.
Reactive and Fast Filters.
Built-in Events and Reactive Variables aka Globals.
Single-threaded.

📖 How To Install

Minimal Unity Version is 2019.3.*

Open Package Manager and add Morpeh URL.

    ⭐ Master: https://github.com/X-Crew/Morpeh.git
    🚧 Dev: https://github.com/X-Crew/Morpeh.git#develop
    🏷️ Tag: https://github.com/X-Crew/Morpeh.git#2020.8.0

You can update Morpeh by Discover Window. Select Help/Morpeh Discover menu.

📖 Introduction

📘 Base concept of ECS pattern

🔖 Entity

Container of components.
Has a set of methods for add, get, set, remove components.

var entity = this.World.CreateEntity();

ref var addedHealthComponent  = ref entity.AddComponent<HealthComponent>();
ref var gottenHealthComponent = ref entity.GetComponent<HealthComponent>();

bool removed = entity.RemoveComponent<HealthComponent>();
entity.SetComponent(new HealthComponent {healthPoints = 100});

bool hasHealthComponent = entity.Has<HealthComponent>();

🔖 Component

Components are types which include only data.
In Morpeh components are value types for performance purposes.

public struct HealthComponent : IComponent {
    public int healthPoints;
}

🔖 System

Types that process entities with a specific set of components.
Entities are selected using a filter.

public class HealthSystem : ISystem {
    public World World { get; set; }

    private Filter filter;

    public void OnAwake() {
        this.filter = this.World.Filter.With<HealthComponent>();
    }

    public void OnUpdate(float deltaTime) {
        foreach (var entity in this.filter) {
            ref var healthComponent = ref entity.GetComponent<HealthComponent>();
            healthComponent.healthPoints += 1;
        }
    }

    public void Dispose() {
    }
}

🔖 World

A type that contains entities, components caches, systems and root filter.

var newWorld = World.Create();

var newEntity = newWorld.CreateEntity();
newWorld.RemoveEntity(newEntity);

var systemsGroup = newWorld.CreateSystemsGroup();
systemsGroup.AddSystem(new HealthSystem());

newWorld.AddSystemsGroup(order: 0, systemsGroup);
newWorld.RemoveSystemsGroup(systemsGroup);

var filter = newWorld.Filter.With<HealthComponent>();

📘 Getting Started

💡 IMPORTANT
For a better user experience, we strongly recommend having Odin Inspector and FindReferences2 in the project.
All GIFs are hidden under spoilers.

After installation import ScriptTemplates and Restart Unity.

Let's create our first component and open it.

Right click in project window and select Create/ECS/Component.

After it, you will see something like this.

using Morpeh;
using UnityEngine;
using Unity.IL2CPP.CompilerServices;

[Il2CppSetOption(Option.NullChecks, false)]
[Il2CppSetOption(Option.ArrayBoundsChecks, false)]
[Il2CppSetOption(Option.DivideByZeroChecks, false)]
[System.Serializable]
public struct HealthComponent : IComponent {
}

💡 Don't care about attributes.
Il2CppSetOption attribute can give you better performance.

Add health points field to the component.

public struct HealthComponent : IComponent {
    public int healthPoints;
}

It is okay.

Now let's create first system.

Right click in project window and select Create/ECS/System.

💡 Icon U means UpdateSystem. Also you can create FixedUpdateSystem and LateUpdateSystem.
They are similar as MonoBehaviour's Update, FixedUpdate, LateUpdate.

System looks like this.

using Morpeh;
using UnityEngine;
using Unity.IL2CPP.CompilerServices;

[Il2CppSetOption(Option.NullChecks, false)]
[Il2CppSetOption(Option.ArrayBoundsChecks, false)]
[Il2CppSetOption(Option.DivideByZeroChecks, false)]
[CreateAssetMenu(menuName = "ECS/Systems/" + nameof(HealthSystem))]
public sealed class HealthSystem : UpdateSystem {
    public override void OnAwake() {
    }

    public override void OnUpdate(float deltaTime) {
    }
}

We have to add a filter to find all the entities with HealthComponent.

public sealed class HealthSystem : UpdateSystem {
    private Filter filter;
    
    public override void OnAwake() {
        this.filter = this.World.Filter.With<HealthComponent>();
    }

    public override void OnUpdate(float deltaTime) {
    }
}

💡 You can chain filters by two operators With<> and Without<>.
For example this.World.Filter.With<FooComponent>().With<BarComponent>().Without<BeeComponent>();

Now we can iterate all needed entities.

public sealed class HealthSystem : UpdateSystem {
    private Filter filter;
    
    public override void OnAwake() {
        this.filter = this.World.Filter.With<HealthComponent>();
    }

    public override void OnUpdate(float deltaTime) {
        foreach (var entity in this.filter) {
            ref var healthComponent = ref entity.GetComponent<HealthComponent>();
            Debug.Log(healthComponent.healthPoints);
        }
    }
}

💡 Don't forget about ref operator.
Components are struct and if you want to change them directly, then you must use reference operator.

For high performance, you can do cached sampling.
No need to do GetComponent from entity every time.
But we will focus on a simplified version, because even in this version GetComponent is very fast.

public sealed class HealthSystem : UpdateSystem {
    private Filter filter;
    
    public override void OnAwake() {
        this.filter = this.World.Filter.With<HealthComponent>();
    }

    public override void OnUpdate(float deltaTime) {
        var healthBag = this.filter.Select<HealthComponent>();

        for (int i = 0, length = this.filter.Length; i < length; i++) {
            ref var healthComponent = ref healthBag.GetComponent(i);
            Debug.Log(healthComponent.healthPoints);
        }
    }
}

Let's create ScriptableObject for HealthSystem.
This will allow the system to have its inspector and we can refer to it in the scene.

Right click in project window and select Create/ECS/Systems/HealthSystem.

Next step: create Installer on the scene.
This will help us choose which systems should work and in which order.

Right click in hierarchy window and select ECS/Installer.

Add system to the installer and run project.

Nothing happened because we did not create our entities.
I will show the creation of entities directly related to GameObject, because to create them from the code it is enough to write world.CreateEntity().
To do this, we need a provider that associates GameObject with an entity.

Create a new provider.

Right click in project window and select Create/ECS/Provider.

using Morpeh;
using Unity.IL2CPP.CompilerServices;

[Il2CppSetOption(Option.NullChecks, false)]
[Il2CppSetOption(Option.ArrayBoundsChecks, false)]
[Il2CppSetOption(Option.DivideByZeroChecks, false)]
public sealed class HealthProvider : MonoProvider<{YOUR_COMPONENT}> {
}

We need to specify a component for the provider.

public sealed class HealthProvider : MonoProvider<HealthComponent> {
}

Create new GameObject and add HealthProvider.

Now press the play button, and you will see Debug.Log with healthPoints.
Nice!

📖 Advanced

📘 Event system. Singletons and Globals Assets.

There is an execution order in the ECS pattern, so we cannot use standard delegates or events, they will break it.

ECS uses the concept of a deferred call, or the events are data.
In the simplest cases, events are used as entities with empty components called tags or markers.
That is, in order to notify someone about the event, you need to create an entity and add an empty component to it.
Another system creates a filter for this component, and if there are entities, we believe that the event is published.

In general, this is a working approach, but there are several problems.
Firstly, these tags overwhelm the project with their types, if you wrote a message bus, then you understand what I mean.
Each event in the game has its own unique type and there is not enough imagination to give everyone a name.
Secondly, it’s uncomfortable working with these events from MonoBehaviours, UI, Visual Scripting Frameworks (Playmaker, Bolt, etc.)

As a solution to this problem, global assets were created.

🔖 Singleton is a simple ScriptableObject that is associated with one specific entity.
It is usually used to add dynamic components to one entity without using filters.

🔖 GlobalEvent is a Singleton, which has the functionality of publishing events to the world by adding a tag to its entity.
It has 4 main methods for working with it:

Publish (arg) - publish within the frame, and all downstream systems will see this.
NextFrame (arg) - publish in the next frame, all systems will see this.
IsPublished - did anyone publish this event
BatchedChanges - a data stack where publication arguments are added.

🔖 GlobalVariable is a GlobalEvent that stores the start value and the last value after the changes.
It also has the functionality of saving and loading data from PlayerPrefs.

You can create globals by context menu Create/ECS/Globals/ in Project Window.
You can declare globals in any systems, components and scripts and set it by Inspector Window, for example:

public sealed class HealthSystem : UpdateSystem {
    public GlobalEvent myEvent;
    ...
}

And check their publication with:

public sealed class HealthSystem : UpdateSystem {
    public GlobalEvent myEvent;
    ...
    public override void OnUpdate(float deltaTime) {
        if (myEvent.IsPublished) {
            Debug.Log("Event is published");
        }
    }
}

And there is also a variation with checking for null:

public sealed class HealthSystem : UpdateSystem {
    public GlobalEvent myEvent;
    ...
    public override void OnUpdate(float deltaTime) {
        if (myEvent) {
            Debug.Log("Event is not null and is published");
        }
    }
}

📘 License

📄 MIT License

💬 Contacts

✉️ Telegram: benjminmoore
📧 E-Mail: benjminmoore@gmail.com

Mefodei / Morpeh