NATS Player Data Bridge

This project is in its early stages and undergoing active development. Edge cases may still exist in complex modded environments. Please report any issues on GitHub or join the community on Discord. Any feedback is valuable and greatly appreciated!

A server-side Fabric mod that synchronizes player inventories, ender chests, health, XP, statistics, and advancements across multiple Minecraft servers using NATS JetStream.

When a player leaves, their data is saved to a NATS Key-Value bucket. When they join another server in the same cluster, that data is fetched and applied before they spawn.

Requirements

• NATS server with JetStream enabled.
• Fabric API.

Installation

1. Drop the mod jar into your mods/ folder.
2. Start the server once to generate two config files.
3. Configure config/nats-fabric.json with your NATS server URL, auth token, and a unique name for this server.
4. Restart.

Setting up the NATS Server

When setting up your NATS server, create a new text file named nats-server.conf and paste the following minimal configuration into it:

port: 4222 authorization { token: "your_secret_token_here" } jetstream { store_dir: "./jetstream-data" }

Then, start your NATS server by pointing it to the configuration file you just created:

• Linux/macOS: ./nats-server -c nats-server.conf
• Windows: nats-server.exe -c nats-server.conf

Ensure the auth token in config/nats-fabric.yml matches what you have set here.

Velocity Proxy Support

If you are running Velocity, set "proxyMode": true in config/nats-player-data-bridge.json. Without this, overlapping logins are rejected outright, which will break server switching.

If you are also using FabricProxy-Lite, you must set hackEarlySend = true in FabricProxy-Lite.toml for the mod to work correctly.

Configuration (config/nats-player-data-bridge.json)

Key Default Description proxyMode false Enable RPC lock handoff for Velocity proxy setups. rpcTimeoutSeconds 15 The timeout in seconds for cross-server RPC requests (e.g., during proxy transfers). syncStats true Sync player statistics. syncAdvancements true Sync advancements. filterMode "whitelist" "whitelist" syncs only listed NBT keys. "blacklist" syncs everything except listed keys. filterKeys Inventory, health, XP, etc. The NBT keys to include or exclude depending on filterMode. backupHistoryCount 20 The number of historical snapshots to keep per player in the backup bucket. autoBackupPolicies [DEATH, DIMENSION_CHANGE] List of triggers that automatically create snapshots.

Admin Commands

All commands require operator permissions.

Command Description /nats sync [player] Manually push a player's data to the cluster. /nats sessions list [page] View DIRTY session locks in the cluster (paginated). /nats sessions clean <player/uuid> Clear a stuck session lock for a specific player by name or UUID. /nats backup push <player> Create a manual snapshot of a player's data. /nats backup list <player> View snapshots. Hover over entries for tags (death, dim_change, etc). /nats backup restore <player> <rev> Stage a restoration. Requires /nats backup confirm to execute. /nats backup confirm Execute a staged restoration. The player will be kicked to apply data safely.

Data Handling

The bridge is built for environments where data integrity and network stability are critical.

• Cluster-Wide Locking: Each player session is assigned a unique lock. A server can only write data if it holds that lock, preventing corruption from racing servers.
• Fail-to-Safety (Vaulting): If NATS is unreachable, player data is saved to a local disk vault (nats-player-data-bridge/pending_sync/) and automatically synced back when the connection is restored.
• Self-Healing: Servers perform a recovery step on startup to reconcile orphaned locks and clear any local vault data.
• Auto-Backups: Configurable triggers (Death, Dimension Change) create snapshots automatically.
• Background Processing: All network operations run on virtual threads.
• Binary Format: Data is packed into a CBOR binary format with Zstd compression for minimal network overhead.
• Stale Data Protection: Timestamping prevents old data from overwriting newer progress during cluster recovery.
• Readiness Gating: Servers block player joins until background synchronization and healing are 100% complete.

License

MIT