Forge is a high-performance, production-ready framework for Arma 3 persistent game servers, built with Rust and Redis for optimal performance and reliability.

Overview

Forge provides a complete solution for managing persistent player data, organizations, and game state in Arma 3 multiplayer environments. It combines the performance of Rust with the flexibility of Redis to deliver sub-millisecond response times while maintaining data consistency across server restarts.

Key Features

🚀 High Performance: Sub-millisecond data access through intelligent caching
🔒 Data Integrity: Strict validation and type safety at every layer
🏗️ Clean Architecture: Layered design following SOLID principles
📦 Modular Design: Easy to extend with new entities and features
🔄 Real-time Sync: Automatic state synchronization across all clients
💾 Persistent Storage: Redis-backed storage with automatic failover
🧪 Testable: Mock-friendly architecture for comprehensive testing

Architecture

Forge follows a layered architecture pattern:

graph TD
    Extension[Extension Layer<br/>ArmA 3 Interface <---> Rust]
    Services[Services Layer<br/>#40;Business Logic#41;]
    Repositories[Repositories Layer<br/>#40;Data Persistence#41;]
    Models[Models Layer<br/>#40;Data Structures & Validation#41;]

    Extension --> Services
    Services --> Repositories
    Repositories --> Models

Communication Flow:

Clients → Use events (CBA_Events) to communicate with server
Server → Calls Rust extension via callExtension
Extension → Manages Redis connection pool and data operations

For detailed architecture information, see Diagram.

Project Structure

forge/
├── arma/
│   ├── client/                 # Client-side SQF mod
│   │   ├── addons/
│   │   │   ├── main/           # Core initialization & config
│   │   │   ├── common/         # Shared utilities & helpers
│   │   │   ├── actor/          # Actor/player UI, class & events
│   │   │   ├── org/            # Organization UI, class & events
│   │   │   └── bank/           # Banking UI, class & events
│   │   ├── include/            # Header files
│   │   └── tools/              # Build tools
│   ├── server/
│   │   ├── addons/
│   │   │   ├── main/           # Core initialization & config
│   │   │   ├── common/         # Shared utilities & helpers
│   │   │   ├── actor/          # Actor/player Registry, Store & events
│   │   │   └── org/            # Organization Registry, Store & events
│   │   ├── include/            # Header files
│   │   ├── tools/              # Build tools
│   │   └── extension/          # Rust extension (Arma 3 interface)
│   │       ├── src/
│   │       │   ├── actor.rs    # Actor/player commands
│   │       │   ├── org.rs      # Organization commands
│   │       │   ├── redis/      # Redis operations module
│   │       │   └── adapters/   # Repository adapters
│   │       └── README.md
├── lib/
│   ├── models/                 # Data structures & validation
│   ├── repositories/           # Data persistence layer
│   ├── services/               # Business logic layer
│   ├── shared/                 # Common utilities & traits
│   └── README.md
└── FORGE_Architecture_Diagram.md

Quick Start

Prerequisites

Rust 1.70+ with cargo
Redis 6.0+
HEMTT

Clone the repository from Gitea
Install HEMTT The latest version of HEMTT can be installed by running:

winget install hemtt

Coding Guidelines

This mod follows the same coding guidelines as the ACE3 mod, which can be found here.

Building the Extension

# Build for release
cargo build --release

# The compiled extension will be at:
# target/release/forge_server.dll (Windows)
# target/release/forge_server.so (Linux)

Configuration

Create @forge_server/config.toml:

[redis]
host = "127.0.0.1"
port = 6379
password = ""  # Optional
max_connections = 10
min_connections = 2
idle_timeout = 300

SQF Usage

// Create an actor
private _data = createHashMapFromArray [
    ["name", "John Doe"],
    ["bank", 1000],
    ["level", 1]
];
private _result = "forge_server" callExtension ["actor:create", [getPlayerUID player, toJSON _data]];

// Get actor data
private _result = "forge_server" callExtension ["actor:get", [getPlayerUID player]];
private _actorData = fromJSON (_result select 0);

// Update actor
private _update = createHashMapFromArray [["bank", 1500]];
"forge_server" callExtension ["actor:update", [getPlayerUID player, toJSON _update]];

Core Modules

Models

Defines strict data structures with built-in validation:

Actor: Player data (stats, inventory, position)
Org: Organization/clan data (members, roles, metadata)

Documentation

Repositories

Manages data persistence with Redis:

Hash-based storage for structured data
Set-based storage for collections
Generic over Redis client implementations

Documentation

Services

Implements business logic and orchestration:

Get-or-create patterns
Data validation and transformation
Complex workflows

Documentation

Extension

Arma 3 interface layer:

Command routing and parsing
Session management
Error handling and logging

Documentation

Client Mod

Client-side SQF addon that provides:

UI Components: Player interfaces for inventory, organizations, banking
Event Handlers: CBA event listeners for server communication
Optimistic Caching: Local data caching for instant UI updates
State Management: Client-side state synchronization
Input Validation: Client-side validation before server requests

The client mod communicates with the server using CBA Events, ensuring:

No direct extension calls from clients (security)
Event-driven architecture for scalability
Automatic state synchronization across all clients
Reduced server load through client-side caching

Available Commands

Actor Commands

Command	Description
`actor:get`	Retrieve actor data by UID
`actor:create`	Create a new actor
`actor:update`	Update actor fields
`actor:exists`	Check if actor exists
`actor:delete`	Delete actor data

Organization Commands

Command	Description
`org:get`	Retrieve organization data
`org:create`	Create a new organization
`org:update`	Update organization fields
`org:exists`	Check if organization exists
`org:delete`	Delete organization
`org:add_member`	Add member to organization
`org:remove_member`	Remove member from organization
`org:get_members`	Get all organization members

Redis Operations

Direct Redis operations for advanced use cases:

Common: Key-value operations (set, get, incr, decr, del)
Hash: Structured data (hset, hget, hgetall, hdel)
List: Ordered collections (lpush, rpush, lrange, lpop, rpop)
Set: Unique collections (sadd, smembers, srem, sismember)

Documentation

Performance

Hot Cache (Server): < 1ms (HashMap lookup)
Cold Storage (Redis): 1-5ms (Network + Redis query)
Cache Hit Ratio: ~95% for active players
Memory Usage: ~1KB per active player (server), ~2KB per player (Redis)

Contributing

We welcome contributions! Please see the contributing guides for each layer:

Development Workflow

Define Model: Create data structure with validation
Create Repository: Implement persistence layer
Build Service: Add business logic
Expose in Extension: Create SQF-callable commands
Test: Verify each layer independently

Error Handling

All commands return consistent error messages:

private _result = "forge_server" callExtension ["actor:get", ["invalid_uid"]];
private _response = _result select 0;

if (_response find "Error:" == 0) then {
    diag_log format ["Operation failed: %1", _response];
} else {
    private _data = fromJSON _response;
    // Use data
};

Logging

Logs are automatically created in @forge_server/logs/:

actor.log - Actor operations
org.log - Organization operations
redis.log - Redis connection and operations
debug.log - General debug information

License

View the License here.

Support

Issues: Gitea Issues
Documentation: See individual module READMEs
Architecture: Diagram

Roadmap

Admin system
Arsenal system
Banking system
Economy system
Garage system
Locker system
Mission template

Built using Rust, Redis, and Arma 3

Languages

SQF 29.3%

JavaScript 27.8%

Rust 21.1%

cpp 8.7%

Pawn 5.8%

Other 7.1%