Horizon Network Common

Shared network types and protocols for the Horizon game server ecosystem.

Overview

This crate provides the common data structures and communication protocols used by:

• Horizon - Game server instances (regions)
• Horizon-Atlas - Server meshing proxy and load balancer
• Horizon-Maestro - Container orchestration and deployment

Installation

Add to your Cargo.toml:

[dependencies]
horizon_network_common = "0.1"

Or with git:

[dependencies]
horizon_network_common = { git = "https://github.com/Far-Beyond-Dev/Horizon-Network-Common" }

Modules

Module	Description
spatial	WorldCoordinate, RegionCoordinate, RegionBounds
server	ServerId, ServerInfo, ServerRegistration, ServerHeartbeat
player	PlayerId, PlayerInfo, PlayerState, MovementData
transfer	TransferToken, TransferRequest, TransferResult
health	HealthStatus, HealthCheck, ClusterHealth
messages	HorizonMessage, AtlasMessage, MaestroMessage

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Maestro                                  │
│              (Container Orchestration)                           │
└─────────────────────────┬───────────────────────────────────────┘
                          │ SpawnServerRequest / SpawnServerResponse
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                          Atlas                                   │
│        (Server Meshing Proxy + Player Routing)                   │
└────────┬────────────────┬───────────────────┬───────────────────┘
         │                │                   │
         │ Registration   │ Heartbeat         │ Transfer
         ▼                ▼                   ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│   Horizon      │ │   Horizon      │ │   Horizon      │
│  Region(0,0,0) │ │  Region(1,0,0) │ │  Region(0,1,0) │
└────────────────┘ └────────────────┘ └────────────────┘

Usage

use horizon_network_common::{
    WorldCoordinate, RegionCoordinate, RegionBounds,
    ServerInfo, ServerRegistration,
    PlayerId, PlayerInfo,
};

// Create a region coordinate
let region = RegionCoordinate::new(1, 0, 0);

// Convert to world position
let world_pos = region.to_world_center(1000.0);

// Check if a position is in bounds
let bounds = RegionBounds::from_center(world_pos, 500.0);
assert!(bounds.contains(&world_pos));

Key Types

Spatial Types

• WorldCoordinate - 3D position with f64 precision
• RegionCoordinate - Discrete 3D grid position (i64)
• RegionBounds - AABB bounding box for regions

Server Types

• ServerId - Unique server identifier (UUID)
• ServerInfo - Server metadata and capabilities
• ServerRegistration - Registration request from Horizon to Atlas
• ServerHeartbeat - Periodic health/load updates

Player Types

• PlayerId - Unique player identifier (UUID)
• PlayerInfo - Player metadata and state
• PlayerState - Complete player state for transfers
• MovementData - Velocity/acceleration for prediction

Transfer Types

• TransferToken - Cryptographically signed transfer authorization
• TransferRequest - Request to move player between servers
• TransferResult - Outcome of a transfer operation

Message Types

• HorizonMessage - Messages from Horizon to Atlas
• AtlasMessage - Messages from Atlas to Horizon
• MaestroMessage - Messages from Maestro to Atlas
• Envelope<T> - Message wrapper with metadata

License

MIT