HyTari Studios · Официальное руководство по настройке

Server Router

Настройте сеть, понимая назначение каждого модуля.

Практическое руководство по Server Router - Network Sync. От идентификации сервера и маршрутов до общих систем, нативного scoreboard и опциональной синхронизации инвентаря. Каждый раздел сочетает копируемый JSON с объяснением реального поведения.

НАЧАТЬ РУКОВОДСТВО СТРАНИЦА МОДА

ПЕРЕД НАЧАЛОМ

Начало работы

ШАГ 01

Установите на каждом сервере

Используйте одну и ту же сборку ServerRouter на каждом узле сети.

ШАГ 02

Настраивайте по одному узлу

Назначьте каждому серверу уникальный serverId, собственные host/port и правильную роль.

ШАГ 03

Проверьте до открытия доступа

Протестируйте маршруты и защиту backend с аккаунтами персонала до запуска публичного трафика.

ServerRouter — сетевая инфраструктура: внимательно настраивайте учетные данные, hosts, права и правила прямого доступа. Перед изменением нескольких модулей сохраните резервную копию production-конфигурации.

ГЛАВА 01 · 1 ПРИМЕРЫ

Установка и роль

Определите сервер в сети и выберите роль router, backend или обе.

01КОНФИГУРАЦИЯ

Идентичность и роль сервера

Каждому узлу сети нужен уникальный serverId и адрес, доступный другим серверам.

КОНФИГУРАЦИЯ
{
  "enabled": true,
  "role": "both",
  "serverId": "hub",
  "host": "hub.example.com",
  "port": 5520,
  "maxPlayers": 100,
  "acceptingPlayers": true
}

mods/ServerRouter/config.json

ЧТО ЭТО ДЕЛАЕТ

Каждому узлу сети нужен уникальный serverId и адрес, доступный другим серверам.

ВАЖНОЕ ПОВЕДЕНИЕ

  • role: main включает маршрутизацию, backend принимает transfers, both объединяет обе роли.
  • serverId должен быть стабильным и совпадать со значением в routes и сетевых модулях.
  • acceptingPlayers позволяет временно убрать сервер из доступных назначений без выключения.

ГЛАВА 02 · 1 ПРИМЕРЫ

База данных и heartbeat

Настройте MariaDB и частоту публикации состояния каждого сервера.

01КОНФИГУРАЦИЯ

MariaDB, heartbeat и online-статус

ServerRouter использует MariaDB для общего состояния, presence, transfers и сетевых модулей.

КОНФИГУРАЦИЯ
{
  "databaseHost": "127.0.0.1",
  "databasePort": 3306,
  "databaseName": "hytale_network",
  "databaseUser": "serverrouter",
  "databasePassword": "CHANGE_ME",
  "tablePrefix": "server_router_",
  "heartbeatIntervalSeconds": 5,
  "offlineTimeoutSeconds": 15
}

mods/ServerRouter/config.json

ЧТО ЭТО ДЕЛАЕТ

ServerRouter использует MariaDB для общего состояния, presence, transfers и сетевых модулей.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Все серверы одной сети должны использовать одну базу данных.
  • heartbeatIntervalSeconds задает частоту обновления состояния узла.
  • offlineTimeoutSeconds определяет, когда узел без heartbeat считается недоступным.

ГЛАВА 03 · 1 ПРИМЕРЫ

Маршруты и команды

Определите назначения, команды, aliases, права и сообщения маршрутов.

01КОНФИГУРАЦИЯ

Маршруты, команды, aliases и права

Каждый route связывает команду с сервером назначения и проверяется до transfer.

КОНФИГУРАЦИЯ
{
  "routes": [
    {
      "name": "Survival",
      "command": "survival",
      "aliases": [
        "sopravvivenza"
      ],
      "serverId": "survival",
      "host": "survival.example.com",
      "port": 5522,
      "permission": "serverrouter.command.survival"
    }
  ]
}

mods/ServerRouter/config.json → routes[]

ЧТО ЭТО ДЕЛАЕТ

Каждый route связывает команду с сервером назначения и проверяется до transfer.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Команда хранится в JSON без slash и используется в игре как /survival.
  • aliases добавляет альтернативные имена для того же transfer.
  • Перед referral ServerRouter проверяет статус, вместимость и доступность назначения.

ГЛАВА 04 · 1 ПРИМЕРЫ

Безопасность transfer

Защитите backend и управляйте временными разрешениями, rejoin и cooldown.

01КОНФИГУРАЦИЯ

Защита backend и transfer-токены

Backend-серверы могут запрещать прямой вход и принимать только игроков из авторизованного transfer.

КОНФИГУРАЦИЯ
{
  "allowDirectAccess": false,
  "allowSameServerRejoin": true,
  "sameServerRejoinSeconds": 300,
  "accessTokenTtlSeconds": 60,
  "accessTokenSecret": "",
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20,
  "loginPortalSafetySeconds": 20
}

mods/ServerRouter/config.json

ЧТО ЭТО ДЕЛАЕТ

Backend-серверы могут запрещать прямой вход и принимать только игроков из авторизованного transfer.

ВАЖНОЕ ПОВЕДЕНИЕ

  • При allowDirectAccess=false backend использует временное разрешение от исходного сервера.
  • Нативный whitelist Hytale остается окончательной проверкой доступа.
  • Arrival cooldown предотвращает случайный возврат через портал сразу после login или transfer.

ГЛАВА 05 · 1 ПРИМЕРЫ

Порталы

Используйте те же маршруты для порталов с теми же сетевыми проверками.

01КОНФИГУРАЦИЯ

Порталы, связанные с routes

Порталы используют назначения из router и те же проверки доступности и безопасности.

КОНФИГУРАЦИЯ
{
  "routes": [
    {
      "name": "Dungeon",
      "command": "dungeon",
      "aliases": [],
      "serverId": "dungeon",
      "host": "dungeon.example.com",
      "port": 5521,
      "permission": "serverrouter.command.dungeon"
    }
  ],
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20
}

mods/ServerRouter/config.json → routes[]

ЧТО ЭТО ДЕЛАЕТ

Порталы используют назначения из router и те же проверки доступности и безопасности.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Отдельное назначение для портала не требуется: route является общим источником.
  • Portal assets генерируются плагином и загружаются как runtime asset pack.
  • Если назначение offline, заполнено или недоступно, transfer блокируется.

ГЛАВА 06 · 1 ПРИМЕРЫ

Общие системы

Chat, events, player list и Presence API обмениваются данными между всеми серверами.

01КОНФИГУРАЦИЯ

Глобальный chat и events

Серверы могут делиться чатом и ключевыми событиями, чтобы Hub, Survival, Dungeon, Creative и другие узлы ощущались как единая сеть.

КОНФИГУРАЦИЯ
{
  "networkChat": {
    "enabled": true,
    "pollSeconds": 1,
    "messageTtlSeconds": 300,
    "maxMessageLength": 300,
    "captureMode": "eliteessentials",
    "serverDisplayNames": {
      "hub": "Hub",
      "survival": "Survival",
      "creative": "Creative"
    },
    "remoteFormat": "&8[&b%server%&8] &r%chat_format%",
    "fallbackFormat": "&8[&b%server%&8] &7%player%&r: &f%message%"
  },
  "networkEvents": {
    "enabled": true,
    "pollSeconds": 1,
    "eventTtlSeconds": 300,
    "joinEnabled": true,
    "quitEnabled": true,
    "switchEnabled": true,
    "suppressServerSwitchJoinQuit": true,
    "quitDelaySeconds": 3,
    "respectVanish": true
  }
}

mods/ServerRouter/config.json

ЧТО ЭТО ДЕЛАЕТ

Серверы могут делиться чатом и ключевыми событиями, чтобы Hub, Survival, Dungeon, Creative и другие узлы ощущались как единая сеть.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Network Chat пересылает сообщения между участвующими серверами, сохраняя имя исходного сервера и общий настраиваемый формат.
  • captureMode определяет источник локального чата; remoteFormat использует доступное форматирование, а fallbackFormat дает безопасный запасной вариант.
  • serverDisplayNames задает читаемые имена Hub, Survival или Creative вместо технического serverId.
  • Network Events может объявлять join, quit и смену сервера по всей сети; каждый тип включается отдельно.
  • suppressServerSwitchJoinQuit не дает смене сервера выглядеть как ложный quit и новый join.
  • quitDelaySeconds помогает отличить реальный disconnect от transfer в процессе; respectVanish скрывает скрытых игроков, если интеграция это поддерживает.
  • Network Player List и Presence API делятся presence с совместимыми серверами и модами без отдельного запроса базы каждой интеграцией.

ГЛАВА 07 · 2 ПРИМЕРЫ

Нативный scoreboard

Настройте содержимое, позицию, цвета, логотип и overrides для миров или динамических instances.

01КОНФИГУРАЦИЯ

Глобальный scoreboard

Нативный scoreboard независим и может располагаться в любом из четырех углов с pixel-offset.

КОНФИГУРАЦИЯ
{
  "refreshSeconds": 10,
  "horizontal": "right:0",
  "vertical": "top:0",
  "boardWidth": 180,
  "backgroundColor": "default",
  "backgroundAlpha": 0.2,
  "logo": "hytari_logo.png",
  "logoWidth": 256,
  "logoHeight": 64,
  "maxLines": 12,
  "lines": [
    "&fOnline: &b{serverrouter_total_online} &7| &fTPS: &b{tps}",
    "&fPlayer: &b{player}",
    "&fWorld: &b{world}"
  ]
}

mods/ServerRouter/scoreboard.json

ЧТО ЭТО ДЕЛАЕТ

Нативный scoreboard независим и может располагаться в любом из четырех углов с pixel-offset.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Нативный scoreboard опционален и может быть отключен без отключения ServerRouter или его сетевых систем.
  • horizontal принимает left:<px> или right:<px>; vertical принимает top:<px> или bottom:<px>.
  • backgroundColor принимает default, none или HEX #RRGGBB.
  • logo: none скрывает логотип. Строки поддерживают форматирование и динамические placeholders.
  • Если используется внешний scoreboard, placeholders ServerRouter доступны без отображения нативного.
02КОНФИГУРАЦИЯ

Overrides для миров и динамические instances

Мир может наследовать глобальную конфигурацию и менять только нужные поля.

КОНФИГУРАЦИЯ
{
  "worlds": {
    "instance-Forgotten_Temple-*": {
      "enabled": true,
      "horizontal": "left:18",
      "vertical": "bottom:120",
      "backgroundColor": "#0E4E0D",
      "backgroundAlpha": 0.25
    },
    "creative_world": {
      "enabled": false
    }
  }
}

mods/ServerRouter/scoreboard.json → worlds

ЧТО ЭТО ДЕЛАЕТ

Мир может наследовать глобальную конфигурацию и менять только нужные поля.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Matching не зависит от регистра и поддерживает * для instance-миров с динамическим суффиксом.
  • Приоритет: точное имя мира > наиболее специфичный wildcard > глобальная конфигурация.
  • Override может менять позицию, строки, ширину, фон или логотип без копирования всего глобального блока.

ГЛАВА 08 · 2 ПРИМЕРЫ

Inventory Sync и ItemQuality

Безопасно синхронизируйте инвентари и сохраняйте ItemQuality между разными registries.

01КОНФИГУРАЦИЯ

Inventory Sync

Синхронизация инвентаря опциональна и использует временные locks для защиты загрузки, сохранения и одновременных transfers.

КОНФИГУРАЦИЯ
{
  "inventorySync": {
    "enabled": false,
    "lockTtlSeconds": 120,
    "lockRefreshSeconds": 30,
    "autoSaveEnabled": true,
    "autoSaveIntervalSeconds": 600,
    "profileSaveDelayMillis": 1500,
    "loadingInventoryMessageEnabled": true,
    "loadingInventoryMessage": "server.serverrouter.inventory.loading",
    "lockedInventoryMessage": "server.serverrouter.inventory.locked",
    "debugQualityMapping": false,
    "qualityMappingLogRetentionDays": 3
  }
}

mods/ServerRouter/config.json → inventorySync

ЧТО ЭТО ДЕЛАЕТ

Синхронизация инвентаря опциональна и использует временные locks для защиты загрузки, сохранения и одновременных transfers.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Включайте только на серверах, которые должны делить один inventory-профиль.
  • Locks предотвращают параллельный доступ, способный вызвать дюпы или перезапись.
  • Оставляйте debugQualityMapping выключенным в обычной работе.
02КОНФИГУРАЦИЯ

ItemQuality между разными registries

ServerRouter сохраняет семантическую идентичность качества, а не полагается только на runtime index.

КОНФИГУРАЦИЯ
{
  "itemQualityMapping": {
    "enabled": false,
    "log-to-file": true,
    "log-to-console": false
  }
}

mods/ServerRouter/config.json

ЧТО ЭТО ДЕЛАЕТ

ServerRouter сохраняет семантическую идентичность качества, а не полагается только на runtime index.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Диагностика ItemQuality особенно полезна при разных registries или mods.
  • Если качество отсутствует на назначении, используется безопасный fallback с сохранением исходной идентичности, когда возможно.
  • Mapping logs — диагностический инструмент и не нужны стабильной сети.

ГЛАВА 09 · 1 ПРИМЕРЫ

Placeholders, API и диагностика

Интегрируйте companion mods, перезагружайте scoreboard и используйте диагностику при необходимости.

01КОНФИГУРАЦИЯ

Placeholders и API для companion mods

Scoreboard содержит встроенные placeholders, а публичный API позволяет другим модам регистрировать новые без patch ServerRouter.

КОНФИГУРАЦИЯ
{
  "integrations": {
    "api": {
      "enabled": true,
      "cacheSeconds": 10
    },
    "betterScoreBoard": {
      "enabled": false,
      "registerPlaceholders": true
    }
  },
  "scoreboardExample": [
    "{player}",
    "{world}",
    "{tps}",
    "{serverrouter_total_online}",
    "{myplugin_rank}"
  ]
}

Java API + scoreboard.json

ЧТО ЭТО ДЕЛАЕТ

Scoreboard содержит встроенные placeholders, а публичный API позволяет другим модам регистрировать новые без patch ServerRouter.

ВАЖНОЕ ПОВЕДЕНИЕ

  • Custom placeholders не зависят от регистра и не могут перехватить уже разрешенные встроенные placeholders.
  • Нативный scoreboard можно оставить выключенным: placeholders ServerRouter доступны совместимым внешним scoreboards и mods.
  • BetterScoreBoard поддерживается через отдельную интеграцию. Для другого scoreboard можно оценить специальную совместимость.
  • Read-only Presence/Network API избавляет каждый mod от отдельного запроса базы данных.
  • Для нативного scoreboard используйте /scoreboard reload после изменений конфигурации, логотипа или layout.

Перед использованием примера

Примеры намеренно посвящены одному модулю за раз. Добавляйте показанные свойства в соответствующий файл, а не заменяйте полную production-конфигурацию частичным примером.

Показанные учетные данные базы и hosts — примеры. Никогда не публикуйте реальные пароли или secrets и используйте одну общую базу только для серверов одной доверенной сети.

Публичная версия использует horizontal/vertical для позиционирования scoreboard. Старые поля offsetRight/offsetTop из тестовых сборок не входят в документированную конфигурацию.

НАВЕРХ