execTool
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
A package of functions that supports the use of a single Lua function to describe the control flow of a scripted task.
Typically, when a Lua task consists of a flow of actions, each of which is implemented as a subtask, the Lua script makes use of state variables (either ad-hoc, or using the fsm module) to keep track of what subtask is running. In the tick function, a subtask is started, the state is changed, and then in subsequent ticks the subtask state is monitored to see when it completes.
This execTool module allows a script to be written as if the script "calls" a subtask and then waits for it to return. This greatly simplifies the script logic, as a flow of tasks can be written simply as a sequence (or any control flow with conditions, loops, etc.) of subtask calls, without using any explicit subtask status calls or state variables.
To use this tool, the task logic is described in a function we call a scriptFunction. This function is written as if it will execute up to a subtask invocation, and then wait until that subtask is completed before continuing. For example, the following script function makes the entity move to waypoint 1, then to waypoint 2 and back twice:
function patrolTwice()
local i = 2;
execTool.subtask("move-to", {control_point = taskParameters.Point1})
while i > 0 do
execTool.subtask("move-to", {control_point = taskParameters.Point2})
execTool.subtask("move-to", {control_point = taskParameters.Point1})
i = i-1
end
end
The execTool.subtask calls actually use the Lua coroutine capability, and yield execution so that the rest of the VR Forces simulation can continue and execute the subtask. The coroutine resume call is used to resume the scriptFunction after the execTool.subtask call.
NOTE: Since this module uses coroutines, and since the VRF Lua interface does not save coroutine information is scenario saves, a script written with this module will not resume correctly if it is saved and reloaded in mid- execution. It will restart the task upon reload.
To use this module, the module must be included in the script, and the module's init and tick member functions must be used. For example: ...
execTool = require "execTool"
...
function patrolTwice()
... (as above)
end
execTool.init(patrolTwice)
...
function init()
vrf:setTickPeriod(0.5)
...
end
execTool.tick()
end
Function List
| init (scriptFunction) | Initializes a script to execute the statements in the Lua function scriptFunction. |
| subtask (taskName, params) | Called in a script function to start a subtask. |
| tick () | Called in the tick() function when the script logic is contained in a script function. |
Functions
- init (scriptFunction)
-
Initializes a script to execute the statements in the Lua function scriptFunction. ExecTool.init should be called in the global part of the Lua script, after the script function has been defined.
Parameters:
-
scriptFunction: A function that contains the control flow logic of the scripted task; defined in the global part of the script.
Return value:
- Nothing
-
- subtask (taskName, params)
-
Called in a script function to start a subtask.
Parameters:
-
taskName: The name (string) of the subtask to start. -
params: The table containing parameters for the task.
Return value:
- Nothing.
-
- tick ()
-
Called in the tick() function when the script logic is contained in a script function. If the script function has completed, then the scripted task will end here (vrf:endTask is called). The task is also ended if there is any error in resuming the script function.
Return value:
- Nothing