--- title: "Custom Mission Generators" description: "Forge can be used as a complete out-of-box PMC mission framework, or as a foundation that communities build on top of. Custom mission generators should integrate through the same task, CAD, and event surfaces that the built-in mission manager uses." --- This guide documents the supported integration path today and calls out the current CAD generated-task provider limitation that should be addressed by a small framework extension point. ## Recommended Architecture Keep custom generation split into three layers: | Layer | Responsibility | | --- | --- | | Generator | Select a mission type, position, entities, rewards, timing, and ownership metadata. | | Task registration | Create a CAD-visible Forge task catalog entry and BIS map task. | | Mission runtime | Own custom win/loss logic, cleanup, and task status transitions. | Use Forge systems for persistence-adjacent state, dispatch visibility, group assignment, notifications, ownership, rewards, and client refresh behavior. Keep mission-specific spawning and objective logic in the mission or community addon. ## Disable Built-In Generation The built-in timer-driven generator is controlled by the server CBA setting: ```sqf forge_server_task_enableGenerator = false; ``` When disabled, Forge does not run timer-based generated missions and CAD hydrates no built-in generated task types. This does not prevent custom code from creating CAD-visible tasks directly. It only disables the built-in generator request list and the framework-owned manual request entry point. The mission setup UI does not override this setting. Generated mission enablement is mission/server policy and should stay in CBA settings until a provider selection extension point exists. ## Framework Mission Setup UI Forge includes an optional framework-level mission setup UI in `arma/client/addons/mission_setup`. Enable it with the server CBA setting: ```sqf forge_server_task_enableMissionSetup = true; ``` When enabled, the UI opens for the setup operator before the mission manager starts. By default, the operator is the player whose Eden variable name is `ceo`. Missions can override the allowed unit variable names before client post-init completes: ```sqf missionNamespace setVariable [ "forge_server_task_missionSetup_allowedUnitVariables", ["ceo", "mission_admin"], true ]; ``` The UI configures: - opposing faction - max concurrent generated missions - mission interval - location reuse cooldown - funds, reputation, penalty, and time limit ranges Applying the UI writes framework-prefixed setup state: ```sqf forge_server_task_missionSetup_settings forge_server_task_missionSetup_settingsApplied ``` The server also publishes the selected opposing faction and side for generated mission runtime code: ```sqf ENEMY_FACTION_STR ENEMY_SIDE ``` When settings are applied, Forge emits the EventBus event `mission.setup.applied` with the applied settings in the event payload. The mission manager waits until setup settings are applied. There is no timeout fallback. If the operator presses Cancel, X, or Escape, Forge applies default settings from CBA, mission parameters, and `CfgMissions`, then starts normally. After setup settings have been applied, the setup UI cannot be reopened. The actor interaction entry is hidden once clients receive the public applied flag, and direct or stale open requests receive a notification explaining that setup has already been applied. ## CAD-Visible Task Contract CAD reads assignable contracts from `TaskStore.getActiveTaskCatalog`. A custom task appears in CAD when it has: - a task catalog entry - a task status of `available`, `assigned`, or `active` - a stable `taskID` or `taskId` - display fields such as `title`, `description`, `type`, and `position` The easiest supported path is to call `forge_server_task_fnc_startTask` from server-side mission code: ```sqf [ "attack", "custom_attack_01", getMarkerPos "custom_attack_area", "Raid the Checkpoint", "Clear the checkpoint and secure the site.", createHashMapFromArray [ ["targets", [target_1, target_2, target_3]] ], createHashMapFromArray [ ["limitSuccess", 3], ["limitFail", 0], ["funds", 25000], ["ratingSuccess", 10], ["ratingFail", -5], ["timeLimit", 1200] ], 0, "", "custom_generator" ] call forge_server_task_fnc_startTask; ``` `startTask` registers entities, creates the BIS task, upserts the Forge task catalog entry, sets the initial task status, and dispatches the matching Forge task flow. ## Custom Runtime Tasks If a community generator has its own objective logic and does not use a built-in Forge task flow, register the catalog entry and status directly: ```sqf private _taskID = "pvp_supply_drop_01"; private _entry = createHashMapFromArray [ ["taskID", _taskID], ["taskId", _taskID], ["type", "pvp_supply_drop"], ["taskType", "custom"], ["title", "Contest the Supply Drop"], ["description", "Secure the marked drop zone before the opposing team."], ["position", getMarkerPos "supply_drop_zone"], ["accepted", false], ["requesterUid", ""], ["orgID", "default"], ["source", "custom_generator"] ]; "forge_server" callExtension ["task:catalog:upsert", [ _taskID, toJSON _entry ]]; "forge_server" callExtension ["task:status:set", [ _taskID, "available" ]]; ``` Create a BIS task separately if players should see it in the vanilla map task tab: ```sqf [ west, _taskID, ["Secure the supply drop.", "Supply Drop", "custom"], getMarkerPos "supply_drop_zone", "CREATED", 1, true, "container" ] call BIS_fnc_taskCreate; ``` When custom objective logic completes, set the task status: ```sqf "forge_server" callExtension ["task:status:set", [_taskID, "succeeded"]]; // or "forge_server" callExtension ["task:status:set", [_taskID, "failed"]]; ``` Use `task:clear` or `task:catalog:delete` when the custom runtime fully owns cleanup and the contract should leave CAD. ## CAD Assignment Lifecycle CAD assignment and task execution are intentionally separate. | Phase | Task status | Owner | | --- | --- | --- | | Created and visible | `available` | No group reservation yet. | | Dispatcher assigns | `assigned` | CAD reserves the task for a group. | | Group leader acknowledges | `active` | Task ownership is accepted for the acknowledging player/org. | | Runtime finishes | `succeeded` or `failed` | CAD refreshes and removes completed active contracts. | Custom task logic should account for this lifecycle. If the task should not start until the assigned group leader accepts it, wait for `active` status: ```sqf waitUntil { sleep 2; private _statusResult = "forge_server" callExtension ["task:status:get", [_taskID]]; private _status = fromJSON (_statusResult select 0); _status isEqualTo "active" }; ``` If a group declines the assignment, CAD returns the task to `available`. ## EventBus Integration The server EventBus is an in-process SQF event system. Initialize it if needed: ```sqf if (isNil "forge_server_common_EventBus") then { call forge_server_common_fnc_eventBus; }; ``` Subscribe to CAD and task lifecycle events: ```sqf private _token = forge_server_common_EventBus call ["on", [ "cad.assignment.acknowledged", { params ["_event"]; private _taskID = _event getOrDefault ["taskID", ""]; private _assignment = _event getOrDefault ["assignment", createHashMap]; diag_log format [ "[CustomGenerator] Task %1 acknowledged by group %2", _taskID, _assignment getOrDefault ["groupId", ""] ]; }, "custom_generator.assignment" ]]; ``` Remove a listener when it is no longer needed: ```sqf forge_server_common_EventBus call ["off", [_token]]; ``` Useful CAD events: | Event | When it fires | | --- | --- | | `cad.assignment.assigned` | Dispatcher assigns a task or order. | | `cad.assignment.acknowledged` | Group leader accepts an assignment. | | `cad.assignment.declined` | Group leader declines an assignment. | | `cad.assignment.closed` | Dispatch order is closed. | | `cad.request.submitted` | Support request is submitted. | | `cad.request.closed` | Support request is closed. | | `cad.group.updated` | Group status or role changes. | Useful task events: | Event | When it fires | | --- | --- | | `task.created` | Task catalog entry is registered through TaskStore. | | `task.started` | Task status transitions to active/started. | | `task.completed` | Task succeeds. | | `task.failed` | Task fails. | | `task.cleared` | Task state is cleared. | | `task.reward.applied` | Task reward mutation succeeds. | | `task.rating.applied` | Rating/earnings outcome succeeds. | | `task.notification.requested` | Task participant notification is requested. | CAD already listens to task and CAD events and globally invalidates CAD state when relevant changes occur. Custom generators usually only need to emit task status changes through TaskStore or extension commands; CAD refresh follows from the existing listeners. ## Generated Task Dropdown Limitation The current CAD generated-task dropdown is owned by the framework task mission manager. CAD hydrates `generatedTaskTypes` from the built-in manager when `forge_server_task_enableGenerator` is enabled. When that setting is disabled, the generated-task request control is disabled. The current CAD request handler calls `forge_server_task_fnc_requestMissionTask` directly. It no longer falls back to mission-local generator request functions, so third-party generated-task providers should create CAD-visible tasks directly until a framework provider extension point is added. Until a provider extension point is added, use one of these supported patterns: 1. Run custom generators from mission/server code and create CAD-visible tasks directly. 2. Use CAD support requests or dispatch orders to let players request custom work, then have mission code convert approved requests into tasks. 3. Keep the built-in generator enabled only if the community intentionally wants the framework dropdown and request handler. ## Planned Provider Extension Point A future code change should make CAD generator providers explicit. The desired shape is: - built-in Forge provider remains the default out-of-box behavior - mission/community providers can supply their own `generatedTaskTypes` - mission/community providers can handle generated-task requests - disabling the built-in provider does not disable custom providers - mission designers or developers can select or toggle the active generator provider when a mission includes custom generators - a framework-hosted mission setup UI can display the active provider and, when supported by the mission, allow choosing between built-in and custom providers Candidate SQF hooks: ```sqf forge_custom_fnc_getGeneratedTaskTypes forge_custom_fnc_requestMissionTask ``` or mission namespace variables: ```sqf missionNamespace setVariable ["forge_generatorProvider_getTypes", { [ createHashMapFromArray [["value", "supply_drop"], ["label", "Supply Drop"]], createHashMapFromArray [["value", "pvp_hold"], ["label", "PvP Hold Area"]] ] }]; missionNamespace setVariable ["forge_generatorProvider_requestTask", { params ["_taskType", "_metadata", "_requesterUid"]; createHashMapFromArray [ ["success", true], ["message", "Generated custom task."], ["taskID", "custom_task_01"], ["taskType", _taskType] ] }]; ``` The exact API should be implemented in the framework code before communities depend on it. Implementation note: the provider selection should be separate from `forge_server_task_enableGenerator`. That CBA setting should continue to gate the built-in Forge generator, while a new provider option can decide whether CAD/manual requests use the built-in provider, a custom provider, both, or no provider at all. ## Validation Checklist For each custom generator: 1. Disable the built-in generator if it should not run. 2. Generate or place task entities on the server. 3. Register a task catalog entry with stable `taskID` and display fields. 4. Set task status to `available`. 5. Confirm the task appears in CAD. 6. Assign it to a group from CAD. 7. Acknowledge and decline from the group leader UI. 8. Confirm custom logic waits for `active` if needed. 9. Set `succeeded` or `failed` when the objective resolves. 10. Confirm CAD refreshes and rewards or cleanup behave as expected.