diff --git a/arma/server/addons/task/README.md b/arma/server/addons/task/README.md index 038449d..a989515 100644 --- a/arma/server/addons/task/README.md +++ b/arma/server/addons/task/README.md @@ -63,6 +63,64 @@ 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`. + +```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. diff --git a/docs/TASK_USAGE_GUIDE.md b/docs/TASK_USAGE_GUIDE.md index 6003e55..60507dd 100644 --- a/docs/TASK_USAGE_GUIDE.md +++ b/docs/TASK_USAGE_GUIDE.md @@ -128,6 +128,41 @@ The task addon provides these server-owned task flows: - `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 @@ -155,6 +190,8 @@ through `forge_server_task_fnc_handler`. ] 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: @@ -167,6 +204,8 @@ registered and you want reputation gating plus ownership binding: ] 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.