diff --git a/arma/client/README.md b/arma/client/README.md index 7d8932d..42176c4 100644 --- a/arma/client/README.md +++ b/arma/client/README.md @@ -1,30 +1,46 @@ -

Forge Client

-

- Version - Issues - - License -
- HEMTT - CBA A3 -

+# Forge Client -

- Requires the latest version of CBA A3 -

+Forge Client contains the Arma client-side addons for Forge. It owns player UI, +browser bridges, client repositories, local event handling, and client-to-server +CBA RPC requests. -**Forge Client** aims to... +The client mod pairs with `arma/server`: client addons collect player input and +render state, while server addons and the Rust extension own authoritative +state and persistence. -The project is entirely **open-source** and any contributions are welcome. +## Requirements +- CBA A3 +- ACE3 for features that use ACE interactions, arsenal, spectator, or medical + integrations +- Forge Server running the matching server-side addons -## Core Features +## Addons +- `main`: shared client mod config and macros +- `common`: shared browser UI bridge helpers +- `actor`: player interaction menu and actor repository +- `bank`: banking UI and account request bridge +- `cad`: map/CAD UI for dispatch, groups, tasks, and support requests +- `garage`: vehicle storage and virtual garage UI +- `locker`: locker and virtual arsenal repositories +- `notifications`: notification HUD and sounds +- `org`: organization portal UI +- `phone`: phone, contacts, messages, and email UI +- `store`: storefront catalog and checkout UI -- Feature +## UI Pattern +Most feature UIs use an Arma display with a `CT_WEBBROWSER` control. JavaScript +sends JSON events through A3API, SQF handles them in `fnc_handleUIEvents.sqf`, +and response events are sent back into the browser with `ctrlWebBrowserAction +["ExecJS", ...]`. -## Contributing +Client repositories cache the most recent state for display only. Server addons +and the extension remain authoritative. -For new contributers, see the [Contributing Setup & Guidelines](./.github/CONTRIBUTING.md). +## Documentation +- [Root client usage guide](../../docs/CLIENT_USAGE_GUIDE.md) +- [Client docs](./docs/README.md) +- [Common web UI framework notes](./addons/common/WEB_UI_FRAMEWORK.md) +- [CAD map integration notes](./addons/cad/MAP_README.md) ## License - Forge Client is licensed under [APL-SA](./LICENSE.md). diff --git a/arma/client/addons/actor/README.md b/arma/client/addons/actor/README.md index e83012b..2684cf8 100644 --- a/arma/client/addons/actor/README.md +++ b/arma/client/addons/actor/README.md @@ -1,3 +1,28 @@ -# forge_client_actor +# Forge Client Actor -Description for this addon +## Overview +The actor addon owns the player interaction menu and client-side actor +repository. It initializes actor state from the server, tracks client-visible +actor fields, and routes menu actions to other Forge UIs. + +## Dependencies +- `forge_client_main` +- server actor events from `forge_server_actor` +- runtime integrations with bank, CAD, garage, org, phone, store, locker, and + notifications addons + +## Main Components +- `fnc_initRepository.sqf` manages client actor state and server init/save + requests. +- `fnc_openUI.sqf` opens `RscActorMenu`. +- `fnc_handleUIEvents.sqf` handles browser menu actions. + +## Event Surface +The actor menu can open bank, ATM mode, CAD, garage, virtual garage, org, phone, +store, and ACE arsenal interactions. Client post-init also wires player killed +and respawn handlers into the server economy flow. + +## Runtime Notes +Actor state is loaded before dependent systems initialize. When the server sends +actor sync data, the repository updates local view state and clears the loading +screen. diff --git a/arma/client/addons/bank/README.md b/arma/client/addons/bank/README.md index a4b1503..bb1bf03 100644 --- a/arma/client/addons/bank/README.md +++ b/arma/client/addons/bank/README.md @@ -1,3 +1,34 @@ -# forge_client_bank +# Forge Client Bank -Description for this addon +## Overview +The bank addon provides the client banking UI and browser bridge for account +hydrate, deposits, withdrawals, transfers, PIN entry, earnings deposits, and +credit-line repayment. + +## Dependencies +- `forge_client_common` +- `forge_client_main` +- server bank events from `forge_server_bank` +- notifications for server-driven messages + +## Main Components +- `fnc_initRepository.sqf` tracks account load state. +- `fnc_initUIBridge.sqf` translates browser requests into server RPCs and sends + server responses back to the browser. +- `fnc_handleUIEvents.sqf` handles `bank::*` browser events. +- `fnc_openUI.sqf` opens `RscBank`; ATM mode is supported by passing `true`. + +## Browser Events +- `bank::ready` +- `bank::refresh` +- `bank::deposit::request` +- `bank::withdraw::request` +- `bank::transfer::request` +- `bank::depositEarnings::request` +- `bank::repayCreditLine::request` +- `bank::pin::request` +- `bank::close` + +## Runtime Notes +The client only displays and requests account changes. The server bank addon and +extension own validation, balances, authorization, and persistence. diff --git a/arma/client/addons/cad/README.md b/arma/client/addons/cad/README.md new file mode 100644 index 0000000..5f5d438 --- /dev/null +++ b/arma/client/addons/cad/README.md @@ -0,0 +1,37 @@ +# Forge Client CAD + +## Overview +The CAD addon provides the client map and dispatch interface for task +assignment, dispatch orders, support requests, group status, group roles, and +task acknowledge/decline actions. + +## Dependencies +- `forge_client_main` +- server CAD events from `forge_server_cad` +- server task catalog data exposed through CAD hydrate payloads + +## Main Components +- `fnc_initRepository.sqf` caches hydrated CAD view state. +- `fnc_initUI.sqf` wires the native map, top bar, bottom bar, side panel, and + dispatcher browser controls. +- `fnc_initUIBridge.sqf` sends browser actions to server CAD RPCs and pushes + state back to the UI. +- `fnc_handleUIEvents.sqf` handles `cad::*` browser events. +- `fnc_openUI.sqf` opens the CAD display. + +## Supported Actions +- hydrate CAD state +- assign active tasks to groups +- create and close dispatch orders +- submit and close support requests +- acknowledge or decline assigned tasks +- update group status, role, and profile +- focus map requests and toggle panels + +## Notes +CAD task visibility depends on server-side task catalog entries. Tasks created +through Forge task modules or `forge_server_task_fnc_startTask` are the normal +CAD-compatible task sources. + +See [MAP_README.md](./MAP_README.md) for details on the integrated native map +and browser layout. diff --git a/arma/client/addons/common/README.md b/arma/client/addons/common/README.md index 05fa06e..71c1190 100644 --- a/arma/client/addons/common/README.md +++ b/arma/client/addons/common/README.md @@ -1,5 +1,18 @@ -# forge_client_common +# Forge Client Common -Common functionality shared between addons. +## Overview +The common addon contains shared client-side UI bridge helpers and common +configuration used by browser-based feature addons. -See [WEB_UI_FRAMEWORK.md](./WEB_UI_FRAMEWORK.md) for the proposed shared `CT_WEBBROWSER` UI framework layout and API. +## Dependencies +- `forge_client_main` + +## Main Components +- `fnc_initWebUIBridge.sqf` provides shared bridge behavior for web browser UI + controls. +- `WEB_UI_FRAMEWORK.md` documents the proposed shared browser runtime and event + API for Forge web UIs. + +## Notes +Keep feature-specific behavior in the owning addon. Common should hold reusable +browser bridge patterns, not copied application logic. diff --git a/arma/client/addons/garage/README.md b/arma/client/addons/garage/README.md index 0442fa7..879df40 100644 --- a/arma/client/addons/garage/README.md +++ b/arma/client/addons/garage/README.md @@ -1,3 +1,35 @@ -# forge_client_garage +# Forge Client Garage -Description for this addon +## Overview +The garage addon provides player vehicle storage UI, vehicle store/retrieve +actions, and virtual garage state on the client. + +## Dependencies +- `forge_client_common` +- `forge_client_main` +- server garage events from `forge_server_garage` +- notifications for action feedback + +## Main Components +- `fnc_initRepository.sqf` manages player garage view state. +- `fnc_initVGRepository.sqf` manages virtual garage view state. +- `fnc_initHelperService.sqf` resolves vehicle names, hit points, and payload + details. +- `fnc_initContextService.sqf` gathers nearby/current vehicle context. +- `fnc_initPayloadService.sqf` builds browser hydrate payloads. +- `fnc_initActionService.sqf` sends store/retrieve requests and handles action + responses. +- `fnc_initUIBridge.sqf` pushes hydrate/sync events to the browser. +- `fnc_openUI.sqf` opens `RscGarage`. +- `fnc_openVG.sqf` opens the Arma garage-style virtual garage view. + +## Browser Events +- `garage::ready` +- `garage::refresh` +- `garage::vehicle::retrieve::request` +- `garage::vehicle::store::request` +- `garage::close` + +## Runtime Notes +The client builds vehicle context and sends requests. The server garage addon +and extension own stored vehicle state. diff --git a/arma/client/addons/locker/README.md b/arma/client/addons/locker/README.md index ccd333d..b5530cf 100644 --- a/arma/client/addons/locker/README.md +++ b/arma/client/addons/locker/README.md @@ -1,3 +1,27 @@ -# forge_client_locker +# Forge Client Locker -Description for this addon +## Overview +The locker addon manages client repositories for personal locker state and +virtual arsenal unlock state. It also integrates with ACE Arsenal display +behavior. + +## Dependencies +- `forge_client_main` +- ACE Arsenal +- server locker events from `forge_server_locker` + +## Main Components +- `fnc_initRepository.sqf` manages locker state, container open/close behavior, + and server sync requests. +- `fnc_initVARepository.sqf` manages virtual arsenal state. + +## Runtime Behavior +- Requests locker and virtual arsenal state after actor load. +- Syncs server responses into client repositories. +- Sends locker override data to the server when a managed locker container is + closed. +- Hides selected ACE Arsenal controls when the arsenal display opens. + +## Notes +The client repository is display/input state. The server locker addon and +extension own saved locker and virtual arsenal data. diff --git a/arma/client/addons/main/README.md b/arma/client/addons/main/README.md index 0f8cf55..52bdcff 100644 --- a/arma/client/addons/main/README.md +++ b/arma/client/addons/main/README.md @@ -1,3 +1,18 @@ -# forge_client_main +# Forge Client Main -Main Addon for forge-client +## Overview +The main addon provides shared mod metadata, macros, settings, and compile +infrastructure for Forge client addons. + +## Dependencies +- `cba_main` + +## Main Components +- `script_macros.hpp` defines shared function, RPC, path, variable, and compile + macros. +- `script_mod.hpp` and `script_version.hpp` define mod identity and version. +- `CfgSettings.hpp` contains client-side CBA settings. + +## Notes +Feature logic should live in the owning addon. Main is the shared foundation for +configuration, macros, and mod-level metadata. diff --git a/arma/client/addons/notifications/README.md b/arma/client/addons/notifications/README.md index ea21f89..5c3fe16 100644 --- a/arma/client/addons/notifications/README.md +++ b/arma/client/addons/notifications/README.md @@ -1,3 +1,27 @@ -# forge_client_notifications +# Forge Client Notifications -Description for this addon +## Overview +The notifications addon owns the client notification HUD, notification sound, +and local notification service used by other Forge client and server modules. + +## Dependencies +- `forge_client_main` + +## Main Components +- `fnc_initService.sqf` manages queued and visible notifications. +- `fnc_openUI.sqf` opens the notification HUD display. +- `fnc_handleUIEvents.sqf` handles browser/HUD events. +- `CfgSounds.hpp` defines the notification sound. + +## Event Surface +`forge_client_notifications_recieveNotification` accepts: + +```sqf +[_type, _title, _content, _duration] +``` + +The event plays the configured sound and adds the notification to the HUD. + +## Runtime Notes +The HUD opens after the virtual arsenal repository is loaded. Other addons +should use this notification event instead of creating their own transient UI. diff --git a/arma/client/addons/org/README.md b/arma/client/addons/org/README.md index a464e97..f1df4f2 100644 --- a/arma/client/addons/org/README.md +++ b/arma/client/addons/org/README.md @@ -1,85 +1,33 @@ -# forge_client_org +# Forge Client Organization -Player organization UI and client integration. +## Overview +The organization addon provides the client organization portal UI and bridge for +organization hydrate, registration, membership, invitations, credit lines, +leave/disband actions, assets, fleet, and treasury display. -## UI Login Contract +## Dependencies +- `forge_client_common` +- `forge_client_main` +- server organization events from `forge_server_org` +- notifications for user feedback -The web UI sends the following request through `A3API.SendAlert`: +## Main Components +- `fnc_initRepository.sqf` caches organization portal state. +- `fnc_initUIBridge.sqf` sends browser requests to server org RPCs and pushes + hydrate/sync events back to the browser. +- `fnc_handleUIEvents.sqf` handles `org::*` browser events. +- `fnc_openUI.sqf` opens `RscOrg`. -```json -{ - "event": "org::login::request", - "data": { - "email": "admin@spearnet.mil", - "password": "secret" - } -} -``` +## Browser Events +- `org::login::request` +- `org::create::request` +- `org::disband::request` +- `org::leave::request` +- `org::credit::request` +- `org::invite::request` +- `org::invite::accept` +- `org::invite::decline` -On success, SQF should call the browser bridge with: - -```sqf -private _payload = createHashMapFromArray [ - ["session", createHashMapFromArray [ - ["actorName", name player], - ["role", "Leader"] - ]], - ["portalData", createHashMapFromArray [ - ["org", createHashMapFromArray [ - ["name", "Black Rifle Company"], - ["tag", "BRC-0160566824"], - ["type", "Private Military Company"], - ["status", "Operational"], - ["headquarters", "Georgetown Command Annex"], - ["owner", "Jacob Schmidt"] - ]], - ["funds", 482750], - ["reputation", 72], - ["members", [ - createHashMapFromArray [["name", "Jacob Schmidt"]], - createHashMapFromArray [["name", "Mara Velez"]] - ]], - ["fleet", [ - createHashMapFromArray [ - ["name", "UH-80 Ghost Hawk"], - ["type", "helicopter"], - ["status", "Ready"], - ["damage", "16%"] - ] - ]], - ["assets", [ - createHashMapFromArray [ - ["name", "First Aid Kits"], - ["type", "items"], - ["quantity", "36"] - ] - ]], - ["activity", []], - ["roadmap", []] - ]] -]; - -_control ctrlWebBrowserAction [ - "ExecJS", - format ["OrgUIBridge.receiveLoginSuccess(%1)", toJSON _payload] -]; -``` - -On failure: - -```sqf -private _payload = createHashMapFromArray [ - ["message", "Invalid credentials."] -]; - -_control ctrlWebBrowserAction [ - "ExecJS", - format ["OrgUIBridge.receiveLoginFailure(%1)", toJSON _payload] -]; -``` - -Current implementation: - -- `fnc_handleUIEvents.sqf` now handles `org::login::request` -- success hydrates the portal with `session` + `portalData` -- failure returns a single `message` string for inline UI feedback +## Runtime Notes +The client portal is a view/controller. Organization state, funds, reputation, +credit lines, assets, fleet, and membership are authoritative on the server. diff --git a/arma/client/addons/phone/README.md b/arma/client/addons/phone/README.md index 756d2e4..d719a9e 100644 --- a/arma/client/addons/phone/README.md +++ b/arma/client/addons/phone/README.md @@ -1,4 +1,29 @@ -forge_client_phone -=================== +# Forge Client Phone -This addon provides the phone user interface and functionality for the in-game phone system. It handles all phone-related features including the UI display, interactions, and core phone operations. \ No newline at end of file +## Overview +The phone addon provides the in-game phone UI for contacts, SMS messages, and +email. It keeps a local `PhoneClass` facade for view state and sends all +authoritative operations to the server phone addon. + +## Dependencies +- `forge_client_main` +- server phone events from `forge_server_phone` +- notifications for contact/message/email feedback + +## Main Components +- `fnc_initClass.sqf` initializes the local phone facade. +- `fnc_handleUIEvents.sqf` translates browser events into server phone RPCs. +- `fnc_openUI.sqf` opens `RscPhone`. +- `ui/_site` contains the browser phone UI source. + +## Supported Operations +- initialize and sync phone state +- refresh contacts +- add/remove contacts by UID, phone number, or email +- send, read, and delete SMS messages +- send, read, and delete email +- push incoming message/email updates into the browser UI + +## Runtime Notes +Phone data is owned by the server extension. Client state is only used to render +the phone UI and provide immediate feedback. diff --git a/arma/client/addons/store/README.md b/arma/client/addons/store/README.md index 8a76830..f2693ad 100644 --- a/arma/client/addons/store/README.md +++ b/arma/client/addons/store/README.md @@ -1,3 +1,28 @@ -# forge_client_store +# Forge Client Store -Description for this addon +## Overview +The store addon provides the client storefront UI for catalog browsing, +category loading, payment-source display, cart handling, and checkout requests. + +## Dependencies +- `forge_client_common` +- `forge_client_main` +- server store events from `forge_server_store` +- bank/org/locker/garage server state through checkout results + +## Main Components +- `fnc_initUIBridge.sqf` handles browser readiness, category requests, checkout + requests, and server responses. +- `fnc_handleUIEvents.sqf` handles `store::*` browser events. +- `fnc_openUI.sqf` opens `RscStore`. + +## Browser Events +- `store::ready` +- `store::category::request` +- `store::checkout::request` +- `store::close` + +## Runtime Notes +The client never calculates authoritative checkout results. The server store +addon and extension validate prices, charge payment sources, grant assets, and +return patches for the UI. diff --git a/arma/client/docs/README.md b/arma/client/docs/README.md index c41b1e5..1fc922c 100644 --- a/arma/client/docs/README.md +++ b/arma/client/docs/README.md @@ -1,54 +1,47 @@ - +# Forge Client Documentation -

forge-client

-

- - forge-client Version - - - forge-client Issues - - - forge-client Downloads - - - forge-client License - -
- HEMTT -

+This folder documents the Arma client mod. The client side is responsible for +displaying UI, handling player input, caching client-visible state, and sending +CBA events to server addons. -

- Requires the latest version of CBA A3 -

+Authoritative gameplay state lives on the server side or in the Rust extension. +Client repositories should be treated as view state, not durable storage. -# Initial Project Setup! +## Architecture +- Each addon declares its own UI resources and CBA extended event handlers. +- `XEH_preStart.sqf`/`XEH_preInit.sqf` compile functions. +- `XEH_postInitClient.sqf` initializes client repositories, UI bridges, and + response event handlers. +- Browser UIs send JSON events through A3API. +- SQF handlers translate browser events into local actions or server RPCs. +- Server responses update repositories and push browser events back into the UI. -Delete this section after the project has been initially set up: +## Addon Docs +- [Main](../addons/main/README.md) +- [Common](../addons/common/README.md) +- [Actor](../addons/actor/README.md) +- [Bank](../addons/bank/README.md) +- [CAD](../addons/cad/README.md) +- [Garage](../addons/garage/README.md) +- [Locker](../addons/locker/README.md) +- [Notifications](../addons/notifications/README.md) +- [Organization](../addons/org/README.md) +- [Phone](../addons/phone/README.md) +- [Store](../addons/store/README.md) -1. Find and replace all instances of `forge-client` with the mod's name. -2. Find and replace all instances of `MOD_REPO` with the mod's name _and no spaces_. - - This should be the name of the repository on GitHub. -3. Find and replace all instances of `forge_client` with the mod's prefix. - - This should be all lowercase. -4. Find and replace all instances of `MOD_ACRONYM` with the mod's acronym. - - This should be all uppercase. -5. After the initial Steam upload, find and replace all instances of `MOD_ID` with the mod's Steam Workshop id. - -For third parties, make sure to also replace `IDSolutions` with your Github username / organization name, and to replace `DartRuffian` with your username. - -**forge-client** (MOD_ACRONYM) aims to... - -The project is entirely **open-source** and any contributions are welcome. - -## Core Features - -- Feature - -## Contributing - -For new contributers, see the [Contributing Setup & Guidelines](./.github/CONTRIBUTING.md). - -## License - -forge-client is licensed under [APL-ND](./LICENSE.md). +## Related Docs +- [Root Client Usage Guide](../../../docs/CLIENT_USAGE_GUIDE.md) +- [Root Client Main Usage Guide](../../../docs/CLIENT_MAIN_USAGE_GUIDE.md) +- [Root Client Common Usage Guide](../../../docs/CLIENT_COMMON_USAGE_GUIDE.md) +- [Root Client Actor Usage Guide](../../../docs/CLIENT_ACTOR_USAGE_GUIDE.md) +- [Root Client Bank Usage Guide](../../../docs/CLIENT_BANK_USAGE_GUIDE.md) +- [Root Client CAD Usage Guide](../../../docs/CLIENT_CAD_USAGE_GUIDE.md) +- [Root Client Garage Usage Guide](../../../docs/CLIENT_GARAGE_USAGE_GUIDE.md) +- [Root Client Locker Usage Guide](../../../docs/CLIENT_LOCKER_USAGE_GUIDE.md) +- [Root Client Notifications Usage Guide](../../../docs/CLIENT_NOTIFICATIONS_USAGE_GUIDE.md) +- [Root Client Organization Usage Guide](../../../docs/CLIENT_ORG_USAGE_GUIDE.md) +- [Root Client Phone Usage Guide](../../../docs/CLIENT_PHONE_USAGE_GUIDE.md) +- [Root Client Store Usage Guide](../../../docs/CLIENT_STORE_USAGE_GUIDE.md) +- [Shared web UI framework notes](../addons/common/WEB_UI_FRAMEWORK.md) +- [CAD map integration notes](../addons/cad/MAP_README.md) +- [Root framework docs](../../../docs/README.md) diff --git a/arma/client/extra/example_addon/README.md b/arma/client/extra/example_addon/README.md index 40e0345..8448397 100644 --- a/arma/client/extra/example_addon/README.md +++ b/arma/client/extra/example_addon/README.md @@ -1,3 +1,9 @@ -# forge_client_addonName +# Forge Client Example Addon -Description for this addon +This directory is a template for creating a new Forge client addon. + +Use it as a starting point for addon structure, config layout, event handler +files, and function preparation. Replace the component names, display strings, +and placeholder implementation with the new addon's real feature behavior. + +Do not ship this example addon as a gameplay module. diff --git a/docs/CLIENT_ACTOR_USAGE_GUIDE.md b/docs/CLIENT_ACTOR_USAGE_GUIDE.md new file mode 100644 index 0000000..bd514dd --- /dev/null +++ b/docs/CLIENT_ACTOR_USAGE_GUIDE.md @@ -0,0 +1,98 @@ +# Client Actor Usage Guide + +The client actor addon owns the player interaction menu and client-side actor +repository. It is the main launcher for nearby player actions and other Forge +client UIs. + +## Open the Actor Menu + +```sqf +call forge_client_actor_fnc_openUI; +``` + +The actor menu opens `RscActorMenu`, loads `ui/_site/index.html`, and routes +browser alerts through `forge_client_actor_fnc_handleUIEvents`. + +## Repository + +`forge_client_actor_fnc_initRepository` creates `GVAR(ActorRepository)`. + +The repository: + +- requests actor initialization from the server +- saves actor state through the server actor addon +- caches client-visible actor fields +- applies position, direction, stance, rank, and loadout on JIP sync when the + relevant settings allow it +- provides nearby interaction actions to the browser UI + +Initialize actor state through the repository: + +```sqf +GVAR(ActorRepository) call ["init", []]; +``` + +Save actor state through the server: + +```sqf +GVAR(ActorRepository) call ["save", [true]]; +``` + +## Nearby Actions + +The menu asks for nearby actions with: + +```text +actor::get::actions +``` + +The repository scans objects within 5 meters and returns actions based on +mission object variables: + +| Variable | Action | +| --- | --- | +| `storeType` | store | +| `isAtm` | ATM | +| `isBank` | bank | +| `isGarage` | garage | +| `garageType` | garage subtype | +| `isLocker` | virtual arsenal action when VA is enabled | +| `deviceType` | device action placeholder | +| nearby player unit | player interaction placeholder | + +The response is pushed into the browser with `updateAvailableActions(...)`. + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `actor::get::actions` | Refresh nearby actions. | +| `actor::close::menu` | Close actor menu. | +| `actor::open::atm` | Open bank UI in ATM mode. | +| `actor::open::bank` | Open bank UI in bank mode. | +| `actor::open::cad` | Open CAD UI. | +| `actor::open::garage` | Open garage UI. | +| `actor::open::vgarage` | Open virtual garage. | +| `actor::open::org` | Open organization UI. | +| `actor::open::vlocker` | Open ACE arsenal on `FORGE_Locker_Box`. | +| `actor::open::phone` | Open phone UI. | +| `actor::open::store` | Open store UI. | + +Device and player interaction events currently display placeholder feedback. + +## Authoritative State + +Actor persistence is server-owned. The client repository requests and displays +actor data, but actor creation, durable updates, and hot-state behavior are +handled by the server actor addon and extension. + +## Related Guides + +- [Actor Usage Guide](./ACTOR_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client CAD Usage Guide](./CLIENT_CAD_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) +- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md) +- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md) +- [Client Phone Usage Guide](./CLIENT_PHONE_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) diff --git a/docs/CLIENT_BANK_USAGE_GUIDE.md b/docs/CLIENT_BANK_USAGE_GUIDE.md new file mode 100644 index 0000000..4390f55 --- /dev/null +++ b/docs/CLIENT_BANK_USAGE_GUIDE.md @@ -0,0 +1,84 @@ +# Client Bank Usage Guide + +The client bank addon opens the bank and ATM browser UI, forwards banking +requests to the server bank addon, and pushes account updates back into the +browser. + +## Open Bank UI + +Open full bank mode: + +```sqf +call forge_client_bank_fnc_openUI; +``` + +Open ATM mode: + +```sqf +[true] call forge_client_bank_fnc_openUI; +``` + +The open function creates `RscBank`, sets the bridge mode to `bank` or `atm`, +loads `ui/_site/index.html`, and routes browser events through +`forge_client_bank_fnc_handleUIEvents`. + +## Bridge and Repository + +`forge_client_bank_fnc_initRepository` tracks account load and cached account +state. + +`forge_client_bank_fnc_initUIBridge` owns: + +- active browser control tracking +- bank/ATM mode +- browser ready handling +- account hydrate and sync responses +- deposit, withdrawal, transfer, earnings deposit, credit repayment, and PIN + requests +- browser notice delivery + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `bank::ready` | Mark browser ready and request hydrate from the server. | +| `bank::refresh` | Request fresh bank hydrate data. | +| `bank::deposit::request` | Forward deposit amount to the server. | +| `bank::withdraw::request` | Forward withdrawal amount to the server. | +| `bank::transfer::request` | Forward target, source field, and amount. | +| `bank::depositEarnings::request` | Request earnings deposit. | +| `bank::repayCreditLine::request` | Request credit-line repayment. | +| `bank::pin::request` | Forward PIN validation request. | +| `bank::close` | Dispose bridge screen state and close the display. | + +## Browser Response Events + +The bridge sends: + +| Event | Purpose | +| --- | --- | +| `bank::hydrate` | Full session/account payload. | +| `bank::sync` | Account patch or sync data. | +| `bank::notice` | UI-visible notice payload. | + +## Request Flow + +Example deposit flow: + +1. Browser sends `bank::deposit::request` with an `amount`. +2. Client bridge calls the server bank request event. +3. Server bank addon validates the request and calls bank hot-state logic. +4. Server response is caught by the client post-init event handlers. +5. Client bridge sends `bank::sync` or `bank::notice` back to the browser. + +## Authoritative State + +Balances, PIN authorization, transfers, checkout charges, credit lines, and +persistence are server-owned. The client should only display account data and +request mutations through server events. + +## Related Guides + +- [Bank Usage Guide](./BANK_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) diff --git a/docs/CLIENT_CAD_USAGE_GUIDE.md b/docs/CLIENT_CAD_USAGE_GUIDE.md new file mode 100644 index 0000000..654f23b --- /dev/null +++ b/docs/CLIENT_CAD_USAGE_GUIDE.md @@ -0,0 +1,100 @@ +# Client CAD Usage Guide + +The client CAD addon provides the map and dispatch UI for groups, active +tasks, task assignment, dispatch orders, support requests, and task +acknowledge/decline workflows. + +## Open CAD UI + +```sqf +call forge_client_cad_fnc_openUI; +``` + +The CAD UI opens `RscMapUI` and loads separate browser controls for: + +- top bar +- bottom bar +- side panel +- dispatcher board + +The native Arma map remains part of the same display. + +## Repository and Bridge + +`forge_client_cad_fnc_initRepository` caches the hydrated CAD payload, +selected mode, dispatch view, session data, groups, tasks, requests, and +assignments. + +`forge_client_cad_fnc_initUIBridge` owns: + +- ready state for side panel, top bar, and dispatcher board +- operations vs dispatch mode +- board vs map dispatch view +- hydrate requests +- task assignment, acknowledge, and decline requests +- dispatch order create/close requests +- support request submit/close requests +- group status, role, and profile requests +- map focus actions + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `cad::topbar::ready` | Mark top bar ready and push top bar state. | +| `cad::ready` | Mark side panel ready and request hydrate. | +| `cad::dispatcher::ready` | Mark dispatcher board ready and push hydrate data. | +| `cad::mode::set` | Switch between operations and dispatch mode. | +| `cad::dispatchView::set` | Switch dispatch board/map view. | +| `cad::refresh` | Request fresh CAD hydrate data. | +| `cad::tasks::assign` | Assign a task to a group. | +| `cad::tasks::acknowledge` | Acknowledge assigned task. | +| `cad::tasks::decline` | Decline assigned task. | +| `cad::dispatchOrder::create` | Create dispatch order. | +| `cad::dispatchOrder::close` | Close dispatch order. | +| `cad::supportRequest::submit` | Submit support request. | +| `cad::supportRequest::close` | Close support request. | +| `cad::groups::status` | Update group status. | +| `cad::groups::role` | Update group role. | +| `cad::groups::profile` | Update status and role together. | +| `cad::groups::focus` | Center map on a group. | +| `cad::tasks::focus` | Center map on a task. | +| `cad::requests::focus` | Center map on a support request. | +| `map::zoomIn` | Zoom native map in. | +| `map::zoomOut` | Zoom native map out. | +| `map::search` | Placeholder status update. | +| `map::close` | Dispose bridge state and close the display. | + +## Response Events + +The bridge pushes: + +| Event | Purpose | +| --- | --- | +| `cad::hydrate` | Full hydrated CAD payload to the side panel. | +| `cad::assignment::response` | Task assignment/acknowledge/decline result. | +| `cad::group::response` | Group status/role/profile result. | +| `cad::request::response` | Support request result. | + +Dispatcher board controls also receive direct `ExecJS` status and hydrate +calls. + +## Task Compatibility + +CAD task visibility depends on server-side task catalog entries. Tasks created +through Eden Forge task modules or `forge_server_task_fnc_startTask` are the +normal CAD-compatible task sources because they register task catalog data. + +Direct handler or task-function calls only work with CAD when the task catalog +entry already exists. + +## Authorization Notes + +Only dispatcher sessions can enter dispatch mode. If the hydrated session is +not a dispatcher, the bridge forces the UI back to operations mode. + +## Related Guides + +- [CAD Usage Guide](./CAD_USAGE_GUIDE.md) +- [Task Usage Guide](./TASK_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) diff --git a/docs/CLIENT_COMMON_USAGE_GUIDE.md b/docs/CLIENT_COMMON_USAGE_GUIDE.md new file mode 100644 index 0000000..754d6c8 --- /dev/null +++ b/docs/CLIENT_COMMON_USAGE_GUIDE.md @@ -0,0 +1,92 @@ +# Client Common Usage Guide + +The client `common` addon contains shared browser UI bridge declarations and +common client-side browser integration patterns. + +## Purpose + +Use `forge_client_common` when a browser-backed feature UI needs reusable +screen lifecycle behavior: + +- active browser control tracking +- browser ready state +- pending event queues +- `ExecJS` payload delivery +- shared bridge object inheritance through `createHashMapObject` + +Feature addons still own their app-specific events and server RPC mapping. + +## Shared Bridge + +Initialize the bridge declarations with: + +```sqf +private _webUIDeclarations = call forge_client_common_fnc_initWebUIBridge; +private _bridgeDeclaration = _webUIDeclarations get "bridgeDeclaration"; +``` + +Feature bridges can inherit from the shared declaration: + +```sqf +GVAR(MyUIBridgeBaseClass) = compileFinal createHashMapFromArray [ + ["#base", _bridgeDeclaration], + ["#type", "MyUIBridgeBaseClass"], + ["handleReady", compileFinal { + params [["_control", controlNull, [controlNull]]]; + + _self call ["setActiveBrowserControl", [_control]]; + _self call ["sendEvent", ["myAddon::hydrate", createHashMap, _control]]; + }] +]; +``` + +## Event Delivery + +`sendEvent` builds this payload: + +```json +{ + "event": "myAddon::event", + "data": {} +} +``` + +If the browser control is missing or not ready, the payload is queued on the +screen object. When the screen marks ready, `flushPendingEvents` delivers the +queue. + +## Screen Lifecycle + +The shared screen object tracks: + +| Field | Purpose | +| --- | --- | +| `control` | Active browser control. | +| `readyState` | Whether the browser app has sent its ready event. | +| `pendingEvents` | Outbound events waiting for a ready browser. | + +Call `handleClose` or `dispose` when a display closes so stale controls and +queued events are cleared. + +## Current Consumers + +The common bridge pattern is used by the newer bank, CAD, garage, and +organization client bridges. Store currently keeps its own bridge object and +browser bridge function names. + +## Usage Rules + +- Keep bridge inheritance in feature addons thin and explicit. +- Keep shared code generic; do not add bank, CAD, org, or store-specific logic + to `common`. +- Prefer namespaced events such as `garage::sync`. +- Send hash maps or arrays that can be safely serialized with `toJSON`. +- Avoid direct extension calls from the client bridge; send CBA server events. + +## Related Guides + +- [Client Usage Guide](./CLIENT_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client CAD Usage Guide](./CLIENT_CAD_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) +- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md) diff --git a/docs/CLIENT_GARAGE_USAGE_GUIDE.md b/docs/CLIENT_GARAGE_USAGE_GUIDE.md new file mode 100644 index 0000000..991c34e --- /dev/null +++ b/docs/CLIENT_GARAGE_USAGE_GUIDE.md @@ -0,0 +1,80 @@ +# Client Garage Usage Guide + +The client garage addon provides player vehicle storage UI, vehicle +store/retrieve actions, vehicle context building, and the virtual garage view. + +## Open Garage UI + +```sqf +call forge_client_garage_fnc_openUI; +``` + +The garage UI opens `RscGarage`, loads `ui/_site/index.html`, and routes +browser events through `forge_client_garage_fnc_handleUIEvents`. + +## Open Virtual Garage + +```sqf +call forge_client_garage_fnc_openVG; +``` + +The virtual garage uses mission-configured `FORGE_CfgGarages` locations to set +the spawn/preview position, opens the BIS garage interface, and restricts the +available vehicle lists from the virtual garage repository. + +## Client Services + +| Service | Purpose | +| --- | --- | +| `GarageRepository` | Player garage view state. | +| `VGRepository` | Virtual garage unlock view state. | +| `GarageHelperService` | Vehicle names, hit points, and payload helpers. | +| `GarageContextService` | Nearby/current vehicle context. | +| `GaragePayloadService` | Browser hydrate payload construction. | +| `GarageActionService` | Store/retrieve request handling. | +| `GarageUIBridge` | Browser ready, hydrate, and sync delivery. | + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `garage::ready` | Mark browser ready and send `garage::hydrate`. | +| `garage::refresh` | Send current garage payload as `garage::sync`. | +| `garage::vehicle::retrieve::request` | Forward retrieve request through the action service. | +| `garage::vehicle::store::request` | Forward store request through the action service. | +| `garage::close` | Dispose bridge screen state and close the display. | + +## Browser Response Events + +| Event | Purpose | +| --- | --- | +| `garage::hydrate` | Initial vehicle and session payload. | +| `garage::sync` | Refreshed vehicle payload. | + +Server action responses are handled by the action service and notification +flow. + +## Mission Setup + +Garage interactions are normally surfaced through the actor menu when nearby +objects have garage variables such as: + +```sqf +_object setVariable ["isGarage", true, true]; +_object setVariable ["garageType", "cars", true]; +``` + +Virtual garage access also requires configured garage locations in mission +config so the preview/spawn position can be resolved. + +## Authoritative State + +The client gathers vehicle context and sends store/retrieve requests. Stored +vehicle state, validation, spawning, removal, and persistence are owned by the +server garage addon and extension. + +## Related Guides + +- [Garage Usage Guide](./GARAGE_USAGE_GUIDE.md) +- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md) +- [Client Notifications Usage Guide](./CLIENT_NOTIFICATIONS_USAGE_GUIDE.md) diff --git a/docs/CLIENT_LOCKER_USAGE_GUIDE.md b/docs/CLIENT_LOCKER_USAGE_GUIDE.md new file mode 100644 index 0000000..dc8d724 --- /dev/null +++ b/docs/CLIENT_LOCKER_USAGE_GUIDE.md @@ -0,0 +1,87 @@ +# Client Locker Usage Guide + +The client locker addon manages personal locker display state, local locker +container behavior, and virtual arsenal unlock state. + +## Repositories + +`forge_client_locker_fnc_initRepository` creates `GVAR(LockerRepository)`. + +`forge_client_locker_fnc_initVARepository` creates `GVAR(VARepository)`. + +Initialize locker state: + +```sqf +GVAR(LockerRepository) call ["init", []]; +GVAR(VARepository) call ["init", []]; +``` + +## Locker Container Flow + +The repository searches mission namespace variables whose names contain +`locker` and refer to objects. For each server/mission locker object, it creates +a local `Box_NATO_Equip_F` at the same position and attaches container event +handlers. + +On container open: + +- the local container is cleared +- cached locker items are inserted into the container +- over-capacity warnings are emitted when the item count is above 25 + +On container close: + +- cargo, nested container items, and weapon attachments are read back +- the new locker map is sent to the server with the override request +- the local repository cache is updated + +## Virtual Arsenal Flow + +The virtual arsenal repository creates a local `FORGE_Locker_Box` and requests +virtual arsenal unlocks from the server. + +As sync data arrives, it applies unlocks through ACE Arsenal: + +| Data key | Client behavior | +| --- | --- | +| `items` | Add virtual items. | +| `weapons` | Add virtual weapons. | +| `magazines` | Add virtual magazines. | +| `backpacks` | Add virtual backpacks. | + +The actor menu opens the virtual locker with: + +```sqf +[FORGE_Locker_Box, player, false] spawn ace_arsenal_fnc_openBox; +``` + +## Server Events + +The client repository sends requests for: + +- locker initialization +- locker save +- locker override after container close +- virtual arsenal initialization +- virtual arsenal save + +The server locker addon and extension own the saved locker and virtual arsenal +state. + +## Mission Setup + +Mission locker objects must be placed into `missionNamespace` with a variable +name containing `locker`. The client creates local interactive containers from +those authoritative mission objects. + +Example: + +```sqf +missionNamespace setVariable ["forge_locker_alpha", _lockerObject, true]; +``` + +## Related Guides + +- [Locker Usage Guide](./LOCKER_USAGE_GUIDE.md) +- [Owned Storage Usage Guide](./OWNED_STORAGE_USAGE_GUIDE.md) +- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md) diff --git a/docs/CLIENT_MAIN_USAGE_GUIDE.md b/docs/CLIENT_MAIN_USAGE_GUIDE.md new file mode 100644 index 0000000..0ac8fbf --- /dev/null +++ b/docs/CLIENT_MAIN_USAGE_GUIDE.md @@ -0,0 +1,48 @@ +# Client Main Usage Guide + +The client `main` addon provides the shared mod identity, version metadata, +CBA settings, and macro foundation used by the Forge client addons. + +## Purpose + +Use `forge_client_main` as the foundation dependency for client addons that +need Forge macros, function naming, settings, or mod-level configuration. + +Feature logic should stay in the owning addon. `main` should remain limited to +shared client configuration and compile infrastructure. + +## Key Files + +| File | Purpose | +| --- | --- | +| `script_mod.hpp` | Client mod identity. | +| `script_version.hpp` | Client mod version values. | +| `script_macros.hpp` | Shared client macros. | +| `CfgSettings.hpp` | Client CBA settings. | +| `config.cpp` | Addon config and mod wiring. | + +## Dependency Pattern + +Feature addons normally depend on `forge_client_main` in their `config.cpp`. + +```cpp +class forge_client_example { + requiredAddons[] = { + "forge_client_main" + }; +}; +``` + +## Usage Notes + +- Put domain UI, repositories, and event handling in feature addons. +- Put reusable browser bridge behavior in `forge_client_common`. +- Put server-only behavior in `arma/server/addons`. +- Keep settings in `CfgSettings.hpp` when they apply to the client mod as a + whole or to a client feature toggle. + +## Related Guides + +- [Client Usage Guide](./CLIENT_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) +- [Development Guide](./DEVELOPMENT_GUIDE.md) diff --git a/docs/CLIENT_NOTIFICATIONS_USAGE_GUIDE.md b/docs/CLIENT_NOTIFICATIONS_USAGE_GUIDE.md new file mode 100644 index 0000000..e102583 --- /dev/null +++ b/docs/CLIENT_NOTIFICATIONS_USAGE_GUIDE.md @@ -0,0 +1,74 @@ +# Client Notifications Usage Guide + +The client notifications addon owns the notification HUD, notification sound, +and local notification service used by Forge client and server modules. + +## Runtime Behavior + +The notification display is created during client initialization. The browser +HUD sends: + +```text +notifications::ready +``` + +When that event is received, `NotificationService` initializes and sends a +startup notification. + +## Create a Notification + +Use the notification service when available: + +```sqf +GVAR(NotificationService) call ["create", [ + "success", + "Title", + "Notification text.", + 4000 +]]; +``` + +Arguments: + +| Argument | Purpose | +| --- | --- | +| `_type` | Notification type, such as `success`, `info`, `warning`, or `error`. | +| `_title` | Notification title. | +| `_content` | Notification body text. | +| `_duration` | Display duration in milliseconds. | + +The service dispatches a browser `forge:notify` custom event. + +## CBA Event Surface + +Other addons can use the client notification event: + +```sqf +["forge_client_notifications_recieveNotification", [ + "warning", + "Garage", + "Vehicle spawn position is blocked.", + 3000 +]] call CBA_fnc_localEvent; +``` + +The event payload is: + +```sqf +[_type, _title, _content, _duration] +``` + +## Usage Rules + +- Use the shared notification service instead of opening separate transient + browser UIs. +- Keep server-driven player feedback short and actionable. +- Treat notification state as transient client UI state. +- Do not use notifications as the only record of durable domain changes. + +## Related Guides + +- [Client Usage Guide](./CLIENT_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) diff --git a/docs/CLIENT_ORG_USAGE_GUIDE.md b/docs/CLIENT_ORG_USAGE_GUIDE.md new file mode 100644 index 0000000..5a5723b --- /dev/null +++ b/docs/CLIENT_ORG_USAGE_GUIDE.md @@ -0,0 +1,106 @@ +# Client Organization Usage Guide + +The client organization addon provides the organization portal UI and browser +bridge for login, registration, membership, invites, credit lines, leave and +disband flows, assets, fleet, and treasury display. + +## Open Organization UI + +```sqf +call forge_client_org_fnc_openUI; +``` + +The UI opens `RscOrg`, loads `ui/_site/index.html`, and routes browser alerts +through `forge_client_org_fnc_handleUIEvents`. + +## Repository and Bridge + +`forge_client_org_fnc_initRepository` caches organization portal state. + +`forge_client_org_fnc_initUIBridge` owns: + +- active browser control tracking +- portal hydrate requests +- create/login response routing +- leave and disband requests +- credit-line assignment requests +- invite, accept invite, and decline invite requests +- targeted browser response events + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `org::ready` | Mark browser ready and request `org::sync`. | +| `org::login::request` | Request portal hydrate as `org::login::success`. | +| `org::create::request` | Validate org name and request creation on server. | +| `org::disband::request` | Request disband on server. | +| `org::leave::request` | Request leave on server. | +| `org::credit::request` | Request credit-line assignment. | +| `org::invite::request` | Request member invite. | +| `org::invite::accept` | Accept invite by org ID. | +| `org::invite::decline` | Decline invite by org ID. | +| `org::close` | Close the display. | + +## Browser Response Events + +| Event | Purpose | +| --- | --- | +| `org::sync` | Full portal sync payload. | +| `org::login::success` | Login hydrate payload. | +| `org::create::success` | Creation hydrate payload. | +| `org::create::failure` | Creation validation or server failure. | +| `org::disband::success` | Requester disband success. | +| `org::disband::failure` | Disband failure. | +| `org::portal::revoked` | Portal state revoked by someone else's disband action. | +| `org::leave::success` | Leave success. | +| `org::leave::failure` | Leave failure. | +| `org::credit::success` | Credit-line request success. | +| `org::credit::failure` | Credit-line request failure. | +| `org::member::creditUpdated` | Targeted member credit-line patch. | +| `org::invite::success` | Invite success. | +| `org::invite::failure` | Invite failure. | +| `org::invite::decision::success` | Invite accept/decline success. | +| `org::invite::decision::failure` | Invite accept/decline failure. | + +## Request Examples + +Create organization request payload: + +```json +{ + "orgName": "Example Logistics" +} +``` + +Credit-line request payload: + +```json +{ + "memberUid": "76561198000000000", + "memberName": "Player Name", + "amount": 2500 +} +``` + +Invite request payload: + +```json +{ + "targetUid": "76561198000000000", + "targetName": "Player Name" +} +``` + +## Authoritative State + +Organization funds, reputation, membership, invites, credit lines, assets, +fleet, and persistence are server-owned. The client portal only displays and +requests changes. + +## Related Guides + +- [Organization Usage Guide](./ORG_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) diff --git a/docs/CLIENT_PHONE_USAGE_GUIDE.md b/docs/CLIENT_PHONE_USAGE_GUIDE.md new file mode 100644 index 0000000..28832a1 --- /dev/null +++ b/docs/CLIENT_PHONE_USAGE_GUIDE.md @@ -0,0 +1,107 @@ +# Client Phone Usage Guide + +The client phone addon provides the in-game phone UI for contacts, SMS +messages, email, and local utility apps such as notes, calendar events, world +clocks, and alarms. + +## Open Phone UI + +```sqf +call forge_client_phone_fnc_openUI; +``` + +The phone UI creates `RscPhone`, loads `ui/_site/index.html`, and routes +browser alerts through `forge_client_phone_fnc_handleUIEvents`. + +## State Ownership + +Contacts, messages, and emails are server-owned and requested through the +server phone addon. + +Local utility app state is stored in `profileNamespace`: + +- notes +- calendar events +- world clocks +- alarms +- theme/preferences + +## Phone Class + +`forge_client_phone_fnc_initClass` creates `GVAR(PhoneClass)`. + +The phone class currently owns local notes, events, and settings helpers. +Contacts, messages, and emails continue to use server-backed request/response +events. + +## Browser Events + +### Session and Preferences + +| Event | Client behavior | +| --- | --- | +| `phone::get::player` | Send player UID to browser with `setPlayerUid`. | +| `phone::get::theme` | Send saved light/dark theme to browser. | +| `phone::set::theme` | Save theme preference to `profileNamespace`. | + +### Contacts + +| Event | Client behavior | +| --- | --- | +| `phone::get::contacts` | Load cached contacts and request server refresh. | +| `phone::refresh::contacts` | Request contacts from server. | +| `phone::add::contact` | Add contact by phone number. | +| `phone::add::contact::by::phone` | Add contact by phone number. | +| `phone::add::contact::by::email` | Add contact by email. | +| `phone::remove::contact` | Remove contact by UID. | + +### Messages + +| Event | Client behavior | +| --- | --- | +| `phone::get::messages` | Request messages from server. | +| `phone::get::message::thread` | Request thread with another UID. | +| `phone::send::message` | Send SMS through server. | +| `phone::mark::message::read` | Mark message read on server. | +| `phone::delete::message` | Delete message on server. | + +### Email + +| Event | Client behavior | +| --- | --- | +| `phone::get::emails` | Request emails from server. | +| `phone::send::email` | Send email through server. | +| `phone::mark::email::read` | Mark email read on server. | +| `phone::delete::email` | Delete email on server. | + +### Local Utility Apps + +| Event | Client behavior | +| --- | --- | +| `phone::get::notes` | Load local notes. | +| `phone::save::note` | Save local note. | +| `phone::delete::note` | Delete local note. | +| `phone::get::events` | Load local calendar events. | +| `phone::save::event` | Save local calendar event. | +| `phone::delete::event` | Delete local calendar event. | +| `phone::get::clocks` | Load local world clocks. | +| `phone::save::clock` | Save local world clock. | +| `phone::delete::clock` | Delete local world clock. | +| `phone::get::alarms` | Load local alarms. | +| `phone::save::alarm` | Save local alarm. | +| `phone::delete::alarm` | Delete local alarm. | +| `phone::toggle::alarm` | Toggle local alarm enabled state. | + +## Usage Rules + +- Send contact, message, and email mutations to the server phone addon. +- Keep local-only utility apps in `profileNamespace` until they are migrated to + server-backed storage. +- Do not treat local phone utility state as shared multiplayer state. +- Validate required UID, phone, email, subject, and message fields before + sending server requests. + +## Related Guides + +- [Phone Usage Guide](./PHONE_USAGE_GUIDE.md) +- [Client Notifications Usage Guide](./CLIENT_NOTIFICATIONS_USAGE_GUIDE.md) diff --git a/docs/CLIENT_STORE_USAGE_GUIDE.md b/docs/CLIENT_STORE_USAGE_GUIDE.md new file mode 100644 index 0000000..3078d3c --- /dev/null +++ b/docs/CLIENT_STORE_USAGE_GUIDE.md @@ -0,0 +1,92 @@ +# Client Store Usage Guide + +The client store addon provides the storefront browser UI for catalog browsing, +category hydration, payment source display, cart handling, and checkout +requests. + +## Open Store UI + +```sqf +call forge_client_store_fnc_openUI; +``` + +The UI opens `RscStore`, loads `ui/_site/index.html`, and routes browser alerts +through `forge_client_store_fnc_handleUIEvents`. + +## Bridge + +`forge_client_store_fnc_initUIBridge` owns: + +- browser control lookup +- store hydrate requests +- category requests +- checkout requests +- category hydrate/failure responses +- checkout success/failure responses +- store config refresh after successful checkout + +Store currently uses its own `StoreUIBridge.receive(...)` browser bridge rather +than the shared `ForgeBridge.receive(...)` delivery used by newer bridges. + +## Browser Events + +| Event | Client behavior | +| --- | --- | +| `store::ready` | Request store hydrate from the server. | +| `store::category::request` | Request catalog items for a category. | +| `store::checkout::request` | Forward checkout JSON to the server. | +| `store::close` | Close the display. | + +## Browser Response Events + +| Event | Purpose | +| --- | --- | +| `store::hydrate` | Initial storefront/session/config payload. | +| `store::config::hydrate` | Refreshed payment/source config. | +| `store::category::hydrate` | Category catalog payload. | +| `store::category::failure` | Category request failure. | +| `store::checkout::success` | Checkout success payload. | +| `store::checkout::failure` | Checkout failure payload. | + +## Category Requests + +Category requests require a non-empty category value. + +```json +{ + "category": "weapons" +} +``` + +The client lowercases the category before forwarding it to the server store +addon. + +## Checkout Requests + +Checkout requests send a serialized checkout payload: + +```json +{ + "checkoutJson": "{\"items\":[],\"paymentSource\":\"cash\"}" +} +``` + +The client only forwards the checkout data. The server store addon and +extension validate prices, inventory grants, payment source authorization, and +integration with bank, organization, locker, and garage state. + +After a successful checkout, the client asks the server for a fresh store config +payload so payment-source balances and permissions stay current. + +## Authoritative State + +Catalog data, prices, checkout validation, money movement, organization funds, +credit lines, locker grants, garage grants, and persistence are server-owned. + +## Related Guides + +- [Store Usage Guide](./STORE_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md) +- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) diff --git a/docs/CLIENT_USAGE_GUIDE.md b/docs/CLIENT_USAGE_GUIDE.md new file mode 100644 index 0000000..23f74f1 --- /dev/null +++ b/docs/CLIENT_USAGE_GUIDE.md @@ -0,0 +1,125 @@ +# Client Usage Guide + +Forge Client contains the Arma client-side addons that open player interfaces, +handle browser events, cache client-visible state, and forward authoritative +requests to the server addons. + +Use this guide as the entry point for client-side integration. Domain data, +validation, persistence, rewards, ownership, and checkout behavior remain +server-side responsibilities. + +## Client Responsibilities + +- Open Arma displays and `CT_WEBBROWSER` controls. +- Load browser UI assets from each addon's `ui/_site` folder. +- Receive browser alerts through `JSDialog` handlers. +- Translate browser events into local actions or CBA server events. +- Cache display state in client repositories. +- Push server responses back into browser UIs with `ExecJS`. +- Provide local-only utility state where the feature is intentionally local. + +## Authoritative Boundaries + +Client repositories are view state. They are useful for rendering, local UI +decisions, and short-lived session behavior, but they should not be treated as +durable state. + +Authoritative state lives in: + +- server SQF addons for mission and player workflow ownership +- the `forge_server` extension for durable and hot-state domain logic +- SurrealDB where the extension persists durable domain records + +## Common Runtime Flow + +Most browser-backed client addons follow this shape: + +1. The addon creates a display, finds a browser control, and registers a + `JSDialog` event handler. +2. The browser loads an HTML entrypoint from `ui/_site`. +3. The browser sends JSON alerts with an `event` name and `data` payload. +4. `fnc_handleUIEvents.sqf` parses the alert and routes the event. +5. A bridge object or repository sends a CBA server event when server data is + needed. +6. Server responses are caught in `XEH_postInitClient.sqf`. +7. The bridge sends browser update events back through `ExecJS`. + +Browser alert payload: + +```json +{ + "event": "module::action", + "data": {} +} +``` + +## Open UI Entry Points + +| UI | Entry point | +| --- | --- | +| Actor menu | `call forge_client_actor_fnc_openUI;` | +| Bank | `call forge_client_bank_fnc_openUI;` | +| ATM | `[true] call forge_client_bank_fnc_openUI;` | +| CAD | `call forge_client_cad_fnc_openUI;` | +| Garage | `call forge_client_garage_fnc_openUI;` | +| Virtual garage | `call forge_client_garage_fnc_openVG;` | +| Organization portal | `call forge_client_org_fnc_openUI;` | +| Phone | `call forge_client_phone_fnc_openUI;` | +| Store | `call forge_client_store_fnc_openUI;` | + +Notifications are normally opened during client initialization and then updated +through the notification event/service. + +## Addon Guides + +- [Client Main Usage Guide](./CLIENT_MAIN_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) +- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client CAD Usage Guide](./CLIENT_CAD_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) +- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md) +- [Client Notifications Usage Guide](./CLIENT_NOTIFICATIONS_USAGE_GUIDE.md) +- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md) +- [Client Phone Usage Guide](./CLIENT_PHONE_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) + +## Extension Calls + +Client addons should usually call server SQF events, not the `forge_server` +extension directly. The server addon owns validation context and converts the +request into extension commands. + +Example: + +```sqf +[SRPC(bank,requestDeposit), [getPlayerUID player, 100]] call CFUNC(serverEvent); +``` + +Direct extension calls from client code bypass server authorization boundaries +and should be avoided. + +## Browser Bridge Notes + +`forge_client_common_fnc_initWebUIBridge` provides reusable bridge and screen +objects for newer browser UIs. It queues outbound events until a browser screen +is ready, then delivers payloads through: + +```sqf +_control ctrlWebBrowserAction ["ExecJS", format ["ForgeBridge.receive(%1)", _json]]; +``` + +Feature addons still own their event names, request payloads, and response +mapping. + +## Development Checklist + +- Keep feature-specific behavior in the owning addon. +- Send authoritative changes to the server addon. +- Use namespaced browser events such as `bank::deposit::request`. +- Treat `profileNamespace` as local player preference or utility state only. +- Make browser-ready events request the current server state before rendering + stale data. +- Queue or ignore bridge responses when the display is closed. +- Keep mission object setup on the mission/server side and client display logic + on the client side. diff --git a/docs/MODULE_REFERENCE.md b/docs/MODULE_REFERENCE.md index 1557846..eb50fc8 100644 --- a/docs/MODULE_REFERENCE.md +++ b/docs/MODULE_REFERENCE.md @@ -33,7 +33,7 @@ docs/ Framework-level documentation | Owned Garage | Organization or owner-scoped vehicle unlock storage. | via garage/org UI | server extension only | `lib/models/src/v_garage.rs`, `lib/services/src/v_garage.rs` | `owned:garage:*` | | Owned Locker | Organization or owner-scoped arsenal unlock storage. | via locker/org UI | server extension only | `lib/models/src/v_locker.rs`, `lib/services/src/v_locker.rs` | `owned:locker:*` | -Guides: +Server and extension guides: [Actor](./ACTOR_USAGE_GUIDE.md), [Bank](./BANK_USAGE_GUIDE.md), [CAD](./CAD_USAGE_GUIDE.md), @@ -45,6 +45,20 @@ Guides: [Store](./STORE_USAGE_GUIDE.md), [Task](./TASK_USAGE_GUIDE.md). +Client guides: +[Client Overview](./CLIENT_USAGE_GUIDE.md), +[Main](./CLIENT_MAIN_USAGE_GUIDE.md), +[Common](./CLIENT_COMMON_USAGE_GUIDE.md), +[Actor](./CLIENT_ACTOR_USAGE_GUIDE.md), +[Bank](./CLIENT_BANK_USAGE_GUIDE.md), +[CAD](./CLIENT_CAD_USAGE_GUIDE.md), +[Garage](./CLIENT_GARAGE_USAGE_GUIDE.md), +[Locker](./CLIENT_LOCKER_USAGE_GUIDE.md), +[Notifications](./CLIENT_NOTIFICATIONS_USAGE_GUIDE.md), +[Organization](./CLIENT_ORG_USAGE_GUIDE.md), +[Phone](./CLIENT_PHONE_USAGE_GUIDE.md), +[Store](./CLIENT_STORE_USAGE_GUIDE.md). + ## Infrastructure Modules | Module | Purpose | Location | diff --git a/docs/README.md b/docs/README.md index 641e9ba..81c25a7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ collects framework-level documentation for those pieces. - [Development Guide](./DEVELOPMENT_GUIDE.md): how to add or change a module without breaking the framework boundaries. -## Existing Usage Guides +## Server and Extension Usage Guides - [Actor Usage Guide](./ACTOR_USAGE_GUIDE.md) - [Bank Usage Guide](./BANK_USAGE_GUIDE.md) @@ -27,6 +27,21 @@ collects framework-level documentation for those pieces. - [Store Usage Guide](./STORE_USAGE_GUIDE.md) - [Task Usage Guide](./TASK_USAGE_GUIDE.md) +## Client Usage Guides + +- [Client Usage Guide](./CLIENT_USAGE_GUIDE.md) +- [Client Main Usage Guide](./CLIENT_MAIN_USAGE_GUIDE.md) +- [Client Common Usage Guide](./CLIENT_COMMON_USAGE_GUIDE.md) +- [Client Actor Usage Guide](./CLIENT_ACTOR_USAGE_GUIDE.md) +- [Client Bank Usage Guide](./CLIENT_BANK_USAGE_GUIDE.md) +- [Client CAD Usage Guide](./CLIENT_CAD_USAGE_GUIDE.md) +- [Client Garage Usage Guide](./CLIENT_GARAGE_USAGE_GUIDE.md) +- [Client Locker Usage Guide](./CLIENT_LOCKER_USAGE_GUIDE.md) +- [Client Notifications Usage Guide](./CLIENT_NOTIFICATIONS_USAGE_GUIDE.md) +- [Client Organization Usage Guide](./CLIENT_ORG_USAGE_GUIDE.md) +- [Client Phone Usage Guide](./CLIENT_PHONE_USAGE_GUIDE.md) +- [Client Store Usage Guide](./CLIENT_STORE_USAGE_GUIDE.md) + ## Related Documentation - [Server Extension Docs](../arma/server/docs/README.md)