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)

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.
• 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