Unity Foundation - Notification Center

A simple event system for Unity + C#.

NOTICE

This package is not considered production-ready. Breaking changes are common and support is limited. Use at your own risk.

Installation

Recommended Installation (Unity Package Manager)

"Add package from git URL..."
https://github.com/ryanslikesocool/UnityFoundation-NotificationCenter.git

Usage

NotificationCenter creates a default shared instance the first time it is accessed in C#.

Notifications

A Notification.Name is the primary identifier for notifications. It is required to send and receive notifications, and should be initialized once and cached.

static readonly Notification.Name myNotificationName = new Notification.Name("my super special notification");

Events are passed around with associated data, stored in a Notification. Each Notification has the following properties:

Property	Description
`Notification.Name name`	The notification's primary identifier.
`object sender`	The object that this notification was sent from. (Optional)
`object data`	Associated data that the sender provides. (Optional)

Adding and Removing Observers

Add and remove notification observers for recieving events with NotificationCenter.Default.AddObserver and NotificationCenter.Default.RemoveObserver. In most cases, this would be in an object's initialization and deinitialization stages.

void AddMyObserver() {
    // notifications will be posted to `MyObserver` after this is called.
    NotificationCenter.Default[myNotificationName].received += MyObserver;
}

void RemoveMyObserver() {
    // notifications will no longer be posted to `MyObserver` after this is called.
    NotificationCenter.Default[myNotificationName].received -= MyObserver;
}

Posting Notifications

When posting a notification, the notification name is required. Any observers that listen for myNotificationName will recieve the following notification. The sender and data are not required.

void PostMyNotification() {
    // the notification sender can be of any type, but it should be a class.
    object mySender = this;

    // the notification data can be of any type.
    object myData = 42; // int

    NotificationCenter.Default[myNotificationName].Post(mySender, myData);
}

Observing

// this function will be called every time it recieves a notification with the name `myNotificationName`
// note the `in` keyword here
void MyObserver(in Notification notification) {
	// safely unwrap the provided data...
	if(notification.TryReadData(out int integer)) {
        Debug.Log(integer); // 42
	}

    // ...forcefully unwrap it...
	int integer = notification.ReadData(); // 42
	MonoBehaviour mb = notification.ReadData(); // error!

	// ...or access it directly
	object data = notification.data;
}

Safety

void MyObserver(in Notification notification) {
	if (notification.name != myNotificationName) {
		throw new NotificationCenter.UnexpectedName(notification, expected: myNotificationName);
	}
	if (notification.sender != mySender) {
		throw new NotificationCenter.UnexpectedSender(notification, expected: mySender);
	}
	if (!notification.TryReadData(out int integer)) {
		throw new NotificationCenter.UnexpectedData(notification, expected: typeof(int));
	}

	// notification name, sender, and data are all valid
	Debug.Log(integer); // 42
}

ryanslikesocool/UnityFoundation-NotificationCenter