Utility Creation Tools

In this tutorial, we explain how to use the Utility Editor module of our creation tools. This editor contains a few similar elements to Entity Creation Tools and some concepts may be found in both tutorials.

You can use Utility Editor in two ways:

  1. To configure the Utility AI in your game. You can essentially create the whole system, but certain logic must be provided in code:

    • the code behind Considerations

    • the code behind Behaviors

  2. To quickly prototype a particular Utility AI without the actual game.

    • you can setup the system and play with it in the editor. This can help you iteratively design the ultimate configuration that works for the game.

Utility Editor uses Considerations and Behaviors as references to things that exist in the game. The editor does not use or require their code (logic). Those elements can be referenced by the name identifier in the editor. However, in the actual game you need to provide the code. This is highly specific logic so it cannot come with predefined implementation. This tutorial will go back to this issue in Section Using the Configuration in your Game.

Getting started

1 dashboard new project
Figure 1. Creating a new configuration

To create a new configuration file, click the Create new project button or open an existing project by clicking the Open project button.

In this manual page, we will show you how to configure the system from scratch. You can save your project at anytime and open it to continue working from where you saved.


utility creation
Figure 2. Utility Reasoner Editor window

(1) File tab - you can see the opened file. You can also close it here.

(2) Editor tabs - when creating the Utility system, you will be working with all of them, but the least of the time with the Entity Editor tab. To create Entities see Entity Creation Tools.

(3) Opened Reasoner - here you select the current Entity Reasoner to work with.

(4) Considerations list - all considerations defined in the system and attached to the currently opened Entity Reasoner are listed here.

(5) Evaluators list - here behaviors will be shown with evaluators that compute their utility. You select those evaluators to see their details in panel (6).

(6) Evaluator’s detailed view - this is the place where an evaluator can be configured. You set up input considerations, modify curves and select the final evaluation method.

(7) Console - a small output log window.

(8) Console buttons - you can clear the output log here and also set the window to auto-scroll ("Show latest" checkbox).

(9) Save - click here to save the configuration to the same file it was created/opened from or click "Save As" to write it to a new file.

Create (or select) Utility Reasoner

To create a new Utility reasoner, go to the Globals tab.

3 entity editor button
Figure 3. Click Globals here

In the Globals tab, click the plus (+) sign under Utility reasoners panel:

utility creation step1
Figure 4. Creating a reasoner

This will create a new reasoner with automatically generated name. You can edit the name to customize it to your game and it is a good idea to do it.

If you opened an existing configuration file, there is a chance that there are some reasoners already defined. You will see them in the combo box marked by (3) in Figure 2.

Create behaviors

Let’s create some Behaviors to work with. The Utility reasoner will be computing utility values for these behaviors, after all. To create behaviors, click the following plus sign under the Behaviors tab.

utility creation step2
Figure 5. Creating behaviors

Click the newly created behavior’s name to edit it. If you load the configuration file in the game, the names will be matched with behavior prefabs defined in code, so make sure the strings are identical.

If you opened an existing configuration file, there is a chance that there are some behaviors already defined. You will see an already populated list then.

Create considerations

Now let’s create some Considerations. These are measurable factors that define the context for the decisions in Utility System. Again, click the respective button:

utility creation step3
Figure 6. Creating considerations
If you opened an existing configuration file, there is a chance that there are some considerations already defined. You will see an already populated list then.

You can change the names of considerations as well as ranges of their allowed values. Setting the proper interval is useful for prototyping. See section Testing the System.

utility creation step4
Figure 7. Editing considerations
If you right click the behavior, consideration or reasoner in the Globals tab, you will be asked if you want to delete it.

Add Behaviors and Considerations to Utility Reasoner

We want the reasoner to have access to created behaviors and considerations. Just drag&drop them from the lists on the left-hand side to the reasoner. It will show how many considerations and behaviors are used by it. They do not need to be used right away - let say they become available to the reasoner.

utility creation step5
Figure 8. Using behaviors and considerations
If you opened an existing configuration file, you will see which behaviors and considerations are used by a particular reasoner.

Configure Evaluators

Switch back to the Utility Reasoners Editor tab:

3 entity editor button
Figure 9. Click Utility Reasoner Editor here

It is time to configure the evaluator. Select the checkbox next to a behavior to see how it is currently evaluated by the Utility Reasoner. This will open its setup in the panel to the right-hand side. When you select multiple behaviors, you will see their evaluations organized in a row-layout.

If you click the arrows (outlined by white and yellow circles in Figure below) you can expand or collapse the view of the evaluation of the respective behavior.
utility creation step6
Figure 10. Select behaviors to view their evaluation

Let’s add the created considerations so they are used in evaluation of Behavior1. Click the (+) sign:

utility creation step7
Figure 11. Add considerations

The effect shoud look as follows:

utility creation step8
Figure 12. Added considerations

If you want to delete a consideration added to an evaluator, click the remove sign in the top-right corner of its node.

You can click the evaluation node to change it type to a different formula. In the example above, it is specifically Evaluation Add. Currently, Grail supports the following methods of combining scores from multiple curves: Max, Min, Average, Multiply, Add.

Configure Curves

The fun part is to configure utility curves! You can right-click the curve symbol to change its type, but to enter the fully-fledged curve editor click the cogwheel in the top-right corner. This will enable you to customize the response curve, which transforms input from a consideration and plugs it in the evaluation.

utility creation step9
Figure 13. Click here to edit curves
utility creation step10
Figure 14. Utility curve editor

(1) Curve type selector - here you can select the base type for your curve. It’s the first thing you should do.

Currently, Grail supports the following types of curves: Linear, Constant, Step curve, Power curve, Exponential, Sigmoid, Linear interpolated curve, and Bezier curve.

(2) Curve parameters - this is a context-based panel that is specific to the chosen curve’s type. You can enter its parametrization here. For example: the Step curve allows you set where the step is (Threshold parameter) and what values the curve takes before and after this step.

(3) Curve view - the curve is plotted here, so you can analyze what values it takes for a given X. Some curves, i.e. Linear interpolated and Bezier, can be edited here. For example, when working with interpolated curves, you can drag&drop points such as the one next to the (3) mark in Figure 14. If you drag a point past another one (in the X axis), then you will be dragging that point instead.

(4) Scaling ver1 - you can see the scale for the plot. This is just for viewing convenience. By default the scaling is equal in both X and Y directions. If you want to change it, uncheck the Y same as X box. This will make the scaling slider appear for Y axis too.

(5) X scaling slider - you can use this slide to scale the view along the X axis.

(6) Scaling ver2 - you can also enter a multiplier for the scale in X and Y axes, respectively. This is just for viewing convenience. For example, if you change the scale X from 1 to 10 you will zoom out the plot 10 times.

(7) Save or discard - when you are done with editing the curve you should apply changes here.

Don’t forget to save your curve.

The image below shows a different type of curve - linear.

Notice how the parameters panel changed. For a linear curve you select gradient (slope) and intercept (crossing with the Y axis). In addition, you can optionally introduce fixed lower and upper bounds.

utility creation step11
Figure 15. Utility curve editor

Testing the System

You can quickly prototype the Utility system you configure.

  • Consideration sliders - in the panel to the left, there is a slider for each consideration that enables to set its value in the allowed interval. It is worth remembering that you can configure the min and max limit in the Globals tab, where you create configurations. This way you can emulate the game state in a simplified fashion. You can test whether the system meets your expectations.

  • Flow of values - notice how the values highlighted in the picture below change as your tinker with the sliders.

  • The winning behavior - the best behavior, i.e. that will be chosen in the current state, is distinguished by a lighter color. Observe whether it changes as you move the sliders or change components of the Utilty system.

Testing Utility System is a similar process to debugging. Here is the manual page for Utility Debugger.

utility creation step12
Figure 16. Rapid prototyping

Utility Reasoner assignment

This topic is covered in tutorial: Entity Creation Tools. You can drag the reasoner onto an entity in the Entity Editor tab.

Using the Configuration in your Game

In order to use the system created in this editor, save it to the configuration file and load it in your game. The save button is in the top-right corner, depicted by (9) in Figure 2. Please go through the following tutorial: Configuration Loading.