Task Framework – Arma 3
Template:SideTOC -wrong parameter ("A3") defined!-[[:Category:Introduced with A3 version 1.00|1.00]]
Task framework is a complex scripted system for handling tasks in both singleplayer and multiplayer environment. It’s main goal is to provide solid interface for creating, updating and managing tasks in both environments and fully automatize synchronization in MP environment.
Framework Structure
The whole task framework consists of multiple functions that can be split into several categories according to their functionality and purpose:
| Function | Description |
|---|---|
| Setter Functions | |
| Functions for creating and updating tasks their data | |
| BIS_fnc_taskCreate | Creates task |
| BIS_fnc_taskSetCurrent | Assigns task |
| BIS_fnc_taskSetDescription | Sets task title, description and marker texts |
| BIS_fnc_taskSetDestination | Sets target destination |
| BIS_fnc_taskSetState | Sets task state (“FAILED”, “SUCCEEDED”, ...) |
| BIS_fnc_deleteTask | Removes task from given target, if no one has the task, task is removed from the framework |
| Getter Functions | |
| Functions for retrieving information about tasks | |
| BIS_fnc_taskCompleted | Returns true if task is "SUCCEEDED", "FAILED" or "CANCELED" |
| BIS_fnc_taskCurrent | Returns id of currently assigned task |
| BIS_fnc_taskDescription | Returns task title, description and marker texts |
| BIS_fnc_taskDestination | Returns task’s destination |
| BIS_fnc_taskExists | Returns true if task exists (was created and not deleted) |
| BIS_fnc_taskState | Returns state of particular task |
| BIS_fnc_tasksUnit | Return all tasks that given unit has (in any state) |
| Support Functions | |
| Special getter functions that are used by the task framework | |
| BIS_fnc_taskVar | Returns variable under which task is stored in the game (based on task id) |
| BIS_fnc_taskChildren | Returns all child tasks for given task |
| BIS_fnc_taskParent | Returns parent task for given task |
| BIS_fnc_taskReal | Returns engine task associated with the task id |
| Core Functions | |
| BIS_fnc_setTask | Creates and updates task data and automatically calls BIS_fnc_setTaskLocal. Can be called directly, however using the setter functions is recommended. |
| BIS_fnc_setTaskLocal | Function that locally creates or updates task data. |
Handling Tasks in MP Environment
Being said, task framework can be used in both SP and MP environments. In SP environment everything is very easy as task data and execution are all handled on one place and there is no needs for synchronization. In MP environment things get complicated.
Task locality
Tasks are purely local. It means that if task is created using the script command createSimpleTask it is created only on the machine where it was called. If you create it on a local client, server would not know about the task existence at all. Similar issue if you want to give a task to whole group of players, you would need to create it separately on every machine. In case you need to update the task, let say change the target destination or the task state, you would need to do the change on every group member machine. Keeping those tasks fully synchronized while using only the engine based script commands could be very tedious in more complex MP scenarios.
And that’s why the task framework was created in the first place - to provide comfortable but still powerful tool for synchronized task creation and management in MP scenarios.
Data and processing centralization
It is strongly suggested that all task operations are initialized from same place, preferably a server. With this approach, all task operations are being handled on server - task creation and updates are initialized from server and thanks to the task framework the task data are automatically transferred to appropriate clients and the local execution is triggered there, so the tasks states are fully synchronized over the network.
Good Techniques
Keeping task ID short (MP)
Task ID is a string that differs tasks between each other and so task id is a required parameter for all setter functions and most of the getter functions. Task ID is also being used for creating global variables that hold different task parameters and are broadcasted on the network. Because of that, it is a good practice when defining task IDs in MP scenario to keep them as short as possible to reduce the network load.
It is usually good idea to keep task IDs descriptive enough, but their length should probably not exceed 15 chars. If you can live with tasks using some code names like “tsk1” or even “t1” it is great. If not try to keep the task id as short as possible. The shorter, the better.
The task ID length is of course important only in MP games. For SP games, feel free to name task as you wish.
Use getters
Even if most of the task data can be read directly from the task global variables, if you learn how they are named and structured, it is not a good technique. The reason is simple - in case we modify the task framework for any reason, the internal structure and data handling can easily change and your scripts cease to work.
If you use the getters we provide, you should not notice any difference. The input and output should always be the same, fully backward compatible and shielded from the internal functionality changes.
Use setters
Although all setters can be replaced by direct call of BIS_fnc_setTask, it is strongly suggested to use the setters. The performance impact is very low and by using setters, the code become more readable and prone to accidental data change - setters only affect data related to the setter nature/functionality.