Перейти к содержимому
Mineforgian

NATS Player Data Bridge

Sync player data across Minecraft servers using NATS.

Загрузки
109
Подписчики
1
Обновлён
19 июня 2026 г.
Лицензия
MIT

Опубликован 20 апреля 2026 г.

Исходный кодСообщить об ошибке

NATS Player Data Bridge

Status

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

Ченджлог

1.0.0-beta.9Бета26.2 · 19 июня 2026 г.

Update target version to 26.2

  • No other changes were made

Full Changelog: https://github.com/xSaVageAU/NATS-Player-Data-Bridge/compare/v1.0.0-beta.8...v1.0.0-beta-9

1.0.0-beta.8Бета26.1, 26.1.1, 26.1.2 · 21 мая 2026 г.

1.0.0-beta.8

This update improves the connection lifecycle.

The config for NATS-Fabric has also been changed from YAML to JSON.

Full Changelog: https://github.com/xSaVageAU/NATS-Player-Data-Bridge/compare/v1.0.0-beta.7...v1.0.0-beta.8

1.0.0-beta.7Бета26.1, 26.1.1, 26.1.2 · 9 мая 2026 г.

1.0.0-beta.7

This update focuses on the backup system.

  • Automatic Snapshots: The bridge now automatically creates a backup when a player dies or moves between dimensions (like going to the Nether or End).
  • Detailed Backup Info: You can now see why a backup was created. Just hover over a backup in the list to see if it was caused by a death, world change, or manual save.
  • Player Names in Commands: Admins can now see player names instead of long ID codes (UUIDs) in the session list, and can use names to clear stuck sessions.
  • Improved Reliability: Under-the-hood optimizations to ensure smoother data transfers and more robust session management.

Full Changelog: v1.0.0-beta.6...v1.0.0-beta.7

1.0.0-beta.6Бета26.1, 26.1.1, 26.1.2 · 7 мая 2026 г.

1.0.0-beta.6

The mod now handles NATS downtime and server crashes gracefully, without losing player data.

  • If NATS goes down, player data is saved locally and synced back automatically when the connection returns.
  • Servers now block player logins until sync and recovery are fully complete.
  • The connection watchdog no longer times out. It will now wait indefinitely for NATS to become available.
  • Added a /nats backup confirm step to prevent accidental data rollbacks.

Feedback and bug reports are welcome.

Full Changelog: v1.0.0-beta.5...v1.0.0-beta.6

Targets:

NATS 2.12.6

Minecraft 26.1.x

1.0.0-beta.5Бета26.1, 26.1.1, 26.1.2 · 30 апреля 2026 г.

improved proxy lock handoffs

Full Changelog: https://github.com/xSaVageAU/NATS-Player-Data-Bridge/compare/v1.0.0-beta.4...v1.0.0-beta.5

1.0.0-beta.4Бета26.1, 26.1.1, 26.1.2 · 28 апреля 2026 г.

This is the first public beta release. The mod is functional and has been tested, but it is still early and rough edges should be expected. Do not use this on a production network without testing it first on a staging setup.

This release includes the full core feature set:

  • Player inventories, ender chest, health, hunger, XP, active effects, statistics, and advancements are synchronized across your cluster using NATS JetStream.
  • A cluster-wide session locking system prevents data from being overwritten if a player connects to two servers simultaneously.
  • Admin commands for manual data sync, session lock management, and long-term backup snapshots with restore support.
  • Velocity proxy support via the proxyMode config option. Requires hackEarlySend = true in FabricProxy-Lite.toml if you are using FabricProxy-Lite.

Known limitations and things to be aware of:

  • This mod requires you to run and manage your own NATS server with JetStream enabled.
  • If your NATS server goes down, players will be unable to log in. This is by design to prevent data loss, but it means NATS is a hard dependency for your network's availability.
  • The backup bucket history limit is fixed at 20 snapshots per player. You cannot change this without deleting and recreating the bucket.
  • Automatic backups (e.g. on login or on a schedule) are not yet implemented. Backups are manual only in this release.

Feedback and bug reports are welcome.

Full Changelog: https://github.com/xSaVageAU/NATS-Player-Data-Bridge/compare/v1.0.0-beta.3...v1.0.0-beta.4

Комментарии

Загружаем…