# NATS Player Data Bridge
\n### <\/p>\n
> This project is in its early stages and undergoing active development. Edge cases may still exist in complex modded environments.
\n> Please report any issues on GitHub or join the community on Discord.
\n> Any feedback is valuable and greatly appreciated!<\/p>\n
A server-side Fabric mod that synchronizes player inventories, ender chests, health, XP, statistics, and advancements across multiple Minecraft servers using NATS JetStream.<\/p>\n
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.<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
– **Server-side only.** Clients do not need this mod installed.
\n– **NATS server with JetStream enabled.**
\n– **Fabric API.**<\/p>\n
—<\/p>\n
## Installation<\/p>\n
1. Drop the mod jar into your `mods\/` folder. The NATS client library is already bundled, no extra files needed.
\n2. Start the server once to generate two config files.
\n3. Configure `config\/nats-fabric.yml` with your NATS server URL, auth token, and a unique name for this server.
\n4. Restart.<\/p>\n
### Setting up the NATS Server<\/p>\n
When setting up your NATS server, create a new text file named `nats-server.conf` and paste the following minimal configuration into it:<\/p>\n
“`hcl
\nport: 4222<\/p>\n
authorization {
\n token: “your_secret_token_here”
\n}<\/p>\n
jetstream {
\n store_dir: “.\/jetstream-data”
\n}
\n“`<\/p>\n
Then, start your NATS server by pointing it to the configuration file you just created:
\n– **Linux\/macOS:** `.\/nats-server -c nats-server.conf`
\n– **Windows:** `nats-server.exe -c nats-server.conf`<\/p>\n
Ensure the auth token in `config\/nats-fabric.yml` matches what you have set here.<\/p>\n
—<\/p>\n
## Velocity Proxy Support<\/p>\n
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.<\/p>\n
When proxyMode is on, the mod prevents item duplication during the switch by freezing the player server-side until the transfer is complete.<\/p>\n
If you are also using FabricProxy-Lite, you must set `hackEarlySend = true` in `FabricProxy-Lite.toml` for the mod to work correctly.<\/p>\n
—<\/p>\n
## Configuration (`config\/nats-player-data-bridge.json`)<\/p>\n
| Key | Default | Description |
\n|—|—|—|
\n| `proxyMode` | `false` | Enable RPC lock handoff for Velocity proxy setups. |
\n| `rpcTimeoutSeconds` | `15` | The timeout in seconds for cross-server RPC requests (e.g., during proxy transfers). |
\n| `syncStats` | `true` | Sync player statistics. |
\n| `syncAdvancements` | `true` | Sync advancements. |
\n| `filterMode` | `”whitelist”` | `”whitelist”` syncs only listed NBT keys. `”blacklist”` syncs everything except listed keys. |
\n| `filterKeys` | Inventory, health, XP, etc. | The NBT keys to include or exclude depending on filterMode. |
\n| `backupHistoryCount` | `20` | The number of historical snapshots to keep per player in the backup bucket. |
\n| `autoBackupPolicies` | `[DEATH, DIMENSION_CHANGE]` | List of triggers that automatically create snapshots. |<\/p>\n
—<\/p>\n
## Admin Commands<\/p>\n
All commands require operator permissions.<\/p>\n
| Command | Description | —<\/p>\n ## Data Handling & Resilience<\/p>\n The bridge is built for production environments where data integrity and network stability are critical.<\/p>\n – **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. —<\/p>\n ## License<\/p>\n MIT<\/p>\n","protected":false},"excerpt":{"rendered":" Sync player data across Minecraft servers using NATS.<\/p>\n","protected":false},"featured_media":108825,"template":"","meta":{"_minecraft_slug":"nats-player-data-bridge","_minecraft_project_id":"I0VEk9nD","_minecraft_author":"xSaVageAU","_minecraft_license":"MIT","_minecraft_downloads":11,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"nats-player-data-bridge.zip","_minecraft_size_bytes":42792521,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-16T12:29:53.168611Z","_minecraft_date_created":"2026-05-12T05:18:25.377916Z","_minecraft_date_modified":"2026-05-09T17:41:06.800261Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/nats-player-data-bridge","_minecraft_icon_attachment_id":108825,"_minecraft_imported_at":"2026-06-06T07:11:29+00:00","_minecraft_import_hash":"685e82c8b16f39f6ffca8fa5735fa8d0","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,126,91,92],"mod_loader":[99],"minecraft_version":[83,167,163],"class_list":["post-108824","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-management","mod_category-storage","mod_category-utility","mod_loader-fabric","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n
\n|—|—|
\n| `\/nats sync [player]` | Manually push a player’s data to the cluster. |
\n| `\/nats sessions list [page]` | View DIRTY session locks in the cluster (paginated). |
\n| `\/nats sessions clean
\n| `\/nats backup push
\n| `\/nats backup list
\n| `\/nats backup restore
\n| `\/nats backup confirm` | Execute a staged restoration. The player will be kicked to apply data safely. |<\/p>\n
\n– **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.
\n– **Self-Healing:** Servers perform an atomic recovery on startup to reconcile orphaned locks and clear any local vault data.
\n– **Auto-Backups:** Configurable triggers (Death, Dimension Change) create safety snapshots automatically.
\n– **Background Processing:** All network operations run on dedicated virtual threads to ensure zero impact on server TPS.
\n– **Binary Format:** Data is packed into a compact CBOR binary format with Zstd compression for minimal network overhead.
\n– **Stale Data Protection:** Intelligent timestamping prevents old data from overwriting newer progress during cluster recovery.
\n– **Readiness Gating:** Servers block player joins until background synchronization and healing are 100% complete.
\n– **Watchdog:** The networking layer performs automatic reconnection retries.<\/p>\n