a4d5c2fd4d
- Added frontmatter to various markdown files for better metadata handling. - Updated site URLs in configuration files for consistency. - Improved content organization and clarity in getting started, server extension, and client addon guides.
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Framework Architecture
|
|
|
|
Forge is organized around domain modules. A domain usually has SQF addon
|
|
entry points, Rust models, repository traits, service logic, extension command
|
|
handlers, and optional browser UI.
|
|
|
|
## Runtime Flow
|
|
|
|
|
|
|
|
```text
|
|
Arma client UI or SQF action
|
|
-> client addon bridge
|
|
-> server addon function
|
|
-> forge_server callExtension command
|
|
-> extension command group
|
|
-> forge-services domain service
|
|
-> forge-repositories trait
|
|
-> SurrealDB repository implementation
|
|
-> SurrealDB
|
|
```
|
|
|
|
For small payloads, server SQF calls `forge_server` directly through the
|
|
extension bridge. For large payloads, `arma/server/addons/extension` stages
|
|
request and response chunks through the extension transport module.
|
|
|
|
## Main Layers
|
|
|
|
### Client Addons
|
|
|
|
Client addons live under `arma/client/addons`. They own local player UX,
|
|
keybinds, browser UI dialogs, and UI-to-SQF event handling. When a client needs
|
|
durable or authoritative state, it routes work to the matching server addon
|
|
instead of touching persistence directly.
|
|
|
|
### Server Addons
|
|
|
|
Server addons live under `arma/server/addons`. They own server-side SQF
|
|
initialization, game-object integration, validation near the Arma runtime, and
|
|
calls into the Rust extension. The `extension` addon is the shared bridge for
|
|
`callExtension` and transport handling.
|
|
|
|
### Rust Extension
|
|
|
|
The server extension lives under `arma/server/extension`. It registers the
|
|
`forge_server` command groups, loads configuration, initializes SurrealDB, and
|
|
maps SQF command inputs into service calls.
|
|
|
|
The extension should stay thin:
|
|
|
|
- Parse and validate command arguments that arrive from SQF.
|
|
- Resolve Arma-specific context such as player UID when required.
|
|
- Call the matching service.
|
|
- Serialize the service result back to JSON or a simple string.
|
|
|
|
### Shared Rust Crates
|
|
|
|
The `lib` workspace contains reusable Rust crates:
|
|
|
|
- `forge-models`: shared domain structs and serialization rules.
|
|
- `forge-repositories`: storage-agnostic repository traits and in-memory
|
|
implementations used by tests and hot-state services.
|
|
- `forge-services`: domain behavior, validation, and mutation workflows.
|
|
- `forge-shared`: cross-crate helpers.
|
|
|
|
### Persistence
|
|
|
|
Durable storage is SurrealDB. Schema modules live under
|
|
`arma/server/extension/src/schema`, and concrete SurrealDB repository
|
|
implementations live under `arma/server/extension/src/storage`.
|
|
|
|
Repository traits stay in `lib/repositories` so service logic remains testable
|
|
without a database.
|
|
|
|
## Hot State
|
|
|
|
Several domains have `hot` command groups. Hot state keeps a runtime copy of
|
|
frequently accessed data in memory, then saves it back to durable storage when
|
|
requested. This is useful for player state that changes often during a session.
|
|
|
|
Typical hot-state flow:
|
|
|
|
```text
|
|
actor:hot:init
|
|
actor:hot:get
|
|
actor:hot:override
|
|
actor:hot:save
|
|
actor:hot:remove
|
|
```
|
|
|
|
Use hot state for session workflows. Use normal domain commands for direct
|
|
durable CRUD operations.
|
|
|
|
## Transport Layer
|
|
|
|
The transport layer exists because Arma extension calls have practical payload
|
|
size limits. It provides chunked request and response handling while still
|
|
routing to the same domain command groups.
|
|
|
|
Common direct command:
|
|
|
|
```sqf
|
|
"forge_server" callExtension ["status", []];
|
|
```
|
|
|
|
Common transport path:
|
|
|
|
```text
|
|
server addon fnc_extCall
|
|
-> transport:request:append
|
|
-> transport:invoke_stored
|
|
-> transport:response:get
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The server extension reads `config.toml` next to the extension DLL. The current
|
|
persistence section is:
|
|
|
|
```toml
|
|
[surreal]
|
|
endpoint = "127.0.0.1:8000"
|
|
namespace = "forge"
|
|
database = "main"
|
|
username = "root"
|
|
password = "root"
|
|
connect_timeout_ms = 5000
|
|
```
|
|
|
|
For install links and role-based setup guidance, see
|
|
[SurrealDB Setup](./surrealdb-setup.md).
|
|
|
|
Check persistence readiness before issuing commands that require storage:
|
|
|
|
```sqf
|
|
"forge_server" callExtension ["status", []];
|
|
"forge_server" callExtension ["surreal:status", []];
|
|
```
|