NATS Player Data Bridge

This project is in its early stages and undergoing active development. 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.json 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)

Admin Commands

All commands require operator permissions.

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.
• 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.
• Binary Format: Data is packed into a CBOR binary format with Zstd compression for minimal network overhead.
• Readiness Gating: Servers block player joins until background synchronization and healing are 100% complete.

License

MIT