Magnus

Magnus (Server-Side)

A modular, high-performance, and resilient synchronization suite for Minecraft Fabric servers. Features real-time inventory sync, cross-server chat, and global player management.

Features

Core Sync

• Multi-Server Sync: Syncs Inventory, Ender Chest, Health, Hunger, XP, Potion Effects.
• High Performance: Uses Redis for sub-millisecond data retrieval.
• Persistence: Uses PostgreSQL for permanent reliable storage.
• Fault Tolerance:
  • Circuit Breaker: Detects database failures automatically.
  • Local Fallback: Saves data to disk if the database goes down.
  • Auto-Recovery: "The Janitor" service automatically restores data when the database comes back online.

Modules

Security

Configuration

Magnus requires a PostgreSQL database and a Redis instance to function.

1. Generate Config: Start your server once to generate the default configuration file at config/magnus.json.
2. Edit Config: Stop the server and open config/magnus.json:

{
    "postgresUrl": "jdbc:postgresql://your-db-host:5432/magnus",
    "postgresUser": "your_user",
    "postgresPass": "your_password",
    "redisHost": "your-redis-host",
    "redisPort": 6379,
    "redisPass": null,
    "serverName": "survival",
    "enableInventorySync": true,
    "enableGlobalChat": false,
    "enableGlobalPlayerList": false,
    "enableSessionLock": false,
    "enableMessageSigning": true,
    "messageSigningSecret": "auto-generated-on-first-run",
    "redisSsl": false
}

1. Launch: Restart your server. Magnus will automatically verify the connection and create the necessary database schema.

[!IMPORTANT] Multi-Server Setup: Copy the messageSigningSecret from the first server to all other servers. All servers must use the same secret.

Configuration Options

Commands

Architecture

For detailed flow diagrams and behavior documentation:

• Core Sync Flow - Data synchronization and fault tolerance
• Global Chat Flow - Cross-server chat messaging
• Global Player List Flow - Player list heartbeat and /glist
• Session Lock Flow - Login queue and session locking
• Message Security Flow - HMAC signing and replay prevention
• Server Lifecycle Flow - Startup and shutdown sequence