forge/docs/TASK_USAGE_GUIDE.md

Task Usage Guide

The task module stores transient mission task metadata for active server or mission lifecycle workflows. SQF still owns Arma-only runtime state such as objects and participants.

The server addon at arma/server/addons/task also owns task execution: creating BIS tasks, registering task entities, tracking participants, binding task ownership, applying player/org rewards, and clearing task state when a task completes.

Runtime dependencies:

• forge_server_extension
• forge_server_common
• forge_server_actor
• forge_server_bank
• forge_server_org
• forge_client_notifications

Data Model

Catalog entries are flexible JSON objects. The service normalizes these fields when a catalog entry is inserted or ownership changes:

• taskId
• taskID
• accepted
• requesterUid
• orgID

Ownership context:

{
  "requesterUid": "76561198000000000",
  "orgId": "default"
}

Commands

Command	Arguments	Returns
task:reset	none	true.
task:catalog:active	none	Active catalog entry array JSON.
task:catalog:get	task_id	Catalog entry JSON or null.
task:catalog:upsert	task_id, entry_json	Stored catalog entry JSON.
task:catalog:delete	task_id	true.
task:ownership:bind	task_id, ownership_json	Ownership mutation result JSON.
task:ownership:release	task_id	Ownership mutation result JSON.
task:ownership:accept	task_id, ownership_json	Ownership mutation result JSON.
task:ownership:reward_context	task_id	Reward context JSON.
task:status:set	task_id, status	true.
task:status:get	task_id	Status string JSON.
task:status:clear	task_id	true.
task:defuse:increment	task_id	New counter value JSON.
task:defuse:get	task_id	Counter value JSON.
task:clear	task_id	true.

Upsert a Catalog Entry

private _entry = createHashMapFromArray [
    ["title", "Destroy Cache"],
    ["description", "Destroy the enemy supply cache."],
    ["reward", 1500]
];

private _result = "forge_server" callExtension ["task:catalog:upsert", [
    "task-cache-1",
    toJSON _entry
]];

Mark a Task Active

"forge_server" callExtension ["task:status:set", [
    "task-cache-1",
    "active"
]];

private _active = "forge_server" callExtension ["task:catalog:active", []];

Completed statuses succeeded and failed are also stored as completed status fallbacks. Clearing status removes active and completed state.

Accept a Task

private _ownership = createHashMapFromArray [
    ["requesterUid", getPlayerUID player],
    ["orgId", "default"]
];

private _result = "forge_server" callExtension ["task:ownership:accept", [
    "task-cache-1",
    toJSON _ownership
]];

task:ownership:accept fails if the task is not active or another requester already accepted it.

Rewards

private _result = "forge_server" callExtension ["task:ownership:reward_context", [
    "task-cache-1"
]];

private _context = fromJSON (_result select 0);

The reward context contains requesterUid and orgId.

Server Task Flows

The task addon provides these server-owned task flows:

• attack
• defend
• defuse
• delivery
• destroy
• hostage
• hvt

Mission designers can create tasks in four ways:

• Eden modules for editor-authored tasks.
• forge_server_task_fnc_startTask for script-authored tasks.
• forge_server_task_fnc_handler for pre-registered entities with reputation gating and ownership binding.
• Direct task function calls for server-owned or mission-authored flows that intentionally fall back to the default org.

The dynamic mission manager can also generate attack tasks from config. That is system-generated content rather than a hand-authored task creation path.

Eden Modules

Eden task modules are the normal designer-facing path. Place the module, configure its attributes, and sync it to the relevant entities or grouping modules.

Available task modules:

• FORGE_Module_Attack: sync directly to target units or vehicles.
• FORGE_Module_Destroy: sync directly to objects, vehicles, or units.
• FORGE_Module_Defuse: sync to FORGE_Module_Explosives and optionally FORGE_Module_Protected.
• FORGE_Module_Delivery: sync to FORGE_Module_Cargo; the cargo module syncs to cargo objects.
• FORGE_Module_Hostage: sync to FORGE_Module_Hostages and FORGE_Module_Shooters.
• FORGE_Module_HVT: sync directly to HVT units.
• FORGE_Module_Defend: configure the defense marker and wave settings.

These modules delegate to forge_server_task_fnc_startTask.

Scripted Start Task

Use forge_server_task_fnc_startTask when creating tasks from modules, mission scripts, or generated mission-manager content. It registers task entities, creates the BIS task, stores the catalog entry, then dispatches through forge_server_task_fnc_handler.

[
    "attack",
    "compound_attack_01",
    getPosATL leader1,
    "Attack: East Compound",
    "Eliminate all hostile forces.",
    createHashMapFromArray [["targets", [unit1, unit2, unit3]]],
    createHashMapFromArray [
        ["limitFail", 0],
        ["limitSuccess", 3],
        ["funds", 50000],
        ["ratingFail", -10],
        ["ratingSuccess", 20],
        ["timeLimit", 900]
    ],
    0,
    getPlayerUID player,
    "script"
] call forge_server_task_fnc_startTask;

Handler Calls

Use forge_server_task_fnc_handler directly when the task entities are already registered and you want reputation gating plus ownership binding:

[
    "delivery",
    ["delivery_1", 1, 3, "delivery_zone", 250000, -75, 300, false, false, 900],
    250,
    getPlayerUID player
] call forge_server_task_fnc_handler;

Direct Task Calls

Direct task function calls still work for mission-authored or server-owned tasks, but they do not provide a requester UID. Ownership falls back to the default org.

Timer Semantics

Task time limits use 0 for no limit:

• attack timeLimit
• destroy timeLimit
• delivery timeLimit
• hostage timeLimit
• HVT timeLimit

Positive values are measured in seconds. Do not pass -1 as a no-limit value; the task runtime treats any non-zero task time limit as active.

Defuse IED timers are different. iedTimer must be greater than 0, because IEDs are expected to have an active countdown. The Eden defuse module defaults to 300 seconds.

Defuse Counter

"forge_server" callExtension ["task:defuse:increment", ["task-cache-1"]];
private _count = "forge_server" callExtension ["task:defuse:get", ["task-cache-1"]];

Error Handling

private _payload = _result select 0;
if (_payload find "Error:" == 0) exitWith {
    systemChat format ["Task error: %1", _payload];
};