Event Based Blackboard

What is Event Based Blackboard?

Event Based Blackboard for Unity is a flexible data storage that can contain any count of properties of any type. The properties can be accessed with property names. Any part of a code can subscribe to a blackboard value change and receive a callback.

The main advantage of Event Based Blackboard is that it allocates as little as possible. Also it has good enough performance.

Installation

This repo is a regular Unity package. You can install it as your project dependency. More here: https://docs.unity3d.com/Manual/upm-dependencies.html.

Usage

Setup

As a Unity component

1. Add a BlackboardContainerComponent to a GameObject in your scene. You can find it in Add Component/Event Based Blackboard/Main/Blackboard Container. That component automatically creates a Blackboard inside. You can access it via BlackboardContainerComponent.blackboard property.
2. Add a Flusher. You can find them in Add Component/Event Based Blackboard/Main/Flushers/. You have to add a Flusher because Blackboard doesn't apply changes until a special method is called which is done by a Flusher. As a Blackboard flushed all changes, it sends callbacks.

As a regular c# class

Simply create a Blackboard with its default constructor: new Blackboard(). You may get all the features of the Event Based Blackboard this way too. But you have to call Blackboard.Flush() yourself to apply changes and send callbacks.

Blackboard API

• TryGetValue() tries to get and return a value of a specified type and property name.
• SetValue() sets a value of of specified type and property name into a buffer.
• Subscribe() subscribes a specified callback to a value change of a specified type and property name.
• Unsubscribe() unsubscribes a specified callback from a value change of a specified type and property name.
• Flush() applies all set into buffers values and sends callbacks of their changes.

Those are main methods of Blackboard, you can find more in its source code.

All the methods of Blackboard use BlackboardPropertyName as a property name, not string. You can create that struct with one of its constructors. It transforms strings into unique integer ids. That makes work of Blackboard faster. But it's not recommended to create a new BlackboardPropertyName every time, cache it.

Serialization

If you use a Blackboard as a regular c# class, you have to support serialization yourself.

If you use a BlackboardContainerComponent, you can create a Serialized Tables Container in Assets/Create/Event Based Blackboard/Serialized Tables Container and link it in your BlackboardContainerComponent. It will automatically apply all properties of a Serialized Tables Container on Awake().

How to customize serialization

Although there are many types supported by Event Based Blackboard out of the box, you may need to serialize more types or your own types. In that case, you need to inherit GeneratedValueSerializedTable or SerializedValueSerializedTable.

If you need a full customizable serialized table, you can inherit SerializedTable_Base.

If you need a full customizable serialized container, you can inherit SerializedContainer.

Blackboard editor support

Because Unity draws only serialized by itself properties, properties of a Blackboard aren't drawn by Unity. But BlackboardContainerComponent has a custom editor to show and make editable all of its Blackboard properties. Although there are many types that are drawn out of the box, you may need to draw more types in Unity editor. You can achieve it by inheriting BlackboardValueView or UnityObjectBlackboardValueView.

Logs

There is a special class for logging the whole Blackboard system: BlackboardDebug. It contains conditional methods for logging. You can control a compilation of those methods with define symbols:

• EVENT_BLACKBOARD_LOG_DETAILS - log every change of the Blackboard system.
• EVENT_BLACKBOARD_LOG
• EVENT_BLACKBOARD_LOG_WARNING
• EVENT_BLACKBOARD_LOG_ERROR

BlackboardDebug has all of them as public const strings.

Little features

BlackboardPropertyReference

It's a simple serializable struct with two fields: reference to BlackboardContainerComponent and property name of string type. It has a custom editor that makes a selector for the property name field. The selector is filled with property names of all serialized properties of the referenced BlackboardContainerComponent. It's recommended to use it for custom components where you need to reference a specific property in a Blackboard of a BlackboardContainerComponent.

Event

It's an empty struct which comparisons are always false. It's useful to make a Blackboard event because setting it will always cause sending callbacks.

Extensions

You can find useful extensions for Event Based Blackboard in the different repo: https://github.com/ZorPastaman/Event-Based-Blackboard-Extensions.

See also

• Simple Blackboard - another version of a blackboard system which doesn't support events but requires much less memory.