Overview

Unity package library for sending and receiving events between components and across multiple scenes.

Heavily inspired by the infamous Unite 2017: Game Architecture with Scriptable Objects presentation by Ryan Hipple (GitHub).

Unfortunately Unity does not understand generics in the Editor and Inspectors, so only concrete types can be used. Fortunately, this can be made easy by deriving from a single generic type allowing the same common behaviors.

NOTE: This package is still in development and may have breaking changes in future versions until a stable v1.0.0 release is made.

Changelog

All notable changes to this library will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.4.2] - 2022-12-28

Added

ScriptableObjectEventChannel variant
ScriptableObjectEventListener component
Icons for event channels in the Editor
Icons for event listeners in the Editor

[0.4.1] - 2022-12-08

Fixed

Missing meta files

[0.4.0] - 2022-12-04

Added

ColorEventChannel variant
ColorEventListener component
Vector2IntEventChannel variant
Vector2IntEventListener component
Vector2EventChannel variant
Vector2EventListener component
Vector3EventChannel variant
Vector3EventListener component
Vector4EventChannel variant
Vector4EventListener component

[0.3.1] - 2022-12-04

Added

Docs via mdbook in Documentation~ directory
GitHub CI/CD workflows for documentation

Changed

Exposed Channel getter property on EventListener component

[0.3.0] - 2022-12-01

Added

EventChannelEditor - custom editor
EventListenerEditor<TChannel> - abstract base class
VoidEventListenerEditor - custom editor
RaiseEvent(int) method for DoubleEventChannel
RaiseEvent(float) method for DoubleEventChannel
RaiseEvent(int) method for FloatEventChannel
RaiseEvent(bool) method for StringEventChannel
RaiseEvent(int) method for StringEventChannel
RaiseEvent(float) method for StringEventChannel
RaiseEvent(double) method for StringEventChannel
RaiseEvent(int) method for DoubleEventListener
RaiseEvent(float) method for DoubleEventListener
RaiseEvent(int) method for FloatEventListener
RaiseEvent(bool) method for StringEventListener
RaiseEvent(int) method for StringEventListener
RaiseEvent(float) method for StringEventListener
RaiseEvent(double) method for StringEventListener

Fixed

Small fixes in Listeners sample scene

[0.2.0] - 2022-12-01

Added

EventListener<TChannel> abstract base class
EventListener<T, TChannel> abstract base class
BoolEventListener component
DoubleEventListener component
FloatEventListener component
IntEventListener component
StringEventListener component
TransformEventListener component
VoidEventListener component
Listeners sample scene

Fixed

Root namespace should now be UnderLogic.Channels

[0.1.0] - 2022-12-01

Added

EventChannel abstract base class
EventChannel<T> abstract base class
BoolEventChannel variant
DoubleEventChannel variant
FloatEventChannel variant
IntEventChannel variant
StringEventChannel variant
TransformEventChannel variant
VoidEventChannel variant
Channels sample scene

Installation

OpenUPM

OpenUPM is an open source Unity package registry that allows you to easily install thousands of packages.

You can install this library with the following CLI command:

$ openupm add com.underlogic.event-channels

Git URL

Starting with Unity 2019.3 you can add packages via git url. You can add this package by the following url: https://github.com/UnderLogic/event-channels

Using this method will allow you to update the package through the Unity Package Manager.

Local Package

Alternatively, you can clone the git repository and add the package locally.

Getting Started

Context

To best understand the purpose of this library and the problems it solves, it is highly recommended to watch the Unite 2017: Game Architecture with Scriptable Objects by Ryan Hipple.

Use Cases

Event Bus

The common case of needing to notify various components of events within an application, potentially across multiple scenes. Includes the ability to chain events to cascade logic and triggers in sequence. Easy to drag and drop references in the Editor and view/modify them in the Inspector during play mode.

Decoupling

The common case of having multiple observers of a single event being able to react independently of each other. For example, playing a sound while also showing a game over screen when the player dies. This helps enforce the single responsibility principle as well as reduce tight coupling between types.

Event-Based Architecture

The case of only wanting to update or perform actions when necessary (reactively) instead of wastefully computing each frame. This is very common in UI-heavy applications.

See runtime-variables library in the related-libraries section for working with observable variables and runtime-collections library in the related-libraries section for working with observable collections.

Samples

The Samples~ folder contains sample scenes showcasing various aspects of the library in action. It is recommended to import and play around with them in Unity to get a feel for how to use the library.

Custom Events

While this library provides many of the common Unity types you will use, you may want to extend this library with your own custom events specific to your application. Fortunately, this is rather easy and typically only involves creating a derived class from one of the base classes. You may also add any additional helper properties and methods as you need.

Channels

Create a new class that derives from EventChannel<T>, where T should be the type of event data.
Ensure the new type is marked with the CreateAssetMenu attribute, so you can create instances in the Editor.
Create any instances of the new event channel in your Assets folder.
Now you can use them throughout your application.

NOTE: If you want a custom VoidEventChannel, derive from that class instead of the EventChannel base class. This will ensure you also get the custom editor for manually invoking the event.

Listeners

Create a new class that derives from EventListener<T, TChannel> where T should be the underlying type and TChannel is the event channel type.
Now you can use the event listener in your components

NOTE: If you want a custom VoidEventListener, derive from that class instead of the EventListener<TChannel> base class. This will ensure you also get the custom editor for manually invoking the event.

Channels

Overview

Event channels are implemented as ScriptableObject instances that can be raise events between components and across scenes. They provide a UnityAction event when an event is raised.

Many of the event channels provide helper methods that make it easier to raise events from other components, including UnityEvent bindings. This can be especially useful when using the Listener components.

EventChannel

Abstract base class that all other non-data event channels derive from.

Event Channels