IDSolutions/forge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation Update & Task Module Refactor #10

Merged
J.Schmidt92 merged 8 commits from master into feature/surrealdb-storage 2026-04-18 20:27:35 -05:00
Conversation 0 Commits 8 Files Changed 48 +1509 -173
28 changed files with 1509 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 89169f1e84 - Show all commits

56
arma/client/README.md
View File

@ -1,30 +1,46 @@
<h1 align="center">Forge Client</h1>
<p align="center">
<a href="https://gitea.innovativedevsolutions.org/IDSolutions/forge/releases/latest"><img src="https://img.shields.io/gitea/v/release/IDSolutions/forge?gitea_url=https%3A%2F%2Fgitea.innovativedevsolutions.org&label=Version" alt="Version"></a>
<a href="https://gitea.innovativedevsolutions.org/IDSolutions/forge/issues"><img src="https://img.shields.io/gitea/issues/open/IDSolutions/forge?gitea_url=https%3A%2F%2Fgitea.innovativedevsolutions.org&label=Issues" alt="Issues"></a>
<!-- <a href="https://steamcommunity.com/sharedfiles/filedetails/?id=MOD_ID"><img src="https://img.shields.io/steam/downloads/MOD_ID.svg?&label=Downloads" alt="Downloads"></a> -->
<a href="https://gitea.innovativedevsolutions.org/IDSolutions/forge/src/branch/master/arma/server/LICENSE.md"><img src="https://img.shields.io/badge/License-APL%20SA-red?label=License" alt="License"></a>
<br>
<img src="https://img.shields.io/github/v/release/brettmayson/hemtt?label=HEMTT" alt="HEMTT">
<img src="https://img.shields.io/github/v/release/cbateam/cba_a3?label=CBA%20A3" alt="CBA A3">
</p>
# Forge Client
<p align="center">
<b>Requires the latest version of <a href="https://github.com/CBATeam/CBA_A3/releases/latest">CBA A3</a></b>
</p>
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).

29
arma/client/addons/actor/README.md
View File

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

35
arma/client/addons/bank/README.md
View File

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

37
arma/client/addons/cad/README.md Normal file
View File

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

19
arma/client/addons/common/README.md
View File

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

36
arma/client/addons/garage/README.md
View File

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

28
arma/client/addons/locker/README.md
View File

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

19
arma/client/addons/main/README.md
View File

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

28
arma/client/addons/notifications/README.md
View File

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

108
arma/client/addons/org/README.md
View File

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

31
arma/client/addons/phone/README.md
View File

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

29
arma/client/addons/store/README.md
View File

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

91
arma/client/docs/README.md
View File

@ -1,54 +1,47 @@
<!-- If you want to make changes to this README, you need to also modify the README.md in the docs folder as well -->
# Forge Client Documentation
<h1 align="center">forge-client</h1>
<p align="center">
<a href="https://github.com/IDSolutions/MOD_REPO/releases/latest">
<img src="https://img.shields.io/badge/Version-0.0.0-blue?style=flat-square" alt="forge-client Version">
</a>
<a href="https://github.com/IDSolutions/MOD_REPO/issues">
<img src="https://img.shields.io/github/issues-raw/IDSolutions/MOD_REPO.svg?style=flat-square&label=Issues" alt="forge-client Issues">
</a>
<a href="https://steamcommunity.com/sharedfiles/filedetails/?id=MOD_ID">
<img src="https://img.shields.io/steam/downloads/MOD_ID.svg?style=flat-square&label=Downloads" alt="forge-client Downloads">
</a>
<a href="https://github.com/IDSolutions/MOD_REPO/blob/master/LICENSE">
<img src="https://img.shields.io/badge/License-APL ND-red?style=flat-square" alt="forge-client License">
</a>
<br>
<img src="https://img.shields.io/github/actions/workflow/status/IDSolutions/MOD_REPO/check.yml?style=flat-square&label=HEMTT" alt="HEMTT">
</p>
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.
<p align="center">
<b>Requires the latest version of <a href="https://github.com/CBATeam/CBA_A3/releases/latest">CBA A3</a></b>
</p>
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)

10
arma/client/extra/example_addon/README.md
View File

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

98
docs/CLIENT_ACTOR_USAGE_GUIDE.md Normal file
View File

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

84
docs/CLIENT_BANK_USAGE_GUIDE.md Normal file
View File

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

100
docs/CLIENT_CAD_USAGE_GUIDE.md Normal file
View File

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

92
docs/CLIENT_COMMON_USAGE_GUIDE.md Normal file
View File

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

80
docs/CLIENT_GARAGE_USAGE_GUIDE.md Normal file
View File

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

87
docs/CLIENT_LOCKER_USAGE_GUIDE.md Normal file
View File

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

48
docs/CLIENT_MAIN_USAGE_GUIDE.md Normal file
View File

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

74
docs/CLIENT_NOTIFICATIONS_USAGE_GUIDE.md Normal file
View File

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

106
docs/CLIENT_ORG_USAGE_GUIDE.md Normal file
View File

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

107
docs/CLIENT_PHONE_USAGE_GUIDE.md Normal file
View File

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

92
docs/CLIENT_STORE_USAGE_GUIDE.md Normal file
View File

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

125
docs/CLIENT_USAGE_GUIDE.md Normal file
View File

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

16
docs/MODULE_REFERENCE.md
View File

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

17
docs/README.md
View File

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