Event Signal

Data-oriented signal system

Overview

The system provides a robust foundation for type-safe, event-driven communication between components while maintaining clean memory management and thread safety.

Project Settings

Signal Getter Timeout

getter will be retry automatically until timeout. default: 1.5s

Signal Trigger State

default trigger state if signal is built with trigger once per frame default: Early Update

Prewarm Providers

build signals after assembly ready.

Why Use It

Consider a UI component that displays a player's life: traditionally, this would require direct references to the Player or Life components. However, such tight coupling makes the UI component less reusable and more difficult to maintain. With Signal, the UI component simply subscribes to life-related signals, making it project-agnostic and highly reusable.

While there are numerous dependency injection and reference management solutions available, many of these packages introduce unnecessary complexity. Unlike engines such as Godot that have built-in signal systems, Unity's traditional GameObject-Component architecture doesn't include a native signal system. However, Unity's flexible architecture allows us to implement custom solutions, which is where this Signal system comes in.

Signals can be created and accessed from anywhere in your codebase, enabling flexible and decoupled system design. This flexibility does come with a responsibility: while powerful, signals should be used thoughtfully and systematically to avoid creating complex, hard-to-debug signal chains.

Key Benefits:

Decoupled component communication
Improved code reusability
Lightweight implementation
Flexible system design

API

// base API
Signal

// Signal Builder
Signal.Builder().ActionsChain();
Signal.LinkerBuilder().ActionsChain();

// Signal Getter
ISignal signal = Signal.GetOrCreate("Signal Id");
bool result = Signal.TryGet("Signal ID", out ISignal signal);
bool result = Signal.TryGetlinker("Signal ID", out ISignalLinker linker);
bool result = Signal.TryGetListener(Enum.SignalId, out ISignalListener signal);
bool result = Signal.TryGetTrigger(Enum.SignalId, out ISignalTrigger signal);
ISignal<T> signal = Signal<T>.GetOrCreate("Signal Id");
bool result = Signal<T>.TryGet(Enum.SignalId, out ISignal<T> signal);
bool result = Signal<T>.TryGetReadonly(Enum.SignalId, out IReadonlySignal<T> signal);
bool result = Signal<T>.TryGetListener(Enum.SignalId, out ISignalListener<T> signal);
bool result = Signal<T>.TryGetTrigger(Enum.SignalId, out ISignalTrigger<T> signal);

// Signal Getter Async
// see sample and Package Task Utils
Promise<ISignal> promise = Signal.GetAsync("Signal ID");
Promise<ISignalLinker > promise = Signal.GetLinkerAsync("Signal ID");
Promise<ISignalListener > promise = Signal.GetAsListenerAsync(Enum.SignalId);
Promise<ISignalTrigger > promise = Signal.GetAsTriggerAsync(Enum.SignalId);
Promise<ISignal<T>> promise = Signal<T>.GetAsync("Signal ID");
Promise<IReadonlySignal<T>> promise = Signal<T>.GetAsReadonlyAsync("Signal ID");
Promise<ISignalListener <T>> promise = Signal<T>.GetAsListenerAsync(Enum.SignalId);
Promise<ISignalTrigger <T>> promise = Signal<T>.GetAsTriggerAsync("Signal ID");

Quick Start

Signal provides a robust event-driven value management system with built-in observer pattern support and type safety.

PlayerLoopState is using Player Loop Hack, please see document for details.

// build a signal without value
ISignal signal = Signal.Builder()    // Get Builder
    .WithId("id")    // optional: set id, new guid if ignore
    .Build();

// build a signal with value
ISignal<int> signal = Signal.Builder()
    .WithId(MyEnum.id)    // id can be an enum value
    .WithValue<int>(1)    // set value
    .Build();

// build a signal with value, and force observers get readonly
ISignal<int> signal = Signal.Builder()
    .WithValue<MyClass>()    // set value type only if value is not created
    .BuildReadonly();
    
// build a signal trigger once per frame
// will trigger in default state in project settings
ISignal signal = Signal.Builder()
    .WithTriggerOncePerFrame()    // on default state in settings
    .Build();
    
// build a signal trigger once per frame with specified state
ISignal<int> signal = Signal.Builder()
    .WithTriggerOncePerFrame(PlayerLoopState)    // on specified state
    .WithValue(4)
    .Build();

GetAsync() is using Promise. Please read Task Utils for details.

// try to get an existing signal
// returning bool for verify result
Signal.TryGet("id", out ISignal signal)
Signal<int>.TryGet(myEnum.Id, out ISignal<int> signal)

// try to get existing signal in limited usage
// see Signal Permissions section
// returning bool for verify result
Signal<int>.TryGetReadonly("id", out IReadonlySignal<int> signal);
Signal<int>.TryGetListener("id", out ISignalListener<int> signal);
Signal<MyClass>.TryGetTrigger(myEnum.Id, out ISignalTrigger<MyClass> signal);

// get a signal but not confirm the existence
// on case build and get in same state
ISignal signal;
Signal.GetAsync("id")
    .Then(s => signal = s)
    .Catch(e => Debug.LogError(e));
    
// on case get or create a signal
// value must be null or default
ISignal<int> signal = Signal<int>.GetOrCreate("id");
ISignal signal = Signal.GetOrCreate("id");

Signal signal;
Signal<int> valueSignal;

// listen
signal.AddListener(OnValueTriggered, runImmediately: true);
valueSignal.AddListener(OnValueChanged);
void OnValueTriggered();
void OnValueChanged(int value)

// unlisten
signal.RemoveListener(OnValueTriggered);
valueSignal.RemoveListener(OnValueChanged);

// modify value
// valueSignal will be triggered on value changed.
valueSignal.Value = 75;

// trigger manually
signal.Trigger();
valueSignal.Trigger();

please see section Signal Permissions and Type Conversion for details.

Signal signal;
Signal<int> valueSignal;

// turn a Signal<T> to ReadonlySignal<T>
IReadonlySignal<int> readonlySignal = valueSignal.AsReadonly()

// turn a Signal or Signal<T> to SignalListerner or SignalListerner<T>
ISignalLister signalListener = signal.AsListener();
ISignalLister<int> signalListener = valueSignal.AsListener();

// turn a Signal or Signal<T> to SignalTrigger
ISignalTrigger signalTrigger = signal.AsTrigger();
ISignalTrigger<int> signalTrigger = valueSignal.AsTrigger();

Signal Permissions

Different type of signal defines the permissions. Select the correct signal for observers.

Type Conversion

Conversion between different signal type is possible. However conversion from ISignal to other types is inversable.

Trigger Once Per Frame

Signal is defaultly triggered immediately on value changed or Trigger() is called. This confirms all observers can be noticed the changes in time.

To prevent from duplicated trigger in same frame, use WithTriggerOncePerFrame() in builder.

When signal is built with trigger once per frame, observers will receive the last trigger before next specified state which may be next frame.

Please read Technical Details in Player Loop Hack for details.

Signal Linker

Linking up multiple Signals for handling multiple signals condition. Accepting only Signal with value.

Setting up signal linker is easy:

create a linker with builder
add adaptor with params
- signalListener: one of signal as Listener
- condition: how to check as true
- option: how consider with other conditions
add listener(s) to linker, listener must received a boolean
- change of any signal in linker will trigger the listener
- true will be return on signal is disposed, and a warning log will be sent
do not forget to dispose the linker

If the signal in linker is disposed, a warning log will be shown, and condition of this adaptor will be true.

There is not result field or Trigger() in linker. The only way to receive condition change event is listener.

Building a linker request almost nothing. Options are all optional.

Any trigger of signals in linker will trigger the linker.

To prevent from duplicated trigger in same frame, use WithTriggerOncePerFrame.

ISignalLinker signalLinker = Signal.LinkerBuilder()
    .WithId("linker")    // optional
    .WithTriggerOncePerFrame(PlayerLoopState.PreUpdate)    // optional
    .Build();

Adaptor is a condition option handler. Adding adaptors to linker to add more condition checking on signals triggered.

// different value signals
ISignal<string> signalA = Signal.Builder().WithValue("apple").Build();
ISignal<int> signalB = Signal.Builder().WithValue(100).Build();
ISignal<bool> signalC = Signal.Builder().WithValue(false).Build();
ISignal<bool> signalD = Signal.Builder().WithValue(false).Build();

// add adaptor to linker
// AdaptorOption decided the way to check the condition of signals in linker.
// in this example, 
//   - Signal A and B must be both true, but A value is in lower case,
//   - either C and D is true, but D should be true with enabled
signalLinker.AddAdaptor(
    signalListener: signalA.AsListener(),
    condition: value => value.ToLower() == "orange", // value is Signal Listener value
    option: AdaptorOption.And);
signalLinker.AddAdaptor(
    signalListener: signalB.AsListener(),
    conditionValue: 101, // compare with Signal Listener value
    option: AdaptorOption.And);
signalLinker.AddAdaptor(
    signalC.AsListener(),
    true,
    AdaptorOption.Or);
signalLinker.AddAdaptor(
    signalD.AsListener(),
    value => value && enabled,
    AdaptorOption.Or);

Adding listener to linker is the only method to listener the condition.

// add listener to linker
// it will be trigger on any signal value in linker is changed
signalLinker.AddListener(OnLinker);

// this is only way to receive condition change event of linker
private void OnLinker(bool result)
{
    Debug.Log($"OnLinker: {result}");
}

// remove listener from linker
signalLinker.RemoveListener(OnLinker);

// remove all listeners from linker
signalLinker.RemoveAllListeners();

Recommended Usage

In any system, regardless of its size, proper signal management is crucial for maintaining code clarity and preventing runtime issues. Even in small applications, you'll likely find yourself handling dozens of signals across multiple objects, making a well-organized structure essential.

Below is our recommended approach to signal management, which we use in production. This pattern offers several advantages:

Type Safety: Using enums for signal IDs prevents typos and enables IDE auto-completion
State Management: Integration with Promise/Task utilities ensures safe asynchronous operations and prevents common runtime issues like timing problems during initialization
Code Organization: Clear structural patterns make the system easy to maintain and scale

While this is our recommended approach, feel free to adapt it to your specific needs. The following example demonstrates how we structure signal systems in our own projects.

Create Signal IDs by Enum(s)

public enum SignalId
{
    HP = 10,
    MP = 20,
}

Build the Player Life component

using AceLand.EventDriven.EventSignal;
using UnityEngine;

public class PlayerLife : MonoBehaviour
{
    [SerializeField] private int hp;
    [SerializeField] private int mp;

    private Signal<int> hpSignal;
    private Signal<int> mpSignal;
    
    private void Start()
    {
        // build signals of values
        // trigger once on default EarlyUpdate state
        // force observer get readonly
        hpSignal = Signal.Builder()
            .WithId(SignalId.HP)
            .WithTriggerOncePerFrame()
            .WithValue(hp)
            .Build();
        mpSignal = Signal.Builder()
            .WithId(SignalId.MP)
            .WithTriggerOncePerFrame()
            .WithValue(mp)
            .Build();
    }
    
    private void OnDestroy()
    {
        hpSignal?.Dispose();
        mpSignal?.Dispose();
    }
}

Dynamic method to create an UI Text Updater with signal.

using AceLand.EventDriven.EventSignal;
using AceLand.TaskUtils;
using TMPro;
using UnityEngine;

// Generic Signal Type can fulfill any type of Signal
[RequireComponent(typeof(TextMeshProUGUI))]
public class UiTextUpdateWithSignal : UIBehaviour
{
    // Select Signal ID in Inspector.
    [SerializeField] private SignalId signalId;

    // require only listener
    private ISignalListener<int> _signal; 
    private TextMeshProUGUI _label;

    protected override void Awake()
    {
        _label = GetComponent<TextMeshProUGUI>();
    }
    
    protected override void OnEnable()
    {
        if (_signal != null) {
            _signal.AddListener(OnSignalUpdate, runImmediately: true);
            return;
        }

        // Get Readonly Signal with Promise Awaiter
        Signal<T>.GetListenerAsync(signalId)
            .Then(signal => {
                _signal = signal;
                signal.AddListener(OnSignalUpdate, runImmediately: true);
            })
            .Catch(e => Debug.LogError(e, this));
            
        return;
    }
    
    protected override void OnDisable()
    {
        _signal?.RemoveListener(OnSignalUpdate);
    }

    private void OnSignalUpdate(int value)
    {
        _label.text = ValueToStringProvider(value);
    }

    // custom label display by override Provider.
    protected virtual string ValueToStringProvider(int value)
    {
        return value.ToString();
    }
}

please read Task Utils for details of Promise Awaiter.

Prewarm Provider

Signals almost use on creating in runtime, and the lifetime should be same as GameObject or Scene. On the case of long-term signals, creating prewarm providers is the best options.

Prewarm Provider is a scriptable object. System will build the signal after assembly ready state. When the scene starts to load, all signals are already ready. This can also prevent from GetAsync process.

using AceLand.EventDriven.Profiles;
using AceLand.Test;
using UnityEngine;

[CreateAssetMenu(fileName = "Signal Prewarm", menuName = "Profiles/Signal Prewarm")]
public class SignalPrewarm : SignalPrewarmProvider<SignalId, int>
{
    public override void PrewarmSignal()
    {
        base.PrewarmSignal();
    }

    public override void Dispose()
    {
        base.Dispose();
    }
}

public enum SignalId
{
    HP, MP, SP
}

Exceptions

On GetAsync or GetReadonlyAsync function, exceptions will be returned on errors.

Exception

Description

SignalNotFoundException

When signal is not found with given ID

SignalTypeErrorException

When signal with wrong given value type - only on Signal with value

SignalReadonlyAlertException

When signal is built as Readonly but using GetAsync - only on Signal with value

Signal<int>.GetAsync("ID")
    .Then(OnGetSignal)
    .Catch<SignalNotFoundException>(OnSignalNotFound)
    .Catch<SignalTypeErrorException>(OnSignalTypeError)
    .Catch<SignalReadonlyAlertException>(OnSignalReadonly)
    .Catch(Debug.LogError);

Advanced Use

An example of runtime instantiated a set of UI Elements and a control of Element Group.

Element is Tag Element. Tags will be a button and will be instantiated different amount in runtime.

Group is Tags Group for instantiating and controlling all tag elements.

Tag Element is controlling a single Tag. By received a pointer click to trigger a tag selection for Tags Group to do further actions.

Tag Element should control the UI behaviour only. UI Behaviour should not contains business logics. Tags Group contains business logics and wait for UI behaviours - on pointer clicked event.

In this case, when Tags Group instantiates a Tag Element, it will build a new Signal with signal id as value and record in tag elements collection. This signal will pass to Tag Element and will be triggered on pointer clicked.

using System;
using System.Collections.Generic;
using AceLand.EventDriven.EventSignal;
using AceLand.Library.Extensions;
using UnityEngine;
using UnityEngine.EventSystems;
using ZLinq;

[DisallowMultipleComponent]
public sealed class TagsGroup : MonoBehaviour
{
    [Header("Tags Group")]
    [SerializeField] private Transform container;
    [SerializeField] private TagElement prefab;
    
    // record Signals and Tag Elements
    private readonly Dictionary<ISignal, TagElement> tags = new ();

    private void Awake()
    {
        if (!container)
            container = transform;
        
        if (!prefab)
            Debug.LogWarning("Tags Group Control: Prefab is not set.", this);
    }

    public void BuildTags(TagData[] tagsData)
    {
        // build tags from tags data
        foreach (var tagData in tagsData)
        {
            string label = tagData.Label;
            ISignal signal = BuildSignal();
            TagElement tagElement = Instantiate(prefab, container);
            tagElement .Initial(signal.AsTrigger(), label);
            tags[signal] = tagElement ;
        }
        
        // select first tag
        tags.AsValueEnumerable().First().Value.Tag.Select();
    }

    // build a Signal<string>
    // asign own id as value
    // add listener
    private ISignal BuildSignal()
    {
        ISignal signal = Signal.Builder().Build();
        signal.AddListener(() => OnTagSelected(signal.Id));
        return signal.AsReadonly();
    }

    // unselect not selected tags
    // do stuffs for selected tag
    private void OnTagSelected(string id)
    {
        foreach (var (key, tagData) in tags)
        {
            if (key != id)
            {
                tagData.Tag.Unselect();
                continue;
            }
            
            // stuffs on selected tag
        }
    }

    // dispose signals
    // destroy all Tag Elements
    private void RemoveTags()
    {
        foreach (var signal in tags.Keys)
            signal.Dispose();
        
        // Library Extension
        container.DestroyAllChildren();
        tags.Clear();
    }
}

using AceLand.EventDriven.EventSignal;
using TMPro;
using UnityEngine;
using UnityEngine.EventSystems;

[DisallowMultipleComponent]
// us UIBehaviour for UI Element
public sealed class TagElement : UIBehaviour, IPointerClickHandler
{
    [SerializeField] private TextMeshProUGUI label;

    private bool selected;
    private ISignalTrigger onSelectSignal;

    protected override void Awake()
    {
        if (label) return;
        
        Debug.LogWarning("Tag Control: TextMesh not found.", this);
        enabled = false;
    }
    
    // initial tag with Signal from Tags Group
    public void Initial(ISignalTrigger selectSignal, string tagName)
    {
        if (!label) return;
        
        onSelectSignal = selectSignal;
        label.text = string.IsNullOrEmpty(tagName) ? "Anonymous" : tagName;
    }
    
    // handle pointer clicked event
    public void OnPointerClick(PointerEventData eventData)
    {
        if (!label || selected) return;
        
        Select();
    }

    // trigger signal
    public void Select()
    {
        onSelectSignal?.Trigger();
    }
    
    // stuffs for unselect
    public void Unselect()
    {
        // stuffs
    }
}

PreviousEvent Bus NextInput

Last updated 22 days ago