Morpeh

🎲 ECS Framework for Unity Game Engine and .Net Platform

Simple Syntax.
Plug & Play Installation.
No code generation.
Structure-Based and Cache-Friendly.

📖 Table of Contents

Migration
How To Install
- Unity Engine
- .Net Platform
Introduction
Examples
Games
License
Contacts

✈️ Migration To New Version

English version: Migration Guide
Russian version: Гайд по миграции

📖 How To Install

Unity Engine

Minimal Unity Version is 2020.3.*
Require Git.
Currently require Odin Inspector for drawing in inspector.

Open Unity Package Manager and add Morpeh URL.

⭐ Main: https://github.com/scellecs/morpeh.git
🏷️ Tag: https://github.com/scellecs/morpeh.git#2022.2.3

.Net Platform

NuGet package URL: https://www.nuget.org/packages/Scellecs.Morpeh

📖 Introduction

📘 Base concept of ECS pattern

🔖 Entity

Container of components.
Has a set of methods for add, get, set, remove components.
It is reference type. Each entity is unique and not pooled. Only entity IDs are reused.

var entity = this.World.CreateEntity();

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

//if you remove last component on entity it will be destroyd on next world.Commit()
bool removed = entity.RemoveComponent<HealthComponent>();
entity.SetComponent(new HealthComponent {healthPoints = 100});

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

var newEntity = this.World.CreateEntity();
//after migration entity has no components, so it will be destroyd on next world.Commit()
entity.MigrateTo(newEntity);

🔖 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.

All systems are represented by interfaces, but for convenience, there are ScriptableObject classes that make it easier to work with the inspector and Installer.
Such classes are the default tool, but you can write pure classes that implement the interface, but then you need to use the SystemsGroup API instead of the Installer.

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() {
    }
}

All systems types:

IInitializer & Initializer - have only OnAwake and Dispose methods, convenient for executing startup logic
ISystem & UpdateSystem
IFixedSystem & FixedUpdateSystem
ILateSystem & LateUpdateSystem
ICleanupSystem & CleanupSystem

🔖 SystemsGroup

The type that contains the systems.
There is an Installer wrapper to work in the inspector, but if you want to control everything from code, you can use the systems group directly.

var newWorld = World.Create();

var newSystem = new HealthSystem();
var newInitializer = new HealthInitializer();

var systemsGroup = newWorld.CreateSystemsGroup();
systemsGroup.AddSystem(newSystem);
systemsGroup.AddInitializer(newInitializer);

//it is bad practice to turn systems off and on, but sometimes it is very necessary for debugging
systemsGroup.DisableSystem(newSystem);
systemsGroup.EnableSystem(newSystem);

systemsGroup.RemoveSystem(newSystem);
systemsGroup.RemoveInitializer(newInitializer);

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

🔖 World

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

var newWorld = World.Create();
//a variable that specifies whether the world should be updated automatically by the game engine.
//if set to false, then you can update the world manually.
//and can also be used for game pauses by changing the value of this variable.
newWorld.UpdateByUnity = true;

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>();

var healthCache = newWorld.GetStash<HealthComponent>();
var reflectionHealthCache = newWorld.GetReflectionStash(typeof(HealthComponent));

//manually world updates
newWorld.Update(Time.deltaTime);
newWorld.FixedUpdate(Time.fixedDeltaTime);
newWorld.LateUpdate(Time.deltaTime);
newWorld.CleanupUpdate(Time.deltaTime);

//apply all entity changes, filters will be updated.
//automatically invoked between systems
newWorld.Commit();

🔖 Filter

A type that contains entities constrained by conditions With and/or Without.
You can chain them in any order and quantity.

var filter = this.World.Filter.With<HealthComponent>()
                              .With<BooComponent>()
                              .Without<DummyComponent>();

var firstEntityOrException = filter.First();
var firstEntityOrNull = filter.FirstOrDefault();

bool filterIsEmpty = filter.IsEmpty();
int filterLengthCalculatedOnCall = filter.GetLengthSlow();

🔖 Stash

A type that contains components.
You can get components and do other operations directly from the stash, because entity methods look up the stash each time on call.
However, such code is harder to read.

var healthStash = this.World.GetStash<HealthComponent>();
var entity = this.World.CreateEntity();

ref var addedHealthComponent  = ref healthStash.Add(entity);
ref var gottenHealthComponent = ref healthStash.Get(entity);

bool removed = healthStash.Remove(entity);

healthStash.Set(entity, new HealthComponent {healthPoints = 100});

bool hasHealthComponent = healthStash.Has(entity);

var newEntity = this.World.CreateEntity();
//transfers a component from one entity to another
healthStash.Migrate(from: entity, to: newEntity);

//not a generic variation of stash, so we can only do a limited set of operations
var reflectionHealthCache = newWorld.GetReflectionStash(typeof(HealthComponent));

//set default(HealthComponent) to entity
reflectionHealthCache.Set(entity);

bool removed = reflectionHealthCache.Remove(entity);

bool hasHealthComponent = reflectionHealthCache.Has(entity);

📘 Getting Started

💡 IMPORTANT
For a better user experience, we strongly recommend having Odin Inspector 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 Scellecs.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, CleanupSystem.
They are similar as MonoBehaviour's Update, FixedUpdate, LateUpdate. CleanupSystem called the most recent in LateUpdate.

System looks like this.

using Scellecs.Morpeh.Systems;
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>();

The filters themselves are very lightweight and are free to create.
They do not store entities directly, so if you like, you can declare them directly in hot methods like OnUpdate().
For example:

public sealed class HealthSystem : UpdateSystem {
    
    public override void OnAwake() {
    }

    public override void OnUpdate(float deltaTime) {
        var filter = this.World.Filter.With<HealthComponent>();
        
        //Or just iterate without variable
        foreach (var entity in this.World.Filter.With<HealthComponent>()) {
        }
    }
}

But we will focus on the option with caching to a variable, because we believe that the filters declared in the header of system increase the readability of the code.

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 use stash directly.
No need to do GetComponent from entity every time, which trying to find suitable stash.
However, we use such code only in very hot areas, because it is quite difficult to read it.

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

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

We will focus on a simplified version, because even in this version entity.GetComponent is very fast.

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 Scellecs.Morpeh.Providers;
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

🧹 Component Disposing

Sometimes it becomes necessary to clear component values. For this, it is enough that the component implements IDisposable. For example:

public struct PlayerView : IComponent, IDisposable {
    public GameObject value;
    
    public void Dispose() {
        Object.Destroy(value);
    }
}

The initializer or system needs to mark the stash as disposable. For example:

public class PlayerViewDisposeInitializer : Initializer {
    public override void OnAwake() {
        this.World.GetStash<PlayerView>().AsDisposable();
    }
}

public class PlayerViewSystem : UpdateSystem {
    public override void OnAwake() {
        this.World.GetStash<PlayerView>().AsDisposable();
    }
    
    public override void OnUpdate(float deltaTime) {
        ...
    }
}

Now, when the component is removed from the entity, the Dispose() method will be called on the PlayerView component.

🧨 Unity Jobs And Burst

💡 Supported only in Unity. Subjected to further improvements and modifications.

You can convert Filter<T> to NativeFilter<TNative> which allows you to do component-based manipulations inside a Job.
Conversion of Stash<T> to NativeStash<TNative> allows you to operate on components based on entity ids.

Current limitations:

NativeFilter and NativeStash and their contents should never be re-used outside of single system tick.
NativeFilter and NativeStash cannot be used in-between World.Commit() calls inside Morpeh.
NativeFilter should be disposed upon usage completion due to #107, which also means NativeFilter causes a single Allocator.TempJob NativeArray allocation.
Jobs can be chained only within current system execution, NativeFilter can be disposed only after execution of all scheduled jobs.

Example job scheduling:

public sealed class SomeSystem : UpdateSystem {
    private Filter filter;
    private Stash<HealthComponent> stash;
    ...
    public override void OnUpdate(float deltaTime) {
        using (var nativeFilter = this.filter.AsNative()) {
            var parallelJob = new ExampleParallelJob {
                entities = nativeFilter,
                healthComponents = stash.AsNative(),
                // Add more native stashes if needed
            };
            var parallelJobHandle = parallelJob.Schedule(nativeFilter.length, 64);
            parallelJobHandle.Complete();
        }
    }
}

Example job:

[BurstCompile]
public struct TestParallelJobReference : IJobParallelFor {
    [ReadOnly]
    public NativeFilter entities;
    public NativeStash<HealthComponent> healthComponents;
        
    public void Execute(int index) {
        var entityId = this.entities[index];
        
        ref var component = ref this.healthComponents.Get(entityId, out var exists);
        if (exists) {
            component.Value += 1;
        }
        
        // Alternatively, you can avoid checking existance of the component
        // if the filter includes said component anyway
        
        ref var component = ref this.healthComponents.Get(entityId);
        component.Value += 1;
    }
}

📚 Examples

Tanks by SH42913
Ping Pong by SH42913
Flappy Bird by R1nge

🔥 Games

Zombie City by GreenButtonGames
Android iOS
Fish Idle by GreenButtonGames
Android iOS
Stickman of Wars: RPG Shooters by Multicast Games
Android iOS
One State RP - Life Simulator by Chillbase
Android iOS

📘 License

📄 MIT License

💬 Contacts

✉️ Telegram: olegmrzv
📧 E-Mail: [email protected]
👥 Telegram Community RU: Morpeh ECS Development

scellecs/morpeh

scellecs

Reviews

Repository Details