forge/arma/server/addons/task/README.md

Forge Task Module

Overview

The task addon is a server-owned mission/task system for Forge. It manages task execution, task-owned state, participant tracking, contribution-based player earnings, and org-owned rewards.

Task operational state is mission-scoped. The extension-backed task catalog, ownership, status, and defuse state are reset on task store startup, so the system intentionally starts clean after each server or mission restart.

Responsibilities

• spawn and monitor task flows on the server
• track per-task entities through TaskStore
• track task participants and engine-rating contribution
• award player earnings through the bank module
• award org funds, reputation, assets, and fleet rewards
• notify task participants and sync org updates to online members

Dependencies

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

Main Components

Task Flows

• fnc_attack.sqf
• fnc_defend.sqf
• fnc_defuse.sqf
• fnc_delivery.sqf
• fnc_destroy.sqf
• fnc_hostage.sqf
• fnc_hvt.sqf

TaskStore

fnc_initTaskStore.sqf initializes TaskStore, which owns:

• task ownership bindings
• participant snapshots
• defuse progress
• per-task entity registries for cargo, hostages, HVTs, IEDs, protected entities, shooters, and targets

Reward Handling

fnc_handleTaskRewards.sqf applies org-owned rewards:

• funds -> org funds
• equipment, supplies, weapons, special -> org assets
• vehicles -> org fleet

Player earnings and org reputation from task outcomes are distributed separately through TaskStore.applyRatingOutcome using Arma engine rating deltas.

Task Ownership

Tasks are bound to an owner org when they are started through fnc_handler.sqf.

• if a requester UID is provided, the task is owned by that requester's org
• if no requester UID is available, the task is bound to the default org

Org rewards always go to the bound owner org. Player earnings still use per-player contribution.

Usage

Task time limits use 0 for no limit on attack, destroy, delivery, hostage, and HVT tasks. Defuse IED timers are different: each IED must have a positive countdown value.

Mission designers can create tasks in four ways:

• Eden modules for editor-authored tasks.
• fnc_startTask.sqf for script-authored tasks.
• fnc_handler.sqf 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.

Create With 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 fnc_startTask.sqf.

Start Through fnc_startTask.sqf

Use fnc_startTask.sqf for script-authored tasks. It registers task entities, creates the BIS task, stores the catalog entry, and dispatches through fnc_handler.sqf.

[
    "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;

Start Through The Handler

Use the handler when you want reputation gating and task ownership binding.

["attack", ["task_attack_1", 1, 2, 1500000, -75, 375, false, false], 250, getPlayerUID player] call forge_server_task_fnc_handler;
["delivery", ["task_delivery_1", 1, 3, "delivery_zone", 250000, -75, 300, false, false, 900], 0, getPlayerUID player] call forge_server_task_fnc_handler;

Arguments:

• 0: task type
• 1: task-specific argument array
• 2: minimum org reputation required to start the task
• 3: requester UID used for ownership binding

Start Task Functions Directly

Direct task calls still work, but they do not provide a requester UID. That means task ownership falls back to the default org.

Use direct starts only when that behavior is intended, such as:

• mission-authored tasks
• editor-placed tasks
• server-owned/random tasks

If you want the accepting player's org to own the task rewards, use fnc_handler.sqf instead.

["task_attack_1", 1, 2, 1500000, -75, 375, false, false] spawn forge_server_task_fnc_attack;
["task_hostage_1", 1, 2, "extract_marker", 1500000, -75, 500, [false, true], false, false] spawn forge_server_task_fnc_hostage;

Event Hooks

• XEH_preInit.sqf
  • compiles functions
  • initializes TaskStore
• XEH_postInit.sqf
  • registers the ACE defuse event hook
  • starts the attack-only mission manager on the server

Notes

• the dynamic mission manager in fnc_missionManager.sqf is now limited to attack missions only
• it starts server-owned tasks through fnc_handler.sqf and binds them to the default org
• task lifecycle for the mission manager is tracked through TaskStore status entries
• task backend state is intentionally transient and resets with the active server/mission lifecycle
• task rewards are org-owned, not player-owned
• participant notifications are sent through the notifications module, not through local server UI

Authors

• J. Schmidt
• Creedcoder
• IDSolutions