README.en.md

LeoECS Proto – Unity uGUI events integration

Integration of Unity uGUI events for LeoECS Proto.

IMPORTANT! Requires C# 9 (or Unity >= 2021.2).

IMPORTANT! Depends on: Leopotam.EcsProto, Leopotam.EcsProto.QoL, Leopotam.EcsProto.Unity, and Unity.TextMeshPro.

IMPORTANT! Use DEBUG builds for development and RELEASE builds for production: all internal checks/exceptions work only in DEBUG builds and are stripped in RELEASE builds to maximize performance.

IMPORTANT! Tested on Unity 2021.3 (depends on it) and contains asmdef definitions so it compiles into separate assemblies and reduces main project recompile time.

Social

Official blog: https://leopotam.ru

Installation

As a Unity package

Installable as a Unity package via a Git URL in the Package Manager or by editing Packages/manifest.json directly:

"ru.leopotam.ecsproto.unity.ugui": "https://gitverse.ru/leopotam/ecsproto.unity.ugui.git",

As source code

You can clone the repo or download an archive from the releases page.

Other sources

The official, working version is hosted at https://gitverse.ru/leopotam/ecsproto.unity.ugui. All other sources (including nuget, npm, and third‑party mirrors) are unofficial clones or unrelated code with unknown content.

Unity uGUI module

The module cleans (consumes) uGUI events and registers them as components. It consists of 2 parts: the aspect and the systems logic.

Manual aspect wiring

Add the UnityUguiAspect type to the main world aspect:

class Aspect1 : ProtoAspectInject {
    public readonly UnityUguiAspect Ugui;
    // Register other aspects here.
}

Manual systems wiring

// Environment initialization.
using Leopotam.EcsProto;
using Leopotam.EcsProto.QoL;
using Leopotam.EcsProto.Unity;
using Leopotam.EcsProto.Unity.Ugui;

IProtoSystems _systems;

void Start () {        
    _systems = new ProtoSystems (new ProtoWorld (new Aspect1 ()));
    _systems
        // Attach injection module.
        .AddModule (new AutoInjectModule ())
        // Attach Unity integration module.
        .AddModule (new UnityModule ())
        .Add (new TestSystem1 ())
        // Attach uGUI integration module.
        .AddModule (new UnityUguiModule ())
        .Init ();
}

The uGUI module should be added at the place where processed uGUI events will be cleaned up. If you want to separate the registration point from the cleanup point, use a named order point and pass it to the UnityUguiModule constructor:

// Environment initialization.
using Leopotam.EcsProto;
using Leopotam.EcsProto.QoL;
using Leopotam.EcsProto.Unity;
using Leopotam.EcsProto.Unity.Ugui;

IProtoSystems _systems;

void Start () {        
    const int OrderUguiClearPoint = 123;
    _systems = new ProtoSystems (new ProtoWorld (new Aspect1 ()));
    _systems
        // Attach injection module.
        .AddModule (new AutoInjectModule ())
        // Attach Unity integration module.
        .AddModule (new UnityModule ())
        // Attach uGUI integration module for the default world
        // with cleanup at the OrderUguiClearPoint order weight.
        .AddModule (new UnityUguiModule (default, OrderUguiClearPoint))
        .Add (new TestSystem1 ())
        .Init ();
}

Automatic wiring of the whole module

// Environment initialization.
using Leopotam.EcsProto;
using Leopotam.EcsProto.QoL;
using Leopotam.EcsProto.Unity;
using Leopotam.EcsProto.Unity.Ugui;

IProtoSystems _systems;

void Start () {
    const int OrderUguiClearPoint = 123;
    ProtoModules modules = new ProtoModules (
        new AutoInjectModule (),
        new UnityModule (),
        new UnityUguiModule (default, OrderUguiClearPoint)
    );
    _systems = new ProtoSystems (new ProtoWorld (modules.BuildAspect ()));
    _systems
        // Attach composite module.
        .AddModule (modules.BuildModule ())
        .Add (new TestSystem1 ())
        .Init ();
}

Events

All supported event types are exposed by the uGUI aspect:

public sealed class UnityUguiAspect : ProtoAspectInject {
    public readonly ProtoPool<UnityUguiClickEvent> ClickEvent;
    public readonly ProtoPool<UnityUguiDownEvent> DownEvent;
    public readonly ProtoPool<UnityUguiDragEndEvent> DragEndEvent;
    public readonly ProtoPool<UnityUguiDragMoveEvent> DragMoveEvent;
    public readonly ProtoPool<UnityUguiDragStartEvent> DragStartEvent;
    public readonly ProtoPool<UnityUguiDropEvent> DropEvent;
    public readonly ProtoPool<UnityUguiEnterEvent> EnterEvent;
    public readonly ProtoPool<UnityUguiExitEvent> ExitEvent;
    public readonly ProtoPool<UnityUguiScrollViewEvent> ScrollViewEvent;
    public readonly ProtoPool<UnityUguiSliderChangeEvent> SliderChangeEvent;
    public readonly ProtoPool<UnityUguiDropdownChangeEvent> DropdownChangeEvent;
    public readonly ProtoPool<UnityUguiInputChangeEvent> InputChangeEvent;
    public readonly ProtoPool<UnityUguiInputEndEvent> InputEndEvent;
    public readonly ProtoPool<UnityUguiUpEvent> UpEvent;
}

You can build an iterator over any of them to handle user actions:

using Leopotam.EcsProto.Unity.Ugui;

public class TestUguiClickEventSystem : IProtoRunSystem {
    [DI] UnityUguiAspect _uguiEvents;
    [DI] ProtoIt _clickIt = new (It.Inc<UnityUguiClickEvent> ());
    
    public void Run () {
        foreach (ProtoEntity entity in _clickIt) {
            ref UnityUguiClickEvent data = ref _uguiEvents.ClickEvent.Get (entity);
            Debug.Log ("I'm clicked!", data.Sender);
        }
    }
}

Actions

Actions (xxxAction classes) are MonoBehaviour components that listen to uGUI widget events and generate the corresponding ECS events:

• UnityUguiClickAction
• UnityUguiDownAction
• UnityUguiDragEndAction
• UnityUguiDragMoveAction
• UnityUguiDragStartAction
• UnityUguiDropAction
• UnityUguiDropdownAction
• UnityUguiEnterAction
• UnityUguiExitAction
• UnityUguiInputChangeAction
• UnityUguiInputEndAction
• UnityUguiScrollViewAction
• UnityUguiSliderAction
• UnityUguiUpAction

License

This package is released under the MIT-ZARYA license, see details here.