behaviorEngine
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
This package implements a behavior engine aimed at supporting unit tasks.
This file should be included in a behavior script with
require "behaviorEngine"
It provides several functions and implements the standard callbacks init(), tick(), saveState(), and loadState(), so they are not needed in the behavior script.
Usage
A task script that uses the behavior engine will generally be organized as follows:
- Define global constants
- Define utility functions
- Define roles in a Role List.
- Define an Activity Block, with nested Actions and Activity Blocks, that describes the behavior.
- Call defineBehavior, passing the Role List and Activity Block as arguments.
Role List
Roles are defined in tables and combined in a list (table). Each role has elements as follows:
- name
- The name of the role. This will be matched with a role string in a parallel action in the behavior.
- types
- A list (table) of strings that define object types. Subordinate entity types must match one of these strings to be assigned this role.
- isCritical
- (Optional, default false.) A Boolean which, if true, means that the behavior fails if no subordinate can be matched to this role; and the behavior fails if a parallel action for this role fails.
- maxInstances
- (Optional, default 1.) The maximum number of subordinates that can execute this role.
- scoreFn
- (Optional, default score is 0.) A function that takes two arguments: a subordinate object and the index of the subordinate in the _subordinates table. Returns a score: < 0 if the subordinate should not be assigned to the role; 0 if it should be assigned only when no + scoring subordinate is available; and a value > 0 otherwise that indicates the desirability of the subordinate for the role.
Activity Block
An Activity Block is a container with either a sequence of Actions or a set of parallel actions defining roles which are executed in parallel by subordinates. An Activity Block is a table with the following elements. Note that all elements are optional, except that a block must have either sequentialActions or parallelActions:
- name
- A string that is useful mostly in debugging output.
- initFn
- A function that takes an Activity Block as an argument. No return value. Run after the block is created, but before any other function is called.
- startWhen
- A function that takes an Activity Block as an argument. Returns a Boolean. When it returns true, block execution can begin.
- doWhile
- A function that takes an Activity Block as an argument. Returns a Boolean. The actions are executed if this is true, and repeated while it remains true.
- endWhen
- A function that takes an Activity Block as an argument. Returns a Boolean. If this function is true, the block stops any running actions and ends.
- failWhen
- A function that takes an Activity Block as an argument. Returns a Boolean. If this function is true, the block stops any running actions and ends with an error status.
- Action list; one of the following:
-
- sequentialActions-- a list (table) of Actions.
- parallelActions-- a list (table) of parallel actions. Each of these is a table with the following elements:
- name (optional) -- a string
- role (required) -- a string; must match a defined role.
- activityBlock (required) -- an Activity Block definition.
Actions
Actions are either chunks of executable code, or definitions of nested Activity Blocks. They are executed as part of a sequential Activity Block. Actions are tables that contain the following elements:
- name
- A string. This name shows up in the html debugging output.
- doIf
- (Optional) A function that takes an Activity Block as an argument. Returns a Boolean. This function is called before any Actions in an Activity Block are executed, to determine if the Action will be executed or not.
- Activity; one of the following:
-
- command -- A function that takes an Activity Block as an argument. This function returns the task ID of a VRF task. It is used to start subtasks.
- computation -- A function that takes an Activity Block as an argument. Returns a string "done", "error", or "running". It is ticked (called every tick) until it returns "done" or "error".
- activityBlock -- an Activity Block definition.
Action Block Member Functions
Functions that take an Activity Block as an argument can call the following functions on it:
- name() returns a string.
- subordinate() returns the sim object running this parallel action.
- instanceN() returns an integer which is the index of the instance of this parallel action.
- role() returns a string which is the name of the role of this parallel action.
- setRoleStateVar(variable, value)-- Param variable is a string, the name of the variable. Sets a state variable in the state that is local to this parallel action. This variable will be saved in a scenario save.
- getRoleStateVar(variable)
State Variables
There is one global table for state variables. These global state variables are accessible to any Activity Block or Action in the behavior. They are saved in a scenario save. To set and access them, use the functions setStateVar() and getStateVar() (see below).
Within each parallel action, there are additional tables set up that are private to that parallel action. Functions in blocks in these parallel actions can set and access variables using the functions setRoleStateVar() and getRoleStateVar() (above).
Graphical Debugging Output
If the notification level of a unit is set to Debug, then the behavior engine will write out an html file that graphically describes the state of the behavior. This file is located in the bin64 directory and has the name behaviorStatus_entity name.html, where the entity name has spaces replaced with underscores. You can view this file in a browser at any time and see the status of the behavior. The page must be reloaded manually to see updates.
Function List
| beDefineCommand (args) | Deprecated. |
| defineCommand (args) | Define the behavior command. |
| getStateVar (variable) | A convenience function to get the value of a state variable. |
| init () | The init() callback. |
| loadState () | The loadState() callback. |
| saveState () | The saveState() callback. |
| setStateVar (variable, value) | Sets the entry "variable" in checkpointState. |
| tick () | The tick() callback. |
Table List
| _subordinates | A list of the subordinates of this entity. |
Functions
- beDefineCommand (args)
-
Deprecated. Calls defineCommand.
Parameters:
-
args:
-
- defineCommand (args)
-
Define the behavior command.
Parameters:
-
args: is a table with two elements, args.subordinateRoles and args.activityBlock. The first argument is a Role List, i.e. a table containing role definitions. The second argument is the description of the top level activity block. Note that using Lua's "{}" notation, this function can be called with key value pairs. Returns true if successful, false otherwise.
Usage:
defineCommand{subordinateRoles = myRoles, activityBlock = commandDefinition} -
- getStateVar (variable)
-
A convenience function to get the value of a state variable.
Parameters:
-
variable: A string, the name of the variable.
Return value:
- checkpointState[variable]
-
- init ()
- The init() callback. Do not include this in the task script.
- loadState ()
- The loadState() callback. Do not include this in the task script.
- saveState ()
- The saveState() callback. Do not include this in the task script.
- setStateVar (variable, value)
-
Sets the entry "variable" in checkpointState. The calling code could do this directly; however, using this function causes an update to the output used for the html Inspector.
Parameters:
-
variable: A string, the name of the variable. -
value: The value to set.
-
- tick ()
- The tick() callback. Do not include this in the task script.