{"name":"Arma 3: Task Framework Tutorial","title":"Arma 3: Task Framework Tutorial","type":"topic","url":"https://community.bistudio.com/wiki/Arma_3:_Task_Framework_Tutorial","revid":347341,"updated":"2023-09-11T08:03:31Z","aliases":["Arma 3 Task Framework Tutorial"],"markdown":"### Basics\n\nTasks are a group's objectives. Arma 3 introduced the **Arma 3: Task Framework** to work with tasks with ease.\nThe **Task Framework** functions have a **global** effect.\n\n> [!NOTE]\n> For **Arma 2**'s Task Tutorial, see Arma 2: Task Tutorial.\n\n### How to Use a Task\n\n#### Create a Task\n\n```sqf\nprivate _title = \"Get the documents\";\nprivate _description = \"Enter the house to find the documents. Hurry, as the enemy is on its way.\";\nprivate _waypoint = \"House\";\n\nprivate _myTask = [groupOfPlayers, \"taskID\", [_description, _title, _waypoint], objDocuments, true] call BIS_fnc_taskCreate;\n```\n\n> [!NOTE]\n> The **\"taskID\"** argument is the task's ID used for later references. This string gets defined here on creation and must be unique for each task. It should be kept short for network economy.\n\n#### Assign a Task\n\n```sqf\n\"taskID\" call BIS_fnc_taskSetCurrent;\n```\n\n> [!NOTE]\n> This step is optional here as we used true as the fifth argument of the BIS_fnc_taskCreate call, making it the current task.\n\n#### Set a Task's Type\n\n```sqf\n[\"taskID\", \"attack\"] call BIS_fnc_taskSetType;\n```\n\n> [!NOTE]\n> This could have been set in the task creation call as the eighth argument. See BIS_fnc_taskCreate's *type* parameter.\n\n#### Set a Task's Visibility\n\n```sqf\n[\"taskID\", true] call BIS_fnc_taskSetAlwaysVisible;\n```\n\n#### Update a Task's Description\n\n```sqf\n// hardcoded language\n_description = _description + \"<br/><br/>UPDATE: an officer stole the documents; we got the GPS tracking, follow your HUD.\";\n[\"taskID\", [_description, _title, _waypoint]] call BIS_fnc_taskSetDescription;\n\n// new description\n[\"taskID\", [\"STR_TaskDescription2\", _title, _waypoint]] call BIS_fnc_taskSetDescription;\n```\n\n#### Update a Task's Waypoint Position\n\n```sqf\n[\"taskID\", [theOfficer, true]] call BIS_fnc_taskSetDestination;\n```\n\n#### Update a Task's Status\n\n```sqf\n[\"taskID\", \"SUCCEEDED\"] call BIS_fnc_taskSetState;\n```\n\n#### Delete a Task\n\n```sqf\n[\"taskID\"] call BIS_fnc_deleteTask;\n```\n\n### How to Read a Task's Information\n\n#### Find if a Task Exists\n\n```sqf\n[\"taskID\"] call BIS_fnc_taskExists;\n```\n\n#### Find if a Task is Completed\n\n```sqf\n\"taskID\" call BIS_fnc_taskCompleted;\n```\n\n> [!NOTE]\n> \"Completed\" means that the task is either \"SUCCEEDED\", \"FAILED\" or \"CANCELED\".\n\n##### Multiple Tasks Check\n\n```sqf\n[\"taskID_0\", \"taskID_1\", \"taskID_2\"] findIf { !(_x call BIS_fnc_taskCompleted) } == -1;\n```\n\n#### Get a Task's Status\n\n```sqf\n\"taskID\" call BIS_fnc_taskState;\n```\n\n#### Get a Task's Type\n\n```sqf\n\"taskID\" call BIS_fnc_taskType;\n```\n\n#### Get a Task's Visibility\n\n```sqf\n\"taskID\" call BIS_fnc_taskAlwaysVisible;\n```\n\n#### Get a Task's Description\n\n```sqf\n\"taskID\" call BIS_fnc_taskDescription;\n```\n\n#### Get a Task's Destination\n\n```sqf\n\"taskID\" call BIS_fnc_taskDestination;\n```\n\n#### Get a Unit's Tasks\n\n```sqf\nprivate _taskIDs = player call BIS_fnc_tasksUnit;\n```\n\n### Advanced\n\n> [!NOTE]\n> All these details can be found in the Description.ext's Tasks chapter.\n\n#### Define a Task in Mission Config\n\nYou can define a task in Description.ext's CfgTaskDescriptions:\n\n```cpp\nclass CfgTaskDescriptions\n{\n    class myTask1\n    {\n        title        = \"my task title\";\n        description    = \"my task description\";\n        marker        = \"my task destination marker\";\n    };\n    class myTask2\n    {\n        title        = \"STR_myTask2Title\";            // note the lack of $ sign here!\n        description    = \"STR_myTask2Description\";        // without $, it translates for each client\n        marker        = \"STR_myTask2Marker\";            // with $ everyone sees the server's language\n    };\n};\n```\n\n#### Define a new Task Type\n\n```cpp\nclass CfgTaskTypes\n{\n    class Attack\n    {\n        icon    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types\\Attack_ca.paa\";\n        icon3D    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types3D\\Attack_ca.paa\";\n    };\n    class Defend\n    {\n        icon    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types\\Defend_ca.paa\";\n        icon3D    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types3D\\Defend_ca.paa\";\n    };\n};\n```\n\n#### Define Task Display Behaviour\n\n```cpp\nclass CfgTaskEnhancements\n{\n    enable       = 1; // 0: disable new task features (default), 1: enable new task features & add new task markers and task widgets into the map\n    3d           = 1; // 0: do not use new 3D markers (default), 1: replace task waypoints with new 3D markers\n    3dDrawDist   = 0; // 3d marker draw distance (default: 2000)\n    share        = 1; // 0: do not count assigned players (default), 1: count how many players have the task assigned\n    propagate    = 1; // 0: do not propagate (default), 1: propagate shared tasks to subordinates\n};\n```\n\n### See Also\n\n- Arma 3: Task Framework\n- Tasks Functions\n- Briefing Commands","sections":[{"heading":"Basics","level":3,"markdown":"Tasks are a group's objectives. Arma 3 introduced the **Arma 3: Task Framework** to work with tasks with ease.\nThe **Task Framework** functions have a **global** effect.\n\n> [!NOTE]\n> For **Arma 2**'s Task Tutorial, see Arma 2: Task Tutorial."},{"heading":"How to Use a Task","level":3,"markdown":""},{"heading":"Create a Task","level":4,"markdown":"```sqf\nprivate _title = \"Get the documents\";\nprivate _description = \"Enter the house to find the documents. Hurry, as the enemy is on its way.\";\nprivate _waypoint = \"House\";\n\nprivate _myTask = [groupOfPlayers, \"taskID\", [_description, _title, _waypoint], objDocuments, true] call BIS_fnc_taskCreate;\n```\n\n> [!NOTE]\n> The **\"taskID\"** argument is the task's ID used for later references. This string gets defined here on creation and must be unique for each task. It should be kept short for network economy."},{"heading":"Assign a Task","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskSetCurrent;\n```\n\n> [!NOTE]\n> This step is optional here as we used true as the fifth argument of the BIS_fnc_taskCreate call, making it the current task."},{"heading":"Set a Task's Type","level":4,"markdown":"```sqf\n[\"taskID\", \"attack\"] call BIS_fnc_taskSetType;\n```\n\n> [!NOTE]\n> This could have been set in the task creation call as the eighth argument. See BIS_fnc_taskCreate's *type* parameter."},{"heading":"Set a Task's Visibility","level":4,"markdown":"```sqf\n[\"taskID\", true] call BIS_fnc_taskSetAlwaysVisible;\n```"},{"heading":"Update a Task's Description","level":4,"markdown":"```sqf\n// hardcoded language\n_description = _description + \"<br/><br/>UPDATE: an officer stole the documents; we got the GPS tracking, follow your HUD.\";\n[\"taskID\", [_description, _title, _waypoint]] call BIS_fnc_taskSetDescription;\n\n// new description\n[\"taskID\", [\"STR_TaskDescription2\", _title, _waypoint]] call BIS_fnc_taskSetDescription;\n```"},{"heading":"Update a Task's Waypoint Position","level":4,"markdown":"```sqf\n[\"taskID\", [theOfficer, true]] call BIS_fnc_taskSetDestination;\n```"},{"heading":"Update a Task's Status","level":4,"markdown":"```sqf\n[\"taskID\", \"SUCCEEDED\"] call BIS_fnc_taskSetState;\n```"},{"heading":"Delete a Task","level":4,"markdown":"```sqf\n[\"taskID\"] call BIS_fnc_deleteTask;\n```"},{"heading":"How to Read a Task's Information","level":3,"markdown":""},{"heading":"Find if a Task Exists","level":4,"markdown":"```sqf\n[\"taskID\"] call BIS_fnc_taskExists;\n```"},{"heading":"Find if a Task is Completed","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskCompleted;\n```\n\n> [!NOTE]\n> \"Completed\" means that the task is either \"SUCCEEDED\", \"FAILED\" or \"CANCELED\"."},{"heading":"Multiple Tasks Check","level":5,"markdown":"```sqf\n[\"taskID_0\", \"taskID_1\", \"taskID_2\"] findIf { !(_x call BIS_fnc_taskCompleted) } == -1;\n```"},{"heading":"Get a Task's Status","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskState;\n```"},{"heading":"Get a Task's Type","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskType;\n```"},{"heading":"Get a Task's Visibility","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskAlwaysVisible;\n```"},{"heading":"Get a Task's Description","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskDescription;\n```"},{"heading":"Get a Task's Destination","level":4,"markdown":"```sqf\n\"taskID\" call BIS_fnc_taskDestination;\n```"},{"heading":"Get a Unit's Tasks","level":4,"markdown":"```sqf\nprivate _taskIDs = player call BIS_fnc_tasksUnit;\n```"},{"heading":"Advanced","level":3,"markdown":"> [!NOTE]\n> All these details can be found in the Description.ext's Tasks chapter."},{"heading":"Define a Task in Mission Config","level":4,"markdown":"You can define a task in Description.ext's CfgTaskDescriptions:\n\n```cpp\nclass CfgTaskDescriptions\n{\n    class myTask1\n    {\n        title        = \"my task title\";\n        description    = \"my task description\";\n        marker        = \"my task destination marker\";\n    };\n    class myTask2\n    {\n        title        = \"STR_myTask2Title\";            // note the lack of $ sign here!\n        description    = \"STR_myTask2Description\";        // without $, it translates for each client\n        marker        = \"STR_myTask2Marker\";            // with $ everyone sees the server's language\n    };\n};\n```"},{"heading":"Define a new Task Type","level":4,"markdown":"```cpp\nclass CfgTaskTypes\n{\n    class Attack\n    {\n        icon    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types\\Attack_ca.paa\";\n        icon3D    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types3D\\Attack_ca.paa\";\n    };\n    class Defend\n    {\n        icon    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types\\Defend_ca.paa\";\n        icon3D    = \"\\A3\\UI_F_MP_Mark\\Data\\Tasks\\Types3D\\Defend_ca.paa\";\n    };\n};\n```"},{"heading":"Define Task Display Behaviour","level":4,"markdown":"```cpp\nclass CfgTaskEnhancements\n{\n    enable       = 1; // 0: disable new task features (default), 1: enable new task features & add new task markers and task widgets into the map\n    3d           = 1; // 0: do not use new 3D markers (default), 1: replace task waypoints with new 3D markers\n    3dDrawDist   = 0; // 3d marker draw distance (default: 2000)\n    share        = 1; // 0: do not count assigned players (default), 1: count how many players have the task assigned\n    propagate    = 1; // 0: do not propagate (default), 1: propagate shared tasks to subordinates\n};\n```"},{"heading":"See Also","level":3,"markdown":"- Arma 3: Task Framework\n- Tasks Functions\n- Briefing Commands"}],"categories":["Arma Scripting Tutorials"],"groups":["Scripting"]}