From c176837a2cf841de6fbcc254050ee62c41253f0e Mon Sep 17 00:00:00 2001 From: Jacob Schmidt Date: Fri, 15 May 2026 20:46:19 -0500 Subject: [PATCH] Verify and fix module documentation accuracy - Add missing forge_server_actor runtime dependency to phone module (critical) - Clarify that garage and locker are event bus listeners, not emitters - Document economy runtime-only dependencies (bank, org) - Add TaskStore public API documentation (27 methods organized by category) - Update task module event emissions and hooks documentation All documentation now aligns with actual implementation verified against codebase. --- arma/server/addons/bank/README.md | 6 ++++++ arma/server/addons/cad/README.md | 21 ++++++++++++++++++--- arma/server/addons/economy/README.md | 11 +++++++++-- arma/server/addons/garage/README.md | 6 ++++++ arma/server/addons/locker/README.md | 7 +++++++ arma/server/addons/org/README.md | 6 ++++++ arma/server/addons/phone/README.md | 1 + arma/server/addons/store/README.md | 7 +++++++ arma/server/addons/task/README.md | 28 ++++++++++++++++++++++++++-- 9 files changed, 86 insertions(+), 7 deletions(-) diff --git a/arma/server/addons/bank/README.md b/arma/server/addons/bank/README.md index b1875b8..8d2a9e9 100644 --- a/arma/server/addons/bank/README.md +++ b/arma/server/addons/bank/README.md @@ -37,3 +37,9 @@ server addons. `forge_server_main_fnc_saveHotState` saves bank hot state on disconnect and mission shutdown. Store checkout and task rewards use this addon for authoritative player balance changes. + +Account syncs and notifications route through the event bus: +- `bank.account.sync.requested` - client-facing account sync +- `notification.requested` - alerts and transaction notifications + +These events are emitted and listened to by the notifications addon. diff --git a/arma/server/addons/cad/README.md b/arma/server/addons/cad/README.md index 3c17a90..223d9c1 100644 --- a/arma/server/addons/cad/README.md +++ b/arma/server/addons/cad/README.md @@ -29,9 +29,24 @@ active server or mission lifecycle and starts fresh after restart. - `fnc_initRequestRepository.sqf` manages support requests. ## Event Surface -The addon handles hydrate, task assignment, dispatch order, support request, -task acknowledge/decline, and group update events. Successful mutations can -invalidate CAD state globally so clients refresh their views. +The addon listens to and emits events through the event bus: + +**Listens to:** +- Task lifecycle events (`task.started`, `task.completed`, `task.failed`) +- Task reward events to sync assignments +- Client notification/sync request events + +**Emits:** +- `cad.assignment.assigned` - task assigned to group +- `cad.assignment.created` - new assignment created +- `cad.assignment.acknowledged` - assignment acknowledged +- `cad.assignment.declined` - assignment declined +- `cad.assignment.closed` - assignment completed +- `cad.request.submitted` - support request submitted +- `cad.request.closed` - support request resolved +- `cad.group.updated` - group status updated + +Successful mutations may invalidate CAD state globally so clients refresh their views. ## Notes CAD hydrate payloads include active task catalog entries from `TaskStore` and diff --git a/arma/server/addons/economy/README.md b/arma/server/addons/economy/README.md index 988ca10..5086506 100644 --- a/arma/server/addons/economy/README.md +++ b/arma/server/addons/economy/README.md @@ -12,10 +12,12 @@ charges such as repairs. ## Dependencies - `forge_server_main` - `forge_server_common` for logging, formatting, and player lookup -- `forge_server_bank` for player-funded medical billing -- `forge_server_org` for extension-backed organization hot-cache charges +- `forge_server_bank` (runtime) for player-funded medical billing +- `forge_server_org` (runtime) for extension-backed organization hot-cache charges - `forge_client_actor` and `forge_client_notifications` for response RPCs +Note: Bank and Org are runtime-only dependencies (not compile-time requiredAddons). They must be loaded before economy stores initialize. + ## Main Components - `fnc_initFEconomyStore.sqf` tracks active refueling sessions, calculates fuel totals, charges the player's organization through `OrgStore`, syncs the org @@ -35,6 +37,11 @@ service, repair service, player killed, player respawn, and healing. Medical store initialization runs after post-init to discover configured medical spawn objects. +Service results emit notifications and syncs through the event bus: +- `notification.requested` - service receipts and failure alerts +- `org.sync.requested` - organization balance updates after service charges +- `bank.account.sync.requested` - player bank/cash balance updates from medical billing + Repair service requests use: ```sqf diff --git a/arma/server/addons/garage/README.md b/arma/server/addons/garage/README.md index 9de1717..9eece37 100644 --- a/arma/server/addons/garage/README.md +++ b/arma/server/addons/garage/README.md @@ -28,3 +28,9 @@ objects. ## Runtime Notes `forge_server_main_fnc_saveHotState` saves both `GarageStore` and `VGarageStore` on disconnect and mission shutdown. + +Garage listens for sync events through the event bus: +- `garage.vgarage.sync.requested` - updates client vehicles and unlock state when granted by store/task checkout +- `notification.requested` - storage and vehicle modification alerts + +The store module emits these events when granting vehicles; garage applies the changes to player state. diff --git a/arma/server/addons/locker/README.md b/arma/server/addons/locker/README.md index dc7e8ce..1a82b3d 100644 --- a/arma/server/addons/locker/README.md +++ b/arma/server/addons/locker/README.md @@ -28,3 +28,10 @@ validation, synchronization, and save calls. `forge_server_main_fnc_saveHotState` saves both `LockerStore` and `VAStore` on disconnect and mission shutdown. Store checkout and task rewards can grant assets into organization-owned storage through the org addon. + +Locker listens for sync events through the event bus: +- `locker.sync.requested` - updates client item storage when granted by store/task checkout +- `locker.va.sync.requested` - updates client arsenal unlocks when granted +- `notification.requested` - storage and item modification alerts + +The store module emits these events when granting items; locker applies the changes to player state. diff --git a/arma/server/addons/org/README.md b/arma/server/addons/org/README.md index 730e40c..0c5f949 100644 --- a/arma/server/addons/org/README.md +++ b/arma/server/addons/org/README.md @@ -34,3 +34,9 @@ and task flows. The addon ensures the `default` organization exists during store creation. Task rewards and store checkout both rely on `OrgStore` for authoritative organization-owned state. + +Organization syncs and notifications route through the event bus: +- `org.sync.requested` - client-facing organization patch and member updates +- `notification.requested` - alerts about funds, reputation, and membership changes + +These events are emitted and listened to by the notifications addon. diff --git a/arma/server/addons/phone/README.md b/arma/server/addons/phone/README.md index 2b2398e..a5dfbeb 100644 --- a/arma/server/addons/phone/README.md +++ b/arma/server/addons/phone/README.md @@ -8,6 +8,7 @@ event-facing API and synchronize client UI state. ## Dependencies - `forge_server_main` - `forge_server_common` at runtime for online player lookup +- `forge_server_actor` at runtime for contact and player lookups - `forge_server_extension` at runtime for phone extension calls - `forge_client_phone` for response RPCs diff --git a/arma/server/addons/store/README.md b/arma/server/addons/store/README.md index 46feb3c..8518890 100644 --- a/arma/server/addons/store/README.md +++ b/arma/server/addons/store/README.md @@ -33,3 +33,10 @@ Store checkout can charge cash, bank balance, organization funds, or approved credit lines depending on the hydrated session context. Checkout results can grant locker assets, organization assets, and fleet vehicles through the related domain stores. + +Checkout results emit notifications and syncs through the event bus: +- `notification.requested` - receipt and transaction alerts +- `bank.account.sync.requested` - player balance updates +- `org.sync.requested` - organization balance and asset updates +- `locker.sync.requested` - item grant notifications +- `garage.vgarage.sync.requested` - vehicle grant notifications diff --git a/arma/server/addons/task/README.md b/arma/server/addons/task/README.md index db86626..dcd4b28 100644 --- a/arma/server/addons/task/README.md +++ b/arma/server/addons/task/README.md @@ -41,6 +41,15 @@ system intentionally starts clean after each server or mission restart. - defuse progress - per-task entity registries for cargo, hostages, HVTs, IEDs, protected entities, shooters, and targets +**Public API Methods:** +- **Lifecycle**: `bindTaskOwnership`, `releaseTaskOwnership`, `registerTaskCatalogEntry`, `setTaskStatus`, `getTaskStatus`, `clearTaskStatus`, `clearTask` +- **Catalog**: `getActiveTaskCatalog`, `hasTaskCatalogEntry`, `getTaskCatalogEntry` +- **Entities**: `registerTaskEntity`, `getTaskEntities`, `findTaskEntityOwner`, `clearTaskEntities` +- **Participants**: `acceptTask`, `isTaskAccepted`, `trackParticipants`, `getTaskParticipants`, `getTaskParticipantUids`, `notifyParticipants` +- **Rewards**: `resolveRewardContext`, `applyRatingOutcome`, `incrementDefuseCount`, `getDefuseCount` +- **Events**: `emitTaskLifecycleEvent`, `buildTaskLifecycleEventPayload` +- **Utilities**: `callTaskState`, `callTaskStateEnvelope` + ### Object Model Object-style task instances and entity controllers live under `functions/objects/` and are initialized directly from `XEH_preInit.sqf`. @@ -207,14 +216,29 @@ If you want the accepting player's org to own the task rewards, use `fnc_handler ["task_hostage_1", 1, 2, "extract_marker", 1500000, -75, 500, [false, true], false, false] spawn forge_server_task_fnc_hostage; ``` -## Event Hooks +## Event Hooks and Bus Integration - `XEH_preInit.sqf` - compiles functions - initializes `TaskStore` + - initializes task instance and entity controller classes - `XEH_postInit.sqf` - - registers temporary task lifecycle event logs for migration testing + - registers task lifecycle event listeners with the event bus + - handles task reward, notification, and rating events + - syncs org and bank state through event bus listeners - registers the ACE defuse event hook +## Events Emitted +Task module emits the following events to the event bus: +- `task.created` - task instance created +- `task.started` - task execution started +- `task.completed` - task succeeded +- `task.failed` - task failed +- `task.cleared` - task cleaned up +- `task.reward.requested` - org rewards pending application +- `task.reward.applied` - org rewards applied +- `task.rating.applied` - player rating applied +- `task.notification.requested` - participant notifications pending dispatch + ## Notes - the dynamic mission manager in `fnc_missionManager.sqf` is currently not started by default - it starts server-owned tasks through `fnc_handler.sqf` and binds them to the `default` org