Horizon Atlas

⚠️ WORK IN PROGRESS ⚠️ Website

A high-performance, production-ready WebSocket proxy and load balancer designed for distributed game server architectures. Atlas intelligently routes client connections across multiple Horizon game servers while providing seamless server transitions, real-time traffic analysis, and advanced spatial routing capabilities.

🚀 Features

Core Functionality

• Spatial Load Balancing - Route clients to servers based on 3D world coordinates
• Seamless Client Transfers - Move players between servers without connection drops
• WebSocket Proxy - High-performance TCP passthrough with WebSocket support
• Real-time Traffic Analysis - Non-blocking data skimming for monitoring and debugging
• Health Monitoring - Automatic server health checks with failover capabilities

Advanced Capabilities

• Dynamic Server Registration - Horizon servers register themselves with their region bounds
• Predictive Server Transitions - Detect client movement patterns to preload server instances
• Cross-Server Communication - Facilitate object and player transitions between server boundaries
• Maestro Integration - Works with Horizon-Maestro for auto-scaling
• Production-Ready Architecture - Comprehensive error handling, logging, and monitoring

🏗️ Architecture

Atlas operates as a spatial routing layer in front of your Horizon game server cluster:

                         ┌─────────────────┐
     Clients ──────────► │  Atlas Proxy    │ ◄──── Maestro (orchestrator)
                         │   :9000/:9001   │
                         └────────┬────────┘
                                  │ Spatial Routing
              ┌───────────────────┼───────────────────┐
              ▼                   ▼                   ▼
        ┌───────────┐       ┌───────────┐       ┌───────────┐
        │  Horizon  │       │  Horizon  │       │  Horizon  │
        │  (0,0,0)  │       │  (1,0,0)  │       │  (0,1,0)  │
        │   :8080   │       │   :8081   │       │   :8082   │
        └───────────┘       └───────────┘       └───────────┘
           Region 0            Region 1            Region 2

Ports

• 9000 - Client WebSocket proxy port
• 9001 - REST API for server registration and management

Modular Design

• proxy - Main proxy server and connection handling
• server - Backend server management and spatial routing
• client - Client connection tracking and state management
• transfer - Server-to-server client migration system
• spatial - 3D region management and coordinate routing
• skim - Real-time traffic analysis and monitoring
• config - Configuration management
• error - Comprehensive error handling and result types

🚦 Getting Started

Prerequisites

• Rust 1.70+
• Horizon game servers running (or use with Maestro for auto-deployment)

Installation

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

Running Standalone

# Set environment variables
export ATLAS_PROXY_ADDR=0.0.0.0:9000
export ATLAS_API_ADDR=0.0.0.0:9001
export ATLAS_REGION_SIZE=1000.0

cargo run

Running with Maestro (Recommended)

The easiest way to run Atlas is via Horizon-Maestro, which automatically deploys and configures Atlas along with Horizon game servers:

cd Horizon-Maestro
MAESTRO_AUTO_BOOTSTRAP=true cargo run

Maestro will:

1. Deploy Atlas with proper configuration
2. Deploy initial Horizon game server(s)
3. Configure servers to register with Atlas automatically

Environment Variables

Variable	Default	Description
ATLAS_PROXY_ADDR	0.0.0.0:9000	Client WebSocket proxy address
ATLAS_API_ADDR	0.0.0.0:9001	REST API address
ATLAS_MAESTRO_URL	-	Maestro URL for auto-scaling requests
ATLAS_REGION_SIZE	1000.0	Size of each region in world units
ATLAS_AUTO_SCALE	false	Request new regions from Maestro automatically

📡 REST API (Port 9001)

Server Registration

Horizon servers register themselves with Atlas on startup:

# Register a server
curl -X POST http://localhost:9001/servers/register \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "horizon-0-0-0",
    "address": "127.0.0.1:8080",
    "region": {"x": 0, "y": 0, "z": 0},
    "center": {"x": 500.0, "y": 500.0, "z": 500.0},
    "bounds_size": 500.0,
    "capacity": 1000
  }'

API Endpoints

Endpoint	Method	Description
GET /servers	GET	List all registered servers
POST /servers/register	POST	Register a new server
DELETE /servers/<id>	DELETE	Unregister a server
GET /servers/<id>/stats	GET	Get server statistics
POST /transfer	POST	Initiate client transfer
GET /health	GET	Health check

🎯 Spatial Routing

Atlas uses 3D spatial regions to route clients to the appropriate server:

// Each server manages a cubic region of the world
struct ServerRegion {
    center: Vec3,      // Center point (e.g., 500, 500, 500)
    bounds_size: f64,  // Half-size (e.g., 500 = 1000x1000x1000 cube)
    region: (i32, i32, i32),  // Region coordinates (0,0,0)
}

// When a client connects at position (750, 200, 300):
// Atlas finds the server whose region contains that position
// and routes the connection accordingly

Automatic Transfers

When a client moves near a region boundary, Atlas:

1. Detects the boundary approach via traffic analysis
2. Notifies the target server to prepare
3. Seamlessly transfers the client connection
4. Maintains game state consistency

🐳 Docker Deployment

Docker Compose

services:
  atlas:
    image: ghcr.io/far-beyond-dev/horizon-atlas:main
    ports:
      - "9000:9000"  # Proxy
      - "9001:9001"  # API
    environment:
      - ATLAS_PROXY_ADDR=0.0.0.0:9000
      - ATLAS_API_ADDR=0.0.0.0:9001
      - ATLAS_MAESTRO_URL=http://maestro:8000
      - ATLAS_REGION_SIZE=1000.0
      - ATLAS_AUTO_SCALE=true

Building the Image

docker build -t horizon-atlas:local .

🛠️ Development

Project Structure

src/
├── main.rs          # Application entry point
├── lib.rs           # Module declarations
├── proxy.rs         # Main proxy server logic
├── server.rs        # Backend server management  
├── client.rs        # Client connection handling
├── transfer.rs      # Client migration system
├── spatial.rs       # 3D region management
├── skim.rs          # Traffic analysis
├── config.rs        # Configuration management
├── persistence.rs   # State persistence
└── error.rs         # Error types and handling

🤝 Integration with Horizon Ecosystem

Atlas is part of the Horizon distributed game server ecosystem:

• Horizon - The game server instances that Atlas routes to
• Horizon-Maestro - Orchestrator that deploys Atlas and Horizon
• Horizon-Network-Common - Shared API types for communication

Data Flow

Client → Atlas (spatial routing) → Horizon Server
                  ↑
            Maestro (scaling requests)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation - Website
• Issues - GitHub Issues
• Discussions - GitHub Discussions

---

Atlas - Intelligent spatial proxy for distributed Horizon game servers.