# Task Usage Guide - forge-docus
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.

Server Modules

# 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.

# 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. This path expects the BIS task and catalog entry to already exist if map-task and CAD visibility are required.
- Direct task function calls for server-owned or mission-authored flows that intentionally fall back to the `default` org. This path expects the BIS task to already exist if map-task visibility is required.

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

## CAD Compatibility

CAD hydrates assignable tasks from `TaskStore.getActiveTaskCatalog`. A task must have a catalog entry and active task status before CAD can show and assign it.

CAD-compatible creation paths:

- Eden modules: compatible because they delegate to `forge_server_task_fnc_startTask`.
- `forge_server_task_fnc_startTask`: compatible because it registers the catalog entry, creates the BIS task, and dispatches through the handler.
- Dynamic mission manager attack tasks: compatible because the mission manager uses `forge_server_task_fnc_startTask`.

Limited or incompatible paths:

- `forge_server_task_fnc_handler`: only compatible if a catalog entry was already registered elsewhere. The handler sets active status and ownership, but it does not create the BIS task shown in the map task tab or upsert the catalog entry.
- Direct task function calls: not CAD-compatible by default. They bypass `startTask` and usually do not register the task catalog entry or active status that CAD hydrates from. They also only call `BIS_fnc_taskSetState` at completion/failure; they do not create the BIS task first.

## BIS Map Task Prerequisite

Only the Eden task modules and `forge_server_task_fnc_startTask` create the BIS task automatically through `BIS_fnc_taskCreate`.

If a mission uses `forge_server_task_fnc_handler` directly or calls a task flow function such as `forge_server_task_fnc_attack`, the mission must create a BIS task with the same task ID before the Forge task completes. Otherwise the success/failure `BIS_fnc_taskSetState` call has no visible map task to update.

That prerequisite can be satisfied with a vanilla Eden task creation module or a scripted `BIS_fnc_taskCreate` call. `forge_server_task_fnc_startTask` is the preferred Forge path because it handles BIS task creation, Forge catalog registration, entity registration, and handler dispatch together.

## 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. Create the BIS task and catalog entry separately if this task should appear in the map task tab or CAD:

    [
        "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. Create the BIS task separately if this task should appear in the map task tab.

## 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];
    };

Edit this page or Report an issue

Store Usage Guide

The store module processes checkout requests. It charges a payment source and grants purchased items to the player locker, virtual arsenal locker, and virtual garage unlocks.

Bank Usage Guide

The bank module stores player account balances, earnings, PINs, and transaction strings. The hot-state API also owns the active banking workflows used by the UI: deposit, withdraw, transfer, checkout charge, and PIN validation.