 |
ezEngine
Release 25.03
|
|
ezEngine
Release 25.03
|
A blackboard is a key/value store that provides OnChange events to be informed when a value changes. More...
#include <Blackboard.h>
Classes | |
| struct | Entry |
| struct | EntryEvent |
Public Member Functions | |
| bool | IsGlobalBlackboard () const |
| void | SetName (ezStringView sName) |
| Changes the name of the blackboard. More... | |
| const char * | GetName () const |
| const ezHashedString & | GetNameHashed () const |
| void | RemoveEntry (const ezHashedString &sName) |
| Removes the named entry. Does nothing, if no such entry exists. | |
| void | RemoveAllEntries () |
| Removes all entries. | |
| bool | HasEntry (const ezTempHashedString &sName) const |
| Returns whether an entry with the given name already exists. | |
| void | SetEntryValue (ezStringView sName, const ezVariant &value) |
| Sets the value of the named entry. If the entry doesn't exist, yet, it will be created with default flags. More... | |
| void | SetEntryValue (const ezHashedString &sName, const ezVariant &value) |
| Overload of SetEntryValue() that takes an ezHashedString rather than an ezStringView. More... | |
| const Entry * | GetEntry (const ezTempHashedString &sName) const |
| Returns a pointer to the named entry, or nullptr if no such entry was registered. | |
| ezBitflags< ezBlackboardEntryFlags > | GetEntryFlags (const ezTempHashedString &sName) const |
| Returns the flags of the named entry, or ezBlackboardEntryFlags::Invalid, if no such entry was registered. | |
| ezResult | SetEntryFlags (const ezTempHashedString &sName, ezBitflags< ezBlackboardEntryFlags > flags) |
| Sets the flags of an existing entry. Returns EZ_FAILURE, if it wasn't created via SetEntryValue() or SetEntryValue() before. | |
| ezVariant | GetEntryValue (const ezTempHashedString &sName, const ezVariant &fallback=ezVariant()) const |
| Returns the value of the named entry, or the fallback ezVariant, if no such entry was registered. | |
| ezVariant | IncrementEntryValue (const ezTempHashedString &sName) |
| Increments the value of the named entry. Returns the incremented value or an invalid variant if the entry does not exist or is not a number type. | |
| ezVariant | DecrementEntryValue (const ezTempHashedString &sName) |
| Decrements the value of the named entry. Returns the decremented value or an invalid variant if the entry does not exist or is not a number type. | |
| const ezHashTable< ezHashedString, Entry > & | GetAllEntries () const |
| Grants read access to the entire map of entries. | |
| const ezEvent< const EntryEvent & > & | OnEntryEvent () const |
| Allows you to register to the OnEntryEvent. This is broadcast whenever an entry is modified that has the flag ezBlackboardEntryFlags::OnChangeEvent. | |
| ezUInt32 | GetBlackboardChangeCounter () const |
| This counter is increased every time an entry is added or removed (but not when it is modified). More... | |
| ezUInt32 | GetBlackboardEntryChangeCounter () const |
| This counter is increased every time any entry's value is modified. More... | |
| ezResult | Serialize (ezStreamWriter &inout_stream) const |
| Stores all entries that have the 'Save' flag in the stream. | |
| ezResult | Deserialize (ezStreamReader &inout_stream) |
| Restores entries from the stream. More... | |
 Public Member Functions inherited from ezRefCounted | |
| virtual | ~ezRefCounted ()=default |
| Adds a virtual destructor. | |
| Public Member Functions inherited from ezRefCountingImpl | |
| ezRefCountingImpl ()=default | |
| Constructor. | |
| ezRefCountingImpl (const ezRefCountingImpl &rhs) | |
| void | operator= (const ezRefCountingImpl &rhs) |
| ezInt32 | AddRef () const |
| Increments the reference counter. Returns the new reference count. | |
| ezInt32 | ReleaseRef () const |
| Decrements the reference counter. Returns the new reference count. | |
| bool | IsReferenced () const |
| Returns true if the reference count is greater than 0, false otherwise. | |
| ezInt32 | GetRefCount () const |
| Returns the current reference count. | |
Static Public Member Functions | |
| static ezSharedPtr< ezBlackboard > | Create (ezAllocator *pAllocator=ezFoundation::GetDefaultAllocator()) |
| Factory method to create a new blackboard. More... | |
| static ezSharedPtr< ezBlackboard > | GetOrCreateGlobal (const ezHashedString &sBlackboardName, ezAllocator *pAllocator=ezFoundation::GetDefaultAllocator()) |
| Factory method to get access to a globally registered blackboard. More... | |
| static ezSharedPtr< ezBlackboard > | FindGlobal (const ezTempHashedString &sBlackboardName) |
| Finds a global blackboard with the given name. | |
A blackboard is a key/value store that provides OnChange events to be informed when a value changes.
Blackboards are used to gather typically small pieces of data. Some systems write the data, other systems read it. Through the blackboard, arbitrary systems can interact.
For example this is commonly used in game AI, where some system gathers interesting pieces of data about the environment, and then NPCs might use that information to make decisions.
|
static |
Factory method to create a new blackboard.
Since blackboards use shared ownership we need to make sure that blackboards are created in ezCore.dll. Some compilers (MSVC) create local v-tables which can become stale if a blackboard was registered as global but the DLL which created the blackboard is already unloaded.
See https://groups.google.com/g/microsoft.public.vc.language/c/atSh_2VSc2w/m/EgJ3r_7OzVUJ?pli=1
| ezResult ezBlackboard::Deserialize | ( | ezStreamReader & | inout_stream | ) |
Restores entries from the stream.
If the blackboard already contains entries, the deserialized data is ADDED to the blackboard. If deserialized entries overlap with existing ones, the deserialized entries will overwrite the existing ones (both values and flags).
|
inline |
This counter is increased every time an entry is added or removed (but not when it is modified).
Comparing this value to a previous known value allows to quickly detect whether the set of entries has changed.
|
inline |
This counter is increased every time any entry's value is modified.
Comparing this value to a previous known value allows to quickly detect whether any entry has changed recently.
|
static |
Factory method to get access to a globally registered blackboard.
If a blackboard with that name was already created globally before, its reference is returned. Otherwise it will be created and permanently registered under that name. Global blackboards cannot be removed. Although you can change their name via "SetName()", the name under which they are registered globally will not change.
If at some point you want to "remove" a global blackboard, instead call UnregisterAllEntries() to clear all its values.
| void ezBlackboard::SetEntryValue | ( | const ezHashedString & | sName, |
| const ezVariant & | value | ||
| ) |
Overload of SetEntryValue() that takes an ezHashedString rather than an ezStringView.
Using this function is more efficient, if you access the blackboard often, but you must ensure to only create the ezHashedString once and cache it for reuse. Assigning a value to an ezHashedString is an expensive operation, so if you do not cache the string, prefer to use the other overload.
| void ezBlackboard::SetEntryValue | ( | ezStringView | sName, |
| const ezVariant & | value | ||
| ) |
Sets the value of the named entry. If the entry doesn't exist, yet, it will be created with default flags.
If the 'OnChangeEvent' flag is set for this entry, OnEntryEvent() will be broadcast. However, if the new value is no different to the old, no event will be broadcast.
For new entries, no OnEntryEvent() is sent.
For best efficiency, cache the entry name in an ezHashedString and use the other overload of this function. DO NOT RECREATE the ezHashedString every time, though.
| void ezBlackboard::SetName | ( | ezStringView | sName | ) |
Changes the name of the blackboard.
1.8.17