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.
This commit is contained in:
Jacob Schmidt 2026-05-15 20:46:19 -05:00
parent b1959ee06d
commit c176837a2c
9 changed files with 86 additions and 7 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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