Forge Framework

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

1. Clone the repository from Gitea
2. 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:

• Extension Contributing Guide
• Services Contributing Guide
• Repositories Contributing Guide
• Models Contributing Guide
• Library Contributing Guide
• Adapter Contributing Guide

Development Workflow

1. Define Model: Create data structure with validation
2. Create Repository: Implement persistence layer
3. Build Service: Add business logic
4. Expose in Extension: Create SQF-callable commands
5. 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