120 lines
3.1 KiB
Markdown
120 lines
3.1 KiB
Markdown
# Task Usage Guide
|
|
|
|
The task module stores transient mission task metadata for active server or
|
|
mission lifecycle workflows. SQF still owns Arma-only runtime state such as
|
|
objects and participants.
|
|
|
|
## Data Model
|
|
|
|
Catalog entries are flexible JSON objects. The service normalizes these fields
|
|
when a catalog entry is inserted or ownership changes:
|
|
|
|
- `taskId`
|
|
- `taskID`
|
|
- `accepted`
|
|
- `requesterUid`
|
|
- `orgID`
|
|
|
|
Ownership context:
|
|
|
|
```json
|
|
{
|
|
"requesterUid": "76561198000000000",
|
|
"orgId": "default"
|
|
}
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Arguments | Returns |
|
|
| --- | --- | --- |
|
|
| `task:reset` | none | `true`. |
|
|
| `task:catalog:active` | none | Active catalog entry array JSON. |
|
|
| `task:catalog:get` | `task_id` | Catalog entry JSON or `null`. |
|
|
| `task:catalog:upsert` | `task_id`, `entry_json` | Stored catalog entry JSON. |
|
|
| `task:catalog:delete` | `task_id` | `true`. |
|
|
| `task:ownership:bind` | `task_id`, `ownership_json` | Ownership mutation result JSON. |
|
|
| `task:ownership:release` | `task_id` | Ownership mutation result JSON. |
|
|
| `task:ownership:accept` | `task_id`, `ownership_json` | Ownership mutation result JSON. |
|
|
| `task:ownership:reward_context` | `task_id` | Reward context JSON. |
|
|
| `task:status:set` | `task_id`, `status` | `true`. |
|
|
| `task:status:get` | `task_id` | Status string JSON. |
|
|
| `task:status:clear` | `task_id` | `true`. |
|
|
| `task:defuse:increment` | `task_id` | New counter value JSON. |
|
|
| `task:defuse:get` | `task_id` | Counter value JSON. |
|
|
| `task:clear` | `task_id` | `true`. |
|
|
|
|
## Upsert a Catalog Entry
|
|
|
|
```sqf
|
|
private _entry = createHashMapFromArray [
|
|
["title", "Destroy Cache"],
|
|
["description", "Destroy the enemy supply cache."],
|
|
["reward", 1500]
|
|
];
|
|
|
|
private _result = "forge_server" callExtension ["task:catalog:upsert", [
|
|
"task-cache-1",
|
|
toJSON _entry
|
|
]];
|
|
```
|
|
|
|
## Mark a Task Active
|
|
|
|
```sqf
|
|
"forge_server" callExtension ["task:status:set", [
|
|
"task-cache-1",
|
|
"active"
|
|
]];
|
|
|
|
private _active = "forge_server" callExtension ["task:catalog:active", []];
|
|
```
|
|
|
|
Completed statuses `succeeded` and `failed` are also stored as completed status
|
|
fallbacks. Clearing status removes active and completed state.
|
|
|
|
## Accept a Task
|
|
|
|
```sqf
|
|
private _ownership = createHashMapFromArray [
|
|
["requesterUid", getPlayerUID player],
|
|
["orgId", "default"]
|
|
];
|
|
|
|
private _result = "forge_server" callExtension ["task:ownership:accept", [
|
|
"task-cache-1",
|
|
toJSON _ownership
|
|
]];
|
|
```
|
|
|
|
`task:ownership:accept` fails if the task is not active or another requester
|
|
already accepted it.
|
|
|
|
## Rewards
|
|
|
|
```sqf
|
|
private _result = "forge_server" callExtension ["task:ownership:reward_context", [
|
|
"task-cache-1"
|
|
]];
|
|
|
|
private _context = fromJSON (_result select 0);
|
|
```
|
|
|
|
The reward context contains `requesterUid` and `orgId`.
|
|
|
|
## Defuse Counter
|
|
|
|
```sqf
|
|
"forge_server" callExtension ["task:defuse:increment", ["task-cache-1"]];
|
|
private _count = "forge_server" callExtension ["task:defuse:get", ["task-cache-1"]];
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
```sqf
|
|
private _payload = _result select 0;
|
|
if (_payload find "Error:" == 0) exitWith {
|
|
systemChat format ["Task error: %1", _payload];
|
|
};
|
|
```
|