Task Framework – Arma 3

From Bohemia Interactive Community
Revision as of 01:26, 2 February 2024 by Lou Montana (talk | contribs) (Text replacement - "{{Feature|Warning|" to "{{Feature|warning|")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Framework Structure

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

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
BIS_fnc_taskSetType Sets task type
BIS_fnc_taskSetAlwaysVisible Makes task always visible
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)
BIS_fnc_taskType Returns type of the task
BIS_fnc_taskAlwaysVisible Makes task always visible
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 inside 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 Centralisation

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

Keep Task ID Short

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.

Task Modules

The task modules in Eden Editor also work in multiplayer, but compared to the scripted framework provided limited customization options.

Task Overhaul

Tasks Overhaul is name for project targeting UX and visual improvements to Arma 3 task framework. The 1st batch of updates was released to development branch on March 2016.

  • Update visuals of task markers in both 3D environment and in map.
  • Improve diary panels UX and visuals.
  • Improve map & task interaction - direct task assignment/unassignment from map.
  • Allow simultaneous display of multiple tasks in 3D environment.
  • Implement 'Shared Objectives' through new generic feature called Custom Data.

Feature Breakdown

Below you will find brief feature breakdown, that should present you all the core features of Tasks Overhaul.

Task Types

There is a new attribute - task type. The attribute describes what is in general the task about and replaces the task label that was displayed on the task marker. Task type is visualized through the icon and unlike the task label, it is fully implemented to the game UI (3D marker, map marker, task list, task index diary panel, task notification, debriefing screen, ...).

Task Type Definition

Tasks overhaul is going to ship with quite large library of task types, that should suffice the common needs community creators might have when designing their mission tasks. However we felt it would be great to allow community to extend or replace the default task type selection with their own task types in an easy and comfortable way. As result we prepared the system the way that it reads the definition from addon, campaign and/or even mission config and merges them together. In case there are duplicated definitions the more local definition takes precedence.


Task types definition is stored in CfgTaskTypes class. Types can also be declared in Description.ext.

class CfgTaskTypes
	class Ambush
		icon = "taskTypes\ambush_ca.paa";
	class Heal
		icon = "\A3\Ui_f\data\IGUI\Cfg\simpleTasks\letters\h_ca.paa";

The default task type icons are .paa textures with 32x32px size, 32bit color, white foreground and transparent background. There are no gradients or any other colors. Could be 2^x 2^y greater than 32px and 8bit color, prefered to follow restricted names "<name>_MCO.paa"

New Commands & Functions

For a detailed explaination and examples visit the command or function page.

Task type was fully integrated to BIS_fnc_taskCreate.

Defining task type when the task is created is suggested and most efficient way.

3D Markers

Task's 3D marker was completely redesigned. It now consists from 3 elements:

  1. background - texture with distinctive shape to visually define the element as task marker
  2. task type icon - texture of task type icon defining nature of the task; replaces the former task label
  3. distance indicator - standardized info about task distance

In standard situation there can be only an assigned task 3D marker shown on the screen. However there are now new commands and functions that allow to bend this behavior by flagging a task to always show - do not fade out.

New Commands

There are 2 new commands that interact with task visibility flag.

New Functions

The alwaysVisible flag is also fully implemented to scripted framework. There are getter and setter functions that mimic the commands behavior.

Task Overview

Task overview is a new display that shows all tasks available to player in 3D environment. It is triggered by new action 'Tasks Overview'. Action can be found in 'Common' section and uses the keybind that was previously used by 'Diary' action.

  • on keydown - all task markers and navigation elements show up and a special widget with assigned task type and name pops-up in the top-left corner
  • on keyup - 3 secs timer starts to tick, when it is over the task markers, navigation elements and assigned task widget fade out

Map Markers and Tooltip Widgets

Map Marker

The former non-interactive markers were replaced by new interactive markers that shows the task type icon and have a tooltip widget.

Interaction patterns (marker)
  • on click on marker - opens-up the task diary panels and selects the task in the task index. Color of the selected task marker on the map gets inverted.
  • on click outside of the marker - closes the diary panels and deselects task marker if it was previously selected. Colors return to normal scheme.
  • on mouse over - marker scales up and tooltip widget get displayed

Tooltip Widget

The tooltip widget shows task name, its state and can also display custom data info. The widget can be used to quickly assign to or unassign from a task.

Interaction patterns (tooltip)
  • on mouse over - task state text (bottom text) changes to action which will trigger on click; it is either assign or unassign
  • on mouse leave - tooltip hides
  • on click - assigns or unassigns task; bottom text shows the action that will trigger on click

Task Index and Description Panels

Task Index Panel

There were 2 major improvements done to the task index panel functionality wise:

  1. inactive (succeeded, failed or cancelled) tasks are automatically drawn in 'disabled' color and are moved down to the bottom of the task list
  2. parent/child task folding visualization and functionality was fixed
Interaction patterns
  • on click (on a list entry) - selects the task in the list and opens up the task description panel. In addition to the former state it also highlights the task marker on the map
  • on double-click (on a list entry) - centers the map on the task marker (if present)

Task Description Panel

There are now 2 new buttons under task title - toggle button 'Assign'/'Unassign' and 'Locate' button (with distance indicator).

Interaction patterns
  • on 'Assign' button click - assigns the task to player; mimicing functionality of previous 'Assign task as current'
  • on 'Unassign' button click - unassigns player from the task; was not possible before
  • on 'Locate' button click - centers the map on the task marker (if present)
Locate button remarks
  • Locate button currently uses "Find" string. It is subject to change.
  • If task doesn't have an objective linked the Locate buttons is disabled.
  • Number in parentheses shows the actual distance from player to the task objective.
  • If showing distances is blocked through difficulty settings, button is visible, but the distance indicator is hidden.

Diary Screen

Visual and functionality of task index and description panel is almost identical to map diary panels, with a single exception - there is no 'Locate' button in the task description panel.

There were 2 major changes done to the Diary display:

  1. In addition to the former functionality it also shows 3D markers of all tasks available to player; similarly to the 'Task Overview' action.
  2. The 'Diary' action was remapped to 2x[J] as its former keybind was taken by the 'Task Overview' action.


Changes and fixes done to the debriefing screen:

  • Task type icons were added to each task.
  • Task list placement was fixed, list made wider so it properly fits the area dedicated to the task list.
  • Uncompleted tasks are now in 'disabled' color. It usually should not happen as it is a good practice to complete every task at the end of the mission - either cancel, fail or succeed it.

Custom Data and 'Shared Objectives'

Custom data is a brand new feature that was prototyped on the scripted 'Shared Objectives' system. Custom Data allows for displaying extra information in task index and description panel as well as map marker tooltip.

New Commands

Custom data are completely local. There are 2 new commands that interact with custom data.

Shared Objectives

Task Overhaul is going to ship with one system build on Custom Data - Shared Objectives. The system monitors people assigned to particular tasks and displays locally the assigned player count per task.

Shared objective can be added to mission from EDEN editor by:

  • Opening Attributes >> Multiplayer >> Tasks >> Shared Objectives panel
  • Selecting either: 'Enable' or 'Enable with Task Propagation'

If 'Enable with Task Propagation' is selected, system automatically re-assigns tasks to every subordinate according to the group leader whenever the leader changes his assigned task.

Task Icons

Default Task Types
Icon Task Type
bis tasktype attack.png attack
bis tasktype danger.png danger
bis tasktype default.png default
bis tasktype defend.png defend
bis tasktype destroy.png destroy
bis tasktype download.png download
bis tasktype exit.png exit
bis tasktype getin.png getin
bis tasktype getout.png getout
bis tasktype heal.png heal
Icon Task Type
bis tasktype interact.png interact
bis tasktype kill.png kill
bis tasktype land.png land
bis tasktype listen.png listen
bis tasktype meet.png meet
bis tasktype move.png move
bis tasktype move1.png move1
bis tasktype move2.png move2
bis tasktype move3.png move3
bis tasktype move4.png move4
Icon Task Type
bis tasktype move5.png move5
bis tasktype navigate.png navigate
bis tasktype rearm.png rearm
bis tasktype refuel.png refuel
bis tasktype repair.png repair
bis tasktype run.png run
bis tasktype scout.png scout
bis tasktype search.png search
bis tasktype takeoff.png takeoff
bis tasktype talk.png talk
Icon Task Type
bis tasktype talk1.png talk1
bis tasktype talk2.png talk2
bis tasktype talk3.png talk3
bis tasktype talk4.png talk4
bis tasktype talk5.png talk5
bis tasktype target.png target
bis tasktype upload.png upload
bis tasktype use.png use
bis tasktype wait.png wait
bis tasktype walk.png walk

Default Task Types
Icon Task Type
bis tasktype armor.png armor
bis tasktype backpack.png backpack
bis tasktype boat.png boat
bis tasktype box.png box
bis tasktype car.png car
Icon Task Type
bis tasktype container.png container
bis tasktype documents.png documents
bis tasktype heli.png heli
bis tasktype intel.png intel
bis tasktype map.png map
Icon Task Type
bis tasktype mine.png mine
bis tasktype plane.png plane
bis tasktype radio.png radio
bis tasktype rifle.png rifle
bis tasktype whiteboard.png whiteboard

Default Task Types

There is also full set of capital letters available. Task types are named simply "a", "b", ... "z".

Icon Task Type
bis tasktype a.png a
bis tasktype z.png z