NATS Player Data Bridge

NATS Player Data Bridge

Этот проект находится на ранней стадии и активно развивается. Пожалуйста, сообщайте о любых проблемах на GitHub или присоединяйтесь к сообществу в Discord. Любые отзывы ценны и очень приветствуются! Серверный мод для Fabric, который синхронизирует инвентари игроков, эндер-сундуки, здоровье, опыт, статистику и достижения между несколькими серверами Minecraft с помощью NATS JetStream. Когда игрок выходит, его данные сохраняются в Key-Value бакет NATS. Когда он заходит на другой сервер в том же кластере, эти данные извлекаются и применяются до его появления.

Требования

• Сервер NATS с включённым JetStream.
• Fabric API.

---

Установка

1. Поместите jar-файл мода в папку mods/.
2. Запустите сервер один раз, чтобы сгенерировать два файла конфигурации.
3. Настройте config/nats-fabric.json, указав URL вашего сервера NATS, токен авторизации и уникальное имя для этого сервера.
4. Перезапустите.

Настройка сервера NATS

При настройке сервера NATS создайте новый текстовый файл с именем nats-server.conf и вставьте в него следующую минимальную конфигурацию:

port: 4222

authorization { token: "your_secret_token_here" }

jetstream { store_dir: "./jetstream-data" }

Затем запустите сервер NATS, указав путь к только что созданному файлу конфигурации:
- **Linux/macOS:** `./nats-server -c nats-server.conf`
- **Windows:** `nats-server.exe -c nats-server.conf`
Убедитесь, что токен авторизации в `config/nats-fabric.json` совпадает с указанным здесь.
---
## Поддержка прокси Velocity
Если вы используете Velocity, установите `"proxyMode": true` в `config/nats-player-data-bridge.json`. Без этого перекрывающиеся входы будут отклоняться, что нарушит переключение между серверами.
Если вы также используете [FabricProxy-Lite](https://modrinth.com/mod/fabricproxy-lite), необходимо установить `hackEarlySend = true` в `FabricProxy-Lite.toml`, чтобы мод работал корректно.
---
## Конфигурация (`config/nats-player-data-bridge.json`)
| Ключ | По умолчанию | Описание |
|---|---|---|
| `proxyMode` | `false` | Включает передачу RPC-блокировки для конфигураций с прокси Velocity. |
| `rpcTimeoutSeconds` | `15` | Тайм-аут в секундах для межсерверных RPC-запросов (например, при передаче через прокси). |
| `syncStats` | `true` | Синхронизировать статистику игрока. |
| `syncAdvancements` | `true` | Синхронизировать достижения. |
| `filterMode` | `"whitelist"` | `"whitelist"` синхронизирует только перечисленные NBT-ключи. `"blacklist"` синхронизирует всё, кроме перечисленных ключей. |
| `filterKeys` | Inventory, health, XP и т.д. | NBT-ключи для включения или исключения в зависимости от filterMode. |
| `backupHistoryCount` | `20` | Количество исторических снимков, сохраняемых для каждого игрока в бакете резервных копий. |
| `autoBackupPolicies` | `[DEATH, DIMENSION_CHANGE]` | Список триггеров, автоматически создающих снимки. |
---
## Админ-команды
Все команды требуют прав оператора.
| Команда | Описание |
|---|---|
| `/nats sync [player]` | Вручную отправить данные игрока в кластер. |
| `/nats sessions list [page]` | Просмотреть блокировки сессий в состоянии DIRTY в кластере (с постраничной навигацией). |
| `/nats sessions clean <player/uuid>` | Снять зависшую блокировку сессии для конкретного игрока по имени или UUID. |
| `/nats backup push <player>` | Создать ручной снимок данных игрока. |
| `/nats backup list <player>` | Просмотреть снимки. Наведите курсор на записи, чтобы увидеть теги (death, dim_change и т.д.). |
| `/nats backup restore <player> <rev>` | Подготовить восстановление. **Требуется `/nats backup confirm` для выполнения.** |
| `/nats backup confirm` | Выполнить подготовленное восстановление. Игрок будет кикнут для безопасного применения данных. |
---
## Обработка данных
Мост создан для сред, где целостность данных и стабильность сети критически важны.
- **Кластерная блокировка:** Каждой сессии игрока присваивается уникальная блокировка. Сервер может записывать данные только если он владеет этой блокировкой.
- **Отказобезопасность (Vaulting):** Если NATS недоступен, данные игрока сохраняются в локальное дисковое хранилище (`nats-player-data-bridge/pending_sync/`) и автоматически синхронизируются обратно при восстановлении соединения.
- **Самовосстановление:** Серверы выполняют шаг восстановления при запуске, чтобы согласовать осиротевшие блокировки и очистить любые локальные данные хранилища.
- **Авторезервные копии:** Настраиваемые триггеры (смерть, смена измерения) автоматически создают снимки.
- **Бинарный формат:** Данные упаковываются в бинарный формат CBOR со сжатием Zstd для минимальных сетевых накладных расходов.
- **Готовность к подключению:** Серверы блокируют вход игроков до полного завершения фоновой синхронизации и восстановления.
---
## Лицензия
MIT