Skip to main content

Blackboard

The blackboard is a per-agent key/value store that lets you track state across conversations and use it to drive branching.

It is the main mechanism for remembering what has happened and making dialogue react to it.

Scopes​

Blackboard values exist in one of two scopes:

  • Conversation -- cleared when the current conversation ends, useful for tracking state within a single dialogue
  • Agent -- persists across conversations and is included in save/load, useful for tracking long-term state like quest progress or relationship changes

Value types​

The blackboard supports four value types:

  • Bool -- true or false
  • Int -- whole numbers
  • Float -- decimal numbers
  • String -- text values

Each type has its own get and set methods. There is no generic accessor.

Conditions​

Conditions check blackboard values to gate connections and tree selection. The built-in conditions are:

  • ConditionBlackboardExists -- checks whether a key exists at all
  • ConditionBlackboardBoolEquals -- checks whether a bool key matches a specific value
  • ConditionBlackboardIntAtLeast -- checks whether an int key is at or above a threshold
  • ConditionBlackboardCompare -- general-purpose comparison of two values

Conditions are attached to connections in the chat tree editor. When a connection has conditions, it is only available if all conditions pass.

Effects​

Effects modify blackboard values when a connection is traversed, a passthrough node is crossed, or a node is entered. The built-in mutations are:

  • Set -- sets a key to a specific value
  • Increment -- adds to a numeric value
  • Remove -- deletes a key

Effects are the primary way conversations change state. A common pattern is setting a bool when the player first hears a piece of information, then using a condition on that bool to hide the option in future conversations.

Participant targeting​

The blackboard system uses DialogueParticipants to control whose blackboard is read or written:

  • Self -- the NPC's blackboard (the agent speaking)
  • Listener -- the player's blackboard (or the listening agent in a headless conversation)

This means you can track state on either side of the conversation. For example, setting a key on the player's blackboard records that the player knows something, regardless of which NPC told them.

Ownership​

Two components implement IBlackboardValueOwner:

  • PlayerAgentService -- owns the player's blackboard
  • AgentChatService -- owns each NPC's blackboard

Editor tooling​

The blackboard editor window is available at Window > BardTreeLtd > Agent Chat Blackboard. It shows the current state of blackboard values at runtime, which is useful for debugging condition and effect logic.

Practical advice​

Keep blackboard keys simple and consistent. A naming convention helps:

  • heard_rumour_innkeeper (bool) -- whether the player has heard the innkeeper's rumour
  • visit_count_alchemist (int) -- how many times the player has visited the alchemist
  • quest_status_missing_sword (string) -- the current state of a quest

Start with bool conditions for basic gating. Add int thresholds and comparisons once you need more nuanced branching.

Embedding blackboard values in text​

The Token System lets you embed blackboard values directly in dialogue text without branching. Use the {bb.key} syntax:

You've visited me {bb.visit_count_alchemist} times now.

This resolves at runtime from the speaker's blackboard. For conversation-scoped values, use {bb.conversation.key}.

Where to go next​

Last updated on