Arma 3: Task Framework

-wrong parameter ("A3") defined!-[[:Category:Introduced with A3 version 1.48|1.48]]

TASK FRAMEWORK

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:

setter functions - functions for creating and updating tasks and task 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. 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 (link to: https://community.bistudio.com/wiki/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.