 |
Plasma Engine
2.0
|
|
Plasma Engine
2.0
|
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 (plStringView sName) |
| Changes the name of the blackboard. | |
| const char * | GetName () const |
| const plHashedString & | GetNameHashed () const |
| void | RemoveEntry (const plHashedString &sName) |
| Removes the named entry. Does nothing, if no such entry exists. | |
| void | RemoveAllEntries () |
| Removes all entries. | |
| bool | HasEntry (const plTempHashedString &sName) const |
| Returns whether an entry with the given name already exists. | |
| void | SetEntryValue (plStringView sName, const plVariant &value) |
| Sets the value of the named entry. If the entry doesn't exist, yet, it will be created with default flags. | |
| void | SetEntryValue (const plHashedString &sName, const plVariant &value) |
| Overload of SetEntryValue() that takes an plHashedString rather than an plStringView. | |
| const Entry * | GetEntry (const plTempHashedString &sName) const |
| Returns a pointer to the named entry, or nullptr if no such entry was registered. | |
| plBitflags< plBlackboardEntryFlags > | GetEntryFlags (const plTempHashedString &sName) const |
| Returns the flags of the named entry, or plBlackboardEntryFlags::Invalid, if no such entry was registered. | |
| plResult | SetEntryFlags (const plTempHashedString &sName, plBitflags< plBlackboardEntryFlags > flags) |
| Sets the flags of an existing entry. Returns PL_FAILURE, if it wasn't created via SetEntryValue() or SetEntryValue() before. | |
| plVariant | GetEntryValue (const plTempHashedString &sName, const plVariant &fallback=plVariant()) const |
| Returns the value of the named entry, or the fallback plVariant, if no such entry was registered. | |
| plVariant | IncrementEntryValue (const plTempHashedString &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. | |
| plVariant | DecrementEntryValue (const plTempHashedString &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 plHashTable< plHashedString, Entry > & | GetAllEntries () const |
| Grants read access to the entire map of entries. | |
| const plEvent< EntryEvent > & | OnEntryEvent () const |
| Allows you to register to the OnEntryEvent. This is broadcast whenever an entry is modified that has the flag plBlackboardEntryFlags::OnChangeEvent. | |
| plUInt32 | GetBlackboardChangeCounter () const |
| This counter is increased every time an entry is added or removed (but not when it is modified). | |
| plUInt32 | GetBlackboardEntryChangeCounter () const |
| This counter is increased every time any entry's value is modified. | |
| plResult | Serialize (plStreamWriter &inout_stream) const |
| Stores all entries that have the 'Save' flag in the stream. | |
| plResult | Deserialize (plStreamReader &inout_stream) |
| Restores entries from the stream. | |
 Public Member Functions inherited from plRefCounted | |
| virtual | ~plRefCounted ()=default |
| Adds a virtual destructor. | |
| Public Member Functions inherited from plRefCountingImpl | |
| plRefCountingImpl ()=default | |
| Constructor. | |
| plRefCountingImpl (const plRefCountingImpl &rhs) | |
| void | operator= (const plRefCountingImpl &rhs) |
| plInt32 | AddRef () const |
| Increments the reference counter. Returns the new reference count. | |
| plInt32 | 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. | |
| plInt32 | GetRefCount () const |
| Returns the current reference count. | |
Static Public Member Functions | |
| static plSharedPtr< plBlackboard > | Create (plAllocator *pAllocator=plFoundation::GetDefaultAllocator()) |
| Factory method to create a new blackboard. | |
| static plSharedPtr< plBlackboard > | GetOrCreateGlobal (const plHashedString &sBlackboardName, plAllocator *pAllocator=plFoundation::GetDefaultAllocator()) |
| Factory method to get access to a globally registered blackboard. | |
| static plSharedPtr< plBlackboard > | FindGlobal (const plTempHashedString &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 plCore.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
| plResult plBlackboard::Deserialize | ( | plStreamReader & | 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 plBlackboard::SetEntryValue | ( | const plHashedString & | sName, |
| const plVariant & | value ) |
Overload of SetEntryValue() that takes an plHashedString rather than an plStringView.
Using this function is more efficient, if you access the blackboard often, but you must ensure to only create the plHashedString once and cache it for reuse. Assigning a value to an plHashedString is an expensive operation, so if you do not cache the string, prefer to use the other overload.
| void plBlackboard::SetEntryValue | ( | plStringView | sName, |
| const plVariant & | 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 plHashedString and use the other overload of this function. DO NOT RECREATE the plHashedString every time, though.
| void plBlackboard::SetName | ( | plStringView | sName | ) |
Changes the name of the blackboard.
1.11.0