Exploring the example scene

A brief description

Grail’s Unity plugin comes bundled with an example scene showcasing a pair of Utility AI agents. Their behavior is fairly simple, but it’s a great introduction to Grail and its Utility AI concepts. The example scene file is Grail/Examples/Scenes/ExampleScene.unit. It contains two agents controlled by Grail’s Utility AI, whose task is to pick up collectibles that are randomly spawned around the level. Each agent has their individual preferences regarding collectibles - one agent takes into account only the distance between them and each collectible, the other one also looks at the value of each collectible, denoted by its size.

Agents on the example scene
Figure 1. Agents on the example scene


  1. AIConfiguration: this directory contains all the basic configuration structures needed to set up Utility AI agents. It also contains a configuration file, ExampleGrailConfig.gcf that can be opened using Grail’s dedicated config tool.

  2. Materials: contains materials for collectibles and characters (collectors).

  3. Prefabs: contains a prefabs defining a collector character and a collectible object.

  4. Scenes: contains the example scene.

  5. Scripts

    1. AI: contains all C# scripts defining AI behavior logic. It will be discussed in more detail below.

    2. Gameplay: contains scripts defining the gameplay mechanics - the logic for character movement, picking up and spawning collectibles.

AI Configuration

To better understand the configuration of the agents, first go through the Utility AI section of the documentation. This page will assume familiarity with basic concepts of the technique.


The only behavior that’s available to the agent is MoveToCollectible. However, thanks to Grail’s behavior instantiation feature, the agents differentiate between each collectible and evaluate them individually. That’s how we obtain the rich behavior that you can see in the example with only a single behavior.

To be used with Grail’s Utility AI, the behavior requires some additional instantiation logic. It’s located in the MoveToCollectibleBehaviorProvider.cs script. The script iterates over each collectible present on the level and tells the Utility system that it should be considered in the decision-making process. You can read more about Behavior Providers in the Scriptable Objects section of this manual.


There are two considerations used by our agents: distance and value. Each of those configurations has a ConsiderationProvider class associated with it. You can read more about Consideration Providers in the Scriptable Objects section of this manual.

Data providers

To communicate with the game world, Grail’s AIEntities utilize data providers that write necessary data to their blackboards. There are two such providers defined in the example:

  1. CollectibleSpawnerProvider that provides a reference to the CollectibleSpawner class, containing the list of all collectibles on the level.

  2. CollectorProvider, providing a reference to the Collector character controlled by a given AI entity.

Configuration Scriptable Objects

To translate the configuration file into something executable, Grail utilizes special Scriptable Objects, located in the AIConfiguration directory. The most important one is GrailConfigurationLoader, that reads and deserializes the configuration and then uses its defined reasoner factories to spawn "brains" for our agents.

GrailConfigurationLoader’s inspector
Figure 2. GrailConfigurationLoader’s inspector

In this example, there’s only one such factory - UtilityReasonerFactory, containing collections of behavior and consideration providers, mentioned above.

UtilityReasonerFactory’s inspector
Figure 3. UtilityReasonerFactory’s inspector

Character Prefab

Now it’s time for the most important part - the character’s configuration. If you open the prefab for the Collector character, you’ll notice that it contains three components on its AIEntity child object:

  1. AI Entity Component: this component binds a specific reasoner (brain) to the character. The reasoner is selected using a dropdown in the component’s inspector.

  2. Two data provider components mentioned in the previous section.

Collector prefab
Figure 4. Collector character AI configuration

AI configuration on the scene

On the scene, there are two Collector agents (feel free to add more!), each of them with a different reasoner. To schedule the characters' reasoning and behavior execution, there’s an AI Manager present on the scene. AI Entities controlling each character register to the AI Manager on awake.

AI Manager reference
Figure 5. AI Manager reference on a characters AIEntity Component

Exploring Utility AI configuration

Now that you’ve gone through the whole AI setup, it’s time to look at the configuration. You can edit the configuration file (ExampleGrailConfig.gcf) by hand, but using our dedicated tool is a much better way to do this. The tool can be downloaded from Grail Shop, after free registration. The manual for Grail Tool’s Utility AI configurator can be found here. We encourage you to open the configuration file and have some fun with the utility curves. After modifying the configuration, remember to click on the "Reload model list" button in GrailConfigurationLoader’s inspector, so that the changes are imported into the engine.

Behavior Debugging

If you’re curious about the inner life of our characters as they perform their collector duties, you can always use Grail’s behavior debugger to produce diagnostic data regarding the decision-making processes of each agent. To do so, use the debugger tab in Grail’s Plugin Window. The resulting .gdi files can be then inspected using Grail Tool’s built-in debugger’s, documented here.