From b8fef9be984e639cca48c3a0c3c2e1e1c9c98a5f Mon Sep 17 00:00:00 2001 From: Jacob Schmidt Date: Sat, 18 Apr 2026 12:32:50 -0500 Subject: [PATCH] Enhance task module documentation with CAD compatibility details and BIS task prerequisites --- arma/server/addons/task/README.md | 29 ++++++++++++++++++++++---- docs/TASK_USAGE_GUIDE.md | 34 +++++++++++++++++++++++++------ 2 files changed, 53 insertions(+), 10 deletions(-) diff --git a/arma/server/addons/task/README.md b/arma/server/addons/task/README.md index 178b82c..785002c 100644 --- a/arma/server/addons/task/README.md +++ b/arma/server/addons/task/README.md @@ -68,9 +68,11 @@ 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. + 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. + 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. @@ -89,10 +91,26 @@ CAD-compatible creation paths: 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 + 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 `fnc_startTask.sqf` and usually do not register the task catalog entry or - active status that CAD hydrates from + 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 `fnc_startTask.sqf` create the BIS task +automatically through `BIS_fnc_taskCreate`. + +If a mission uses `fnc_handler.sqf` 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. `fnc_startTask.sqf` is the preferred Forge +path because it handles BIS task creation, Forge catalog registration, entity +registration, and handler dispatch together. ### Create With Eden Modules Eden task modules are the normal designer-facing path. Place the module, @@ -142,6 +160,8 @@ creates the BIS task, stores the catalog entry, and dispatches through ### Start Through The Handler Use the handler when you want reputation gating and task ownership binding. +Create the BIS task and catalog entry separately if this task should appear in +the map task tab or CAD. ```sqf ["attack", ["task_attack_1", 1, 2, 1500000, -75, 375, false, false], 250, getPlayerUID player] call forge_server_task_fnc_handler; @@ -156,6 +176,7 @@ Arguments: ### 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. +Create the BIS task separately if this task should appear in the map task tab. Use direct starts only when that behavior is intended, such as: - mission-authored tasks diff --git a/docs/TASK_USAGE_GUIDE.md b/docs/TASK_USAGE_GUIDE.md index 05bc470..0639dbb 100644 --- a/docs/TASK_USAGE_GUIDE.md +++ b/docs/TASK_USAGE_GUIDE.md @@ -133,9 +133,11 @@ 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. + 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. + 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. @@ -158,10 +160,27 @@ 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 or upsert the catalog entry. + 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. + 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 @@ -216,7 +235,9 @@ through `forge_server_task_fnc_handler`. ## Handler Calls Use `forge_server_task_fnc_handler` directly when the task entities are already -registered and you want reputation gating plus ownership binding: +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: ```sqf [ @@ -231,7 +252,8 @@ registered and you want reputation gating plus ownership binding: 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. +`default` org. Create the BIS task separately if this task should appear in the +map task tab. ## Timer Semantics