Getting Started

# Module Reference

This reference lists the main Forge modules and where each layer lives.

# Module Reference

This reference lists the main Forge modules and where each layer lives.

## Directory Map

    arma/client/addons/      Client-side Arma addons and browser UIs
    arma/server/addons/      Server-side Arma addons and extension bridge
    arma/server/extension/   Rust arma-rs extension and SurrealDB adapters
    bin/icom/                Interprocess communication helper
    lib/models/              Shared domain data models
    lib/repositories/        Repository traits and in-memory stores
    lib/services/            Domain services and workflow logic
    lib/shared/              Cross-crate helpers
    tools/                   Web UI build tooling
    docs/                    Framework-level documentation

## Gameplay Domains

Domain | Purpose | Client addon | Server addon | Service/model layer | Extension group
--- | --- | --- | --- | --- | ---
Actor | Player identity, loadout, position, status, contact identifiers, and persistent character data. | `arma/client/addons/actor` | `arma/server/addons/actor` | `lib/models/src/actor.rs`, `lib/services/src/actor.rs` | `actor:*`
Bank | Player accounts, cash/bank balances, PIN validation, transfers, checkout charging, and transaction context. | `arma/client/addons/bank` | `arma/server/addons/bank` | `lib/models/src/bank.rs`, `lib/services/src/bank.rs` | `bank:*`, `bank:hot:*`
CAD | Dispatch requests, assignments, orders, activity stream, profiles, groups, and hydrated dispatcher views. | `arma/client/addons/cad` | `arma/server/addons/cad` | `lib/models/src/cad.rs`, `lib/services/src/cad.rs` | `cad:*`
Garage | Player vehicle storage with plate IDs, fuel, damage, and hit point state. | `arma/client/addons/garage` | `arma/server/addons/garage` | `lib/models/src/garage.rs`, `lib/services/src/garage.rs` | `garage:*`, `garage:hot:*`
Locker | Player item storage keyed by classname with category and amount. | `arma/client/addons/locker` | `arma/server/addons/locker` | `lib/models/src/locker.rs`, `lib/services/src/locker.rs` | `locker:*`, `locker:hot:*`
Organization | Player organizations, membership, treasury, credit lines, shared assets, and fleet data. | `arma/client/addons/org` | `arma/server/addons/org` | `lib/models/src/org.rs`, `lib/services/src/org.rs` | `org:*`, `org:hot:*`
Phone | Contacts, messages, and email state. | `arma/client/addons/phone` | `arma/server/addons/phone` | `lib/models/src/phone.rs`, `lib/services/src/phone.rs` | `phone:*`
Store | Storefront entity setup, catalog hydration, checkout workflows, and checkout charging integration. | `arma/client/addons/store` | `arma/server/addons/store` | `lib/models/src/store.rs`, `lib/services/src/store.rs` | `store:checkout`
Task | Server-owned mission/task flows, catalog, ownership, status, participant tracking, rewards, and defuse counters. | none | `arma/server/addons/task` | `lib/models/src/task.rs`, `lib/services/src/task.rs` | `task:*`
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:*`

Server and extension guides: Actor, Bank, CAD, Economy, Garage, Locker, Organization, Owned Storage, Phone, Store, Task.

Client guides: Client Overview, Main, Common, Actor, Bank, CAD, Garage, Locker, Notifications, Organization, Phone, Store.

## Infrastructure Modules

Module | Purpose | Location
--- | --- | ---
`common` | Shared SQF helpers, base stores, utility functions, and shared UI bridge pieces. | `arma/client/addons/common`, `arma/server/addons/common`
`extension` | Server SQF bridge around `forge_server` extension calls and chunked transport. | `arma/server/addons/extension`
`main` | Mod-level configuration, pre-init wiring, and server/client startup glue. | `arma/client/addons/main`, `arma/server/addons/main`
`economy` | Server-side fuel, medical, and service economy helpers. Fuel and repair charge organization hot state; medical charges player bank/cash first, then organization funds with repayable member debt when personal funds cannot cover the bill. | `arma/server/addons/economy`
`notifications` | Client notification UI, sounds, and UI event handling. | `arma/client/addons/notifications`
`icom` | Rust helper for interprocess communication and event broadcasting. | `bin/icom`, `arma/server/extension/src/icom.rs`
`terrain` | Extension-side terrain export helper. | `arma/server/extension/src/terrain.rs`
`transport` | Chunked request/response handling for large extension payloads. | `arma/server/extension/src/transport.rs`
`surreal` | SurrealDB connection lifecycle and status reporting. | `arma/server/extension/src/surreal.rs`

## Extension Command Groups

Commands are invoked with:

    "forge_server" callExtension ["group:command", [_arg1, _arg2]];

Nested groups use additional `:` separators, for example `bank:hot:deposit`.

### Core

Command | Purpose
--- | ---
`version` | Return the extension version string.
`status` | Return SurrealDB connection state.
`surreal:status` | Return SurrealDB connection state directly from the Surreal module.

### Actor

Command | Purpose
--- | ---
`actor:get` | Fetch actor data for a resolved player UID.
`actor:create` | Create actor data from JSON.
`actor:update` | Apply actor JSON updates.
`actor:exists` | Return `true` or `false`.
`actor:delete` | Delete actor data.
`actor:hot:init`, `actor:hot:get`, `actor:hot:keys`, `actor:hot:override`, `actor:hot:save`, `actor:hot:remove` | Manage actor hot state.

See Actor Usage Guide for examples.

### Bank

Command | Purpose
--- | ---
`bank:get`, `bank:create`, `bank:update`, `bank:exists`, `bank:delete` | Durable bank CRUD.
`bank:hot:init`, `bank:hot:get`, `bank:hot:override`, `bank:hot:patch`, `bank:hot:save`, `bank:hot:remove` | Manage bank hot state.
`bank:hot:deposit`, `bank:hot:withdraw`, `bank:hot:deposit_earnings`, `bank:hot:transfer` | Mutate hot bank balances with operation context.
`bank:hot:charge_checkout` | Charge a checkout against hot bank state.
`bank:hot:validate_pin` | Validate a PIN for bank operations.

See Bank Usage Guide for examples.

### Garage

Command | Purpose
--- | ---
`garage:create`, `garage:get`, `garage:add`, `garage:update`, `garage:patch`, `garage:remove`, `garage:delete`, `garage:exists` | Durable player garage operations.
`garage:hot:init`, `garage:hot:get`, `garage:hot:override`, `garage:hot:add`, `garage:hot:remove_vehicle`, `garage:hot:save`, `garage:hot:remove` | Manage player garage hot state.

See Garage Usage Guide for examples.

### Locker

Command | Purpose
--- | ---
`locker:create`, `locker:get`, `locker:add`, `locker:update`, `locker:patch`, `locker:remove`, `locker:delete`, `locker:exists` | Durable player locker operations.
`locker:hot:init`, `locker:hot:get`, `locker:hot:override`, `locker:hot:save`, `locker:hot:remove` | Manage player locker hot state.

See Locker Usage Guide for examples.

### Organization

Command | Purpose
--- | ---
`org:get`, `org:create`, `org:update`, `org:exists`, `org:delete` | Durable organization CRUD.
`org:assets:get`, `org:assets:update` | Manage organization assets.
`org:fleet:get`, `org:fleet:update` | Manage organization fleet entries.
`org:members:get`, `org:members:add`, `org:members:remove` | Manage organization membership.
`org:hot:*` | Runtime organization workflows including registration, invites, credit lines, checkout charging, assets, fleet, leave, disband, save, and remove.

See Org Usage Guide for examples.

### Phone

Command | Purpose
--- | ---
`phone:init` | Initialize phone state for a UID.
`phone:contacts:list`, `phone:contacts:add`, `phone:contacts:remove` | Manage contacts.
`phone:messages:list`, `phone:messages:thread`, `phone:messages:send`, `phone:messages:mark_read`, `phone:messages:delete` | Manage messages.
`phone:emails:list`, `phone:emails:send`, `phone:emails:mark_read`, `phone:emails:delete` | Manage emails.
`phone:remove` | Remove phone state for a UID.

See Phone Usage Guide for examples.

### CAD

Command Group | Purpose
--- | ---
`cad:activity:append`, `cad:activity:recent` | Append and read recent activity.
`cad:assignments:list`, `cad:assignments:assign`, `cad:assignments:acknowledge`, `cad:assignments:decline`, `cad:assignments:upsert`, `cad:assignments:delete` | Manage dispatch assignments.
`cad:orders:list`, `cad:orders:create`, `cad:orders:create_from_context`, `cad:orders:close`, `cad:orders:upsert`, `cad:orders:delete` | Manage orders.
`cad:requests:list`, `cad:requests:submit`, `cad:requests:submit_from_context`, `cad:requests:close`, `cad:requests:upsert`, `cad:requests:delete` | Manage requests.
`cad:profiles:list`, `cad:profiles:update_from_context`, `cad:profiles:upsert`, `cad:profiles:delete` | Manage profiles.
`cad:groups:build` | Build grouped CAD state.
`cad:view:hydrate` | Build the dispatcher view model.

See CAD Usage Guide for examples.

### Task

Command Group | Purpose
--- | ---
`task:reset` | Reset task state.
`task:catalog:active`, `task:catalog:get`, `task:catalog:upsert`, `task:catalog:delete` | Manage task catalog entries.
`task:ownership:bind`, `task:ownership:release`, `task:ownership:accept`, `task:ownership:reward_context` | Manage task ownership and rewards.
`task:status:set`, `task:status:get`, `task:status:clear` | Manage task status.
`task:defuse:increment`, `task:defuse:get` | Manage defuse counters.
`task:clear` | Clear task state.

See Task Usage Guide for examples.

### Owned Storage

Command Group | Purpose
--- | ---
`owned:garage:create`, `owned:garage:fetch`, `owned:garage:get`, `owned:garage:add`, `owned:garage:remove`, `owned:garage:delete`, `owned:garage:exists` | Owner-scoped vehicle storage.
`owned:garage:hot:*` | Owner-scoped vehicle hot state.
`owned:locker:create`, `owned:locker:fetch`, `owned:locker:get`, `owned:locker:add`, `owned:locker:remove`, `owned:locker:delete`, `owned:locker:exists` | Owner-scoped item storage.
`owned:locker:hot:*` | Owner-scoped item hot state.

See Owned Storage Usage Guide for examples.

### Other Extension Groups

Command Group | Purpose
--- | ---
`store:checkout` | Run store checkout behavior.
`icom:connect`, `icom:broadcast`, `icom:send_event` | ICom connection and event forwarding.
`terrain:exportSVG` | Export terrain data as SVG.
`transport:invoke`, `transport:invoke_stored` | Invoke commands through transport.
`transport:request:append`, `transport:request:clear` | Manage stored request chunks.
`transport:response:get`, `transport:response:clear` | Manage stored response chunks.

## Rust Crates

Crate | Role
--- | ---
`forge-models` | Domain models and validation. Keep these serializable and free of persistence details.
`forge-repositories` | Repository traits and in-memory implementations. Keep these storage-agnostic.
`forge-services` | Business rules and workflows. Depend on repository traits, not concrete databases.
`forge-shared` | Cross-crate helpers. Keep dependencies light.
`forge-server` | Arma extension crate. Owns command registration, SurrealDB runtime wiring, and concrete storage adapters.
`forge-icom` | ICom helper binary and client library.

Edit this page or Report an issue

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.

Development Guide

This guide covers the usual path for adding or changing a Forge module.