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

### 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 `fnc_startTask.sqf`
- `fnc_startTask.sqf`: compatible because it registers the catalog entry,
  creates the BIS task, and dispatches through `fnc_handler.sqf`
- dynamic mission manager attack tasks: compatible because the mission manager
  uses `fnc_startTask.sqf`

Limited or incompatible paths:
- `fnc_handler.sqf`: 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 or upsert the catalog entry
- direct task function calls: not CAD-compatible by default. They bypass
  `fnc_startTask.sqf` and usually do not register the task catalog entry or
  active status that CAD hydrates from

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

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

```sqf
["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.

```sqf
["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