Mirage Sync

Mirage

Minecraft Fabric мод для инкрементальной синхронизации регионов измерений в реальном времени между основным сервером и одним или несколькими зеркальными серверами. 中文说明

Возможности

Архитектура

flowchart LR
    subgraph Main["Main Server"]
        MS[ServerLevel world]
        RH[RegionHasher SHA-256]
        SS[MirageSyncServer<br/>Netty TCP :25566]
        SM[MainServerTask broadcasts hashes]
    end

    subgraph Mirror["Mirror Server"]
        MR[ServerLevel world]
        DC[DeltaComparator diff]
        FT[FileTransferManager atomic move]
        SC[MirageSyncClient TCP client]
        MA[MirrorApplyTask applies changes]
    end

    MS -->|"flush save"| RH
    RH -->|"hash map"| SS
    SS -.->|"HASH_LIST_RESP"| SC
    SC -->|"FILE_SYNC_START"| DC
    DC -->|"file list"| SS
    SS -.->|"FILE_CHUNK"| SC
    SC -->|"write temp mca"| FT
    FT -->|"atomic move"| MR
    MA -->|"kick players"| MR
    MA -->|"clear cache"| MR

Последовательность синхронизации (запрос инициируется зеркалом):

sequenceDiagram
    participant M as Mirror Server
    participant S as Main Server

    M->>S: HANDSHAKE (authToken)
    S-->>M: OK

    M->>S: HASH_LIST_REQ
    S->>S: flush world, save chunks
    S->>S: compute SHA-256 for all .mca files
    S-->>M: HASH_LIST_RESP (dimension + hash map)

    M->>M: diff with local hashes
    alt no differences
        M-->>S: SYNC_DONE (no changes)
    else files differ
        M->>S: FILE_SYNC_START (list of changed files)
        loop each file
            S-->>M: FILE_CHUNK (512 KB segments, base64)
        end
        S-->>M: SYNC_DONE
    end

    M->>M: kick all players in dimension
    M->>M: force-save + disable saving
    M->>M: force-unload all chunks + clear region cache
    M->>M: atomic-move temp files → region dir
    M->>M: clear region cache again
    M->>M: re-enable world saving
    M->>M: sync complete

Требования

Установка

1. Соберите мод

   ./gradlew build

   Готовый jar-файл находится в `build/libs/mirage-.jar`.

2. Установите на основной и зеркальный серверы

   • Поместите jar-файл в папку mods/ каждого сервера.
   • Оба сервера должны работать на одной версии Minecraft (1.21.11).

3. Первый запуск

   • Запустите сервер один раз. Файл config/mirage.json создастся автоматически.
   • Остановите сервер и отредактируйте конфиг (см. ниже).
   • Перезапустите сервер.

Конфигурация

Файл конфигурации: config/mirage.json, создаётся при первом запуске.

Основной сервер

{
  "mode": "main",
  "syncCooldownSeconds": 30,
  "mainServer": {
    "port": 25566,
    "authToken": "replace-with-a-secure-random-string"
  }
}

Зеркальный сервер

{
  "mode": "mirror",
  "syncCooldownSeconds": 30,
  "mirrorServer": {
    "mainIp": "main-server-ip-or-hostname",
    "mainPort": 25566,
    "authToken": "replace-with-a-secure-random-string",
    "targetDimensions": [
      "minecraft:overworld"
    ],
    "autoSyncEnabled": false,
    "autoSyncIntervalMinutes": 30
  }
}

Поля конфигурации

Внимание: authToken должен быть одинаковым на обоих серверах — иначе соединения будут отклонены. Замените значение по умолчанию change-me на надёжную случайную строку перед использованием.

Примечание: Изменения сетевых настроек (port, mainIp, mainPort) требуют перезапуска сервера.

Команды

Все команды уровня администратора требуют уровень прав OPERATORS.

Команды основного сервера

Команда	Описание
`/mirage sync `	Вычислить и отправить список хешей для одного измерения всем подключённым зеркалам

| /mirage sync all | Разослать списки хешей для всех зарегистрированных измерений | | `/mirage sync chunk | Разослать один чанк по блочным координатам | |/mirage status| Показать режим, количество подключённых зеркал, состояние синхронизации | |/mirage reload| Перезагрузитьconfig/mirage.json` с диска |

Команды зеркального сервера

Примечание: Игроки в целевом измерении на зеркальном сервере будут кикнуты во время синхронизации.

Структура проекта

src/main/java/xyz/tofumc/
├── Mirage.java                         # Точка входа мода, жизненный цикл
└── mirage/
    ├── command/
    │   └── MirageCommand.java          # Дерево команд /mirage (brigadier)
    ├── config/
    │   ├── ConfigManager.java           # Чтение/запись JSON-конфига
    │   └── MirageConfig.java            # POJO конфига со значениями по умолчанию
    ├── hash/
    │   ├── RegionHasher.java            # SHA-256 всех .mca файлов в измерении
    │   ├── DeltaComparator.java         # Сравнение хешей → файлы для скачивания/удаления
    │   └── FileTransferManager.java     # Запись по частям + атомарное перемещение
    ├── network/
    │   ├── protocol/
    │   │   ├── MessageType.java        # Enum: HANDSHAKE, HASH_LIST_REQ, ...
    │   │   ├── MirageProtocol.java     # Бинарное кодирование/декодирование (ByteBuf codec)
    │   │   ├── MessagePayloads.java     # Определения payload на основе record
    │   │   └── MirageFrameDecoder.java # 4-байтовая big-endian длина фрейма
    │   ├── server/
    │   │   ├── MirageSyncServer.java   # Netty NIO сервер, помощник рассылки
    │   │   └── ServerHandler.java      # Серверный входящий обработчик канала
    │   └── client/
    │       ├── MirageSyncClient.java   # Netty TCP клиент, авто-переподключение
    │       └── ClientHandler.java      # Клиентский входящий обработчик канала
    ├── sync/
    │   ├── SyncState.java              # Флаг синхронизации + таймер задержки
    │   ├── MainServerTask.java         # Вычисление хешей + рассылка
    │   ├── MirrorApplyTask.java        # Приём + применение файлов / патч чанков в памяти
    │   └── ScheduledSyncTask.java      # Планирование авто-синхронизации (сторона зеркала)
    ├── util/
    │   ├── HashUtil.java               # Обёртка SHA-256 дайджеста
    │   ├── DimensionPathUtil.java      # ID измерения → путь к region/директории
    │   ├── RegionFileUtil.java         # Имя .mca файла, смещение чанка, NBT I/O
    │   └── SyncLogger.java             # Логгер с namespace
    └── world/
        ├── WorldSafetyManager.java     # Кик игроков, принудительное сохранение, вкл/выкл сохранения
        └── ChunkUnloader.java          # Выгрузка чанков + очистка кеша регионов

---

Сборка и релиз

Локальная сборка

./gradlew build

Артефакт: `build/libs/mirage-.jar Версия читается из gradle.properties (mod_version`, сейчас 1.2.0).

CI/CD

Workflow	Триггер	Действие
build.yml	Пуш в любую ветку / PR	./gradlew build → загрузка артефакта
release.yml	Пуш тега v*	Обновление mod_version в gradle.properties → ./gradlew build → публикация GitHub Release

---

Участие в разработке

Сообщения об ошибках и предложения приветствуются. Пожалуйста, откройте issue перед отправкой pull request.

Настройка для разработки

git clone https://github.com/MRNOBODY-ZST/Mirage.git
cd Mirage
./gradlew build   # проверить, что компилируется

---

FAQ

В: Можно ли запустить несколько зеркал? Да. Основной сервер — это TCP-сервер, любое количество зеркал может подключиться одновременно. Каждое зеркало работает независимо. В: Этот мод работает как прокси BungeeCord/Velocity? Нет. Mirage синхронизирует только файлы регионов мира (.mca). Он не проксирует подключения игроков или чат. Это инструмент синхронизации миров, а не прокси. В: Что происходит с игроками во время синхронизации? На зеркальном сервере игроки в синхронизируемом измерении кикаются с сообщением и могут сразу переподключиться (мир полностью сохранён и консистентен). Основной сервер продолжает работать нормально — игроки не затронуты. В: Что если синхронизация прервана (например, обрыв сети)? Передача файлов использует атомарную схему временный-файл-затем-перемещение. Если передача прервана на середине, мир зеркала остаётся в предыдущем консистентном состоянии. Повреждений не происходит. Просто запустите `/mirage pull снова после переподключения. **В: Нужно ли устанавливать Fabric API отдельно?** Fabric API объявлен как зависимость вfabric.mod.jsonс версией*, то есть он обязателен. Установите его вместе с Mirage в папку mods/`.

Лицензия

MIT License — см. LICENSE.

Mirage — TofuMC · Minecraft 1.21.11 · Fabric