IDSolutions/forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance task module documentation with CAD compatibility details and BIS task prerequisites

Browse Source
This commit is contained in:
Jacob Schmidt 2026-04-18 12:32:50 -05:00
parent 0cfaec86d0
commit b8fef9be98
2 changed files with 53 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
arma/server/addons/task/README.md
View File

@ -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

34
docs/TASK_USAGE_GUIDE.md
View File

@ -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