Blackboard examples

This page describes concrete examples of AI Entity organizational structures that can be produced using private and shared blackboards in complex decision making scenarios.

Hierarchical structure

Imagine the following scenario: in a shooter game, a military force is storming the player’s position. The enemy is highly organized and the whole operation is coordinated by a commander, broadcasting his orders through a radio to multiple squad commanders, each of them having a group of soldiers under his command.

The following diagram illustrates how this kind of structure can be achieved in Grail. For simplicity’s sake, only one Squad is represented on the diagram.

Hierarchical Entity Structure
Figure 1. Hierarchical Entity Structure


This entity’s only task is to provide high level orders to squad commanders (orders like "take over this area", "defend your positions" etc.). These orders are then written to private blackboards of each of them.

This means that Behaviors on this level of abstraction don’t perform any actions in the game world (unless you want to play some animations or sounds), but are mainly preocuppied with providing the right clues to lower level AIs.

As you can see, there’s an external system called "Strategic Data Provider" that supplies the Commander with needed strategic data. The implementation of this system is not important to the Commander, as long as the data is valid.

Squad Commander

This level is constructed similarly to the Commander entity, but is concerned with lower-level decisions like choosing targets for individual units, deciding whether to rush or to be more defensive etc.

The product of this entity’s behaviors are order data written to individual units' blackboards.

If you decide that Squad Commanders shouldn’t be abstract entities, but physical units on the battlefield, there’s nothing stopping you from extending them with standard or slightly modified Unit AI. The low level unit actions and high level decision making will run in parallel.


A single soldier consists of two AI Entities. One is concerned with choosing the correct actions, the other one - with communication and sharing observations with other Units.

Unit Action AI performs low level behaviors like movement, shooting and seeking cover, taking into account the orders received from its Squad Commander.

Unit Communication AI reads from "Perception Data" blackboard and writes chosen observations to "Shared Observations" - a blackboard being shared with other units and the Squad Commander.

Modifying the system

The presented AI system is very easy to reorganize. If your designer wants squads to perform predefined, scripted actions on a certain map, just remove the Commander entity and write your custom data to their "Order Data" blackboards. As long as the data format is preserved, Squad Commanders will work uninterrupted - they are not concerned with the source of their orders.

Similar logic applies to Squad Commanders. If a Squad Commander gets killed by the player, its subordinate units will still perform actions to the best of their ability, communicate with each other, but will lose coordination abilities formerly provided by their leader.

Flat structure and ad hoc communication

Now let’s consider another type of scenario: a small village in a role-playing game. The village is inhabited by many NPCs who need various resources to perform their daily tasks like feeding themselves, keeping their houses warm and fending off any external threats (like wild animals and other beasts).

Flat Entity Structure
Figure 2. Flat Entity Structure

Because resources are scarce, the villagers have to manage them somehow. The village is small, so we may assume that every inhabitant knows who owns what. We model this fact by using a shared "Resource State" blackboard to which everyone has access. This way, each villager can take their fellows into account when planning various activities.

The fact that other people can be a part of another villagers plan necessitates the ability of negotiating and trading. We solve this problem by creating an ad-hoc shared blackboard whenever there’s a need for negotiation between two villagers. After the negotiation blackboard is initialized, both participants can modify its contents by adding and responding to trade offers.

Once the villagers finish their communication, they can remember important facts about the exchange by storing them on their private blackboard. The historical transaction data can be used in many different ways, e. g. to prevent the agent from making the same trade offer if it’s been rejected before.