Magnus

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

download 28 Downloads · favorite 0 Followers · Updated 1 week ago

Magnus (Server-Side)

Build Status GitHub Tag

A high-performance, fault-tolerant inventory synchronization mod for Minecraft Fabric servers.

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

Module	Description
Inventory Sync	Core synchronization of inventory, ender chest, health, hunger, XP, and potion effects. Enabled by default.
Global Chat	Syncs chat messages across all servers via Redis pub/sub. Raw text format for compatibility with LuckPerms, Stylist, etc.
Global Player List	Maintains a global player count with heartbeat. Provides `/glist` command.
Session Lock	Prevents concurrent logins by locking player sessions during sync. Players are held in queue until their data is safely transferred.

Security

Feature	Default	Description
Message Signing	✅ Enabled	HMAC-SHA256 prevents message injection attacks
Auto-Generated Secret	✅	32-byte cryptographic secret generated on first run
Replay Prevention	30 sec	Messages older than 30 seconds are rejected
Payload Size Limits	64KB	Prevents DoS via oversized messages
SSL/TLS Support	Optional	Encrypt Redis connections

Configuration

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

Generate Config: Start your server once to generate the default configuration file at config/magnus.json.
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
}

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

Option	Default	Description
`serverName`	`"default"`	Unique identifier for this server (e.g., `"survival"`, `"lobby"`)
`enableInventorySync`	`true`	Enable inventory/player data synchronization. Disable for lobby servers.
`enableGlobalChat`	`false`	Enable cross-server chat synchronization
`enableGlobalPlayerList`	`false`	Enable global player list and `/glist` command
`enableSessionLock`	`false`	Enable session locking to prevent concurrent logins
`enableMessageSigning`	`true`	Enable HMAC message signing (recommended)
`redisSsl`	`false`	Enable SSL/TLS for Redis connections

Commands

Command	Description
`/glist`	Shows total player count and players grouped by server (requires `enableGlobalPlayerList`)

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

What are you searching for?

Magnus

Versions

Magnus Sync v1.3.2

Magnus Sync v1.3.1

Magnus Sync v1.3.0

Magnus Sync v1.2.0

Magnus Sync v1.1.2

About

Magnus (Server-Side)