Arma 3: Task Framework

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.

See also

• Arma 3 Tasks Overhaul

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. ⚠ This function is designed to be executed only from insight of the framework, do not execute it directly.

ⓘ

In normal circumstances the setter and getter functions are all is needed to create and manage tasks. Check the function headers in the function viewer from inside of the game for detailed information about function syntax and parameters.

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.