A high-performance, modular game server architecture built in Rust, designed for large-scale multiplayer games with real-time networking requirements. The server provides a plugin-first architecture that separates infrastructure concerns from game logic, enabling rapid development and deployment of multiplayer game features.

Before you continue

Do you like this project? You may like the pulsar game engine from many of the same developers who work on Horizon. Check it out

Overview
Architecture
Quick Start
Configuration
Plugin Development
Event System
GORC System
Security
Deployment
Performance
Contributing

Overview

Horizon addresses the common challenges in multiplayer game server development by providing a robust foundation that handles networking, player management, and real-time data synchronization while keeping game-specific logic in isolated, hot-reloadable plugins. This architecture allows teams to focus on game mechanics rather than infrastructure concerns.

The server is built around three core principles: modularity through a comprehensive plugin system, performance through efficient async networking and memory management, and reliability through comprehensive error handling and monitoring capabilities. The result is a server that can handle thousands of concurrent players while maintaining low latency and high availability.

Architecture

System Overview

graph TB
    Client[Game Clients] --> WS[WebSocket Layer]
    WS --> ES[Event System]
    ES --> PM[Plugin Manager]
    ES --> GORC[GORC System]
    ES --> NL[Network Layer]
    
    PM --> P1[Chat Plugin]
    PM --> P2[Movement Plugin]
    PM --> P3[Combat Plugin]
    PM --> PN[...Other Plugins]
    
    GORC --> SP[Spatial Partitioning]
    GORC --> RC[Replication Channels]
    
    ES --> Core[Core Systems]
    Core --> Config[Configuration]
    Core --> Security[Security & Rate Limiting]
    Core --> Health[Health Monitoring]
    
    P1 -.-> ES
    P2 -.-> ES
    P3 -.-> ES
    PN -.-> ES

Core Components

The server architecture consists of several interconnected systems that work together to provide a complete multiplayer gaming infrastructure. The EventSystem serves as the central nervous system, routing messages between different components using a type-safe event handling mechanism. This design ensures that different parts of the system can communicate efficiently while maintaining strict boundaries between concerns.

The Plugin System enables dynamic loading and hot-reloading of game logic without server restarts. Plugins are isolated from each other and from core server functionality, providing stability and security while allowing for rapid iteration during development. Each plugin operates in its own namespace and can register handlers for specific event types.

The GORC (Game Object Replication Channels) system handles real-time synchronization of game state between server and clients. It provides efficient spatial partitioning, level-of-detail management, and selective replication based on player proximity and game mechanics. This system is crucial for maintaining consistent game state across all connected players.

Network Layer

The networking layer is built on top of async Rust with tokio, providing high-performance WebSocket connections that can handle thousands of concurrent players. The server implements connection pooling, automatic cleanup of stale connections, and configurable rate limiting to protect against abuse. Network messages are processed asynchronously to ensure that slow clients don't impact overall server performance.

Connection management includes automatic heartbeat monitoring, graceful disconnection handling, and reconnection support for mobile clients with unstable network conditions. The server tracks connection statistics and provides detailed metrics for monitoring and debugging network issues.

Quick Start

Prerequisites

Ensure you have Rust 1.70 or later installed on your system. The server has been tested on Linux, macOS, and Windows platforms. Additional dependencies include openssl-dev (Linux) or equivalent security libraries for TLS support.

Installation

Clone the repository and build the server:

git clone https://github.com/Far-Beyond-Dev/horizon.git
cd horizon
cargo build --release

The build process will compile all core components and example plugins. The resulting binary will be located in target/release/horizon.

First Run

Start the server with default configuration:

./target/release/horizon

The server will bind to localhost:8080 by default and look for plugins in the plugins/ directory.

Configuration

Create a config.toml file to customize server behavior:

[server]
bind_address = "127.0.0.1:8080"
max_connections = 1000
connection_timeout = 60
use_reuse_port = false
tick_interval_ms = 50
plugin_directory = "plugins"

[server.region_bounds]
min_x = -1000.0
max_x = 1000.0
min_y = -1000.0
max_y = 1000.0
min_z = -100.0
max_z = 100.0

[server.security]
enable_rate_limiting = true
max_requests_per_minute = 60
max_message_size = 65536
enable_ddos_protection = true
max_connections_per_ip = 10

Configuration options cover network settings, security parameters, plugin management, and game world boundaries. The server validates all configuration values at startup and provides detailed error messages for invalid settings.

Plugin Development

Plugin Lifecycle

sequenceDiagram
    participant S as Server
    participant PM as Plugin Manager
    participant P as Plugin
    participant ES as Event System
    
    S->>PM: Start Server
    PM->>P: Load Plugin Library
    P->>PM: create_plugin()
    PM->>P: pre_init(context)
    P->>ES: Register Event Handlers
    PM->>P: init(context)
    P->>P: Initialize Resources
    
    Note over S,ES: Server Running - Event Processing
    
    ES->>P: Handle Events
    P->>ES: Emit Events
    
    Note over S,ES: Server Shutdown
    
    S->>PM: Shutdown Signal
    PM->>P: shutdown(context)
    P->>P: Clean Resources
    PM->>P: Unload Plugin

Plugin Structure

Plugins are dynamic libraries that implement the Plugin trait from the horizon_event_system crate. Each plugin operates independently and communicates with the server and other plugins through the event system. This design ensures that plugin crashes or errors don't affect other components.

A basic plugin structure looks like this:

use async_trait::async_trait;
use chrono::prelude::*;
use horizon_event_system::{
    create_simple_plugin, current_timestamp, register_handlers, EventSystem, LogLevel,
    PlayerId, PluginError, Position, ServerContext, SimplePlugin,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

pub struct GreeterPlugin {
    name: String,
    welcome_count: u32,
}

impl GreeterPlugin {
    pub fn new() -> Self {
        println!("🎉 GreeterPlugin: Creating new instance");
        Self {
            name: "greeter".to_string(),
            welcome_count: 0,
        }
    }
}

impl Default for GreeterPlugin {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl SimplePlugin for GreeterPlugin {
    fn name(&self) -> &str {
        &self.name
    }

    fn version(&self) -> &str {
        "1.0.0"
    }

    async fn register_handlers(&mut self, events: Arc<EventSystem>, _context: Arc<dyn ServerContext>) -> Result<(), PluginError> {
        println!("👋 GreeterPlugin: Registering event handlers...");

        Ok(())
    }

    async fn on_init(&mut self, context: Arc<dyn ServerContext>) -> Result<(), PluginError> {
        context.log(
            LogLevel::Info,
            "👋 GreeterPlugin: Starting up! Ready to welcome players!",
        );
    }
}

// Create the plugin using our macro - zero unsafe code!
create_simple_plugin!(GreeterPlugin);

Event Handling

The event system provides four types of event handlers corresponding to different aspects of game server operation. Core events handle server lifecycle and system-level operations. Client events process messages from connected players. Plugin events enable inter-plugin communication. GORC events manage game object replication and state synchronization.

Event handlers are type-safe and use Rust's ownership system to prevent common concurrency issues. The event system automatically handles serialization, routing, and error recovery. Handlers can be synchronous for simple operations or asynchronous for complex processing that involves I/O or network operations.

Plugin Examples

The repository includes several example plugins that demonstrate common patterns:

Chat Plugin: Handles player chat messages, moderation, and channels
Movement Plugin: Processes player movement and validates positions
Combat Plugin: Manages player vs player and player vs environment combat
Economy Plugin: Handles virtual currency, trading, and market operations

Each example plugin includes extensive documentation and demonstrates best practices for error handling, state management, and inter-plugin communication

Horizon

Install / Use

README