HyTari Studios · Офіційний посібник з налаштування

Server Router

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

Практичний посібник для Server Router - Network Sync. Від ідентифікації сервера та routes до спільних систем, нативного scoreboard і опційної синхронізації інвентарю. Кожен розділ поєднує копійований JSON із поясненням реальної поведінки.

ПОЧАТИ ПОСІБНИК СТОРІНКА МОДА

ПЕРЕД ПОЧАТКОМ

Початок роботи

КРОК 01

Встановіть на кожному сервері

Використовуйте однакову збірку ServerRouter на кожному вузлі мережі.

КРОК 02

Налаштовуйте по одному вузлу

Призначте кожному серверу унікальний serverId, власні host/port і правильну роль.

КРОК 03

Перевірте до відкриття доступу

Протестуйте routes і backend-захист із staff-акаунтами до запуску публічного трафіку.

ServerRouter — мережева інфраструктура: уважно налаштовуйте облікові дані, hosts, дозволи й правила direct access. Перед зміною кількох модулів збережіть резервну копію 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 вмикає routing, 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 ПРИКЛАДИ

Routes і команди

Визначте призначення, команди, aliases, дозволи й повідомлення routes.

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

Routes, команди, 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

Захистіть backends і керуйте тимчасовими дозволами, 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 ПРИКЛАДИ

Портали

Використовуйте ті самі routes для порталів із тими самими мережевими перевірками.

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 з сумісними серверами й mods без окремого запиту бази кожною інтеграцією.

РОЗДІЛ 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 для захисту load, save та одночасних 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 для захисту load, save та одночасних 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 дозволяє іншим mods реєструвати нові без 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 дозволяє іншим mods реєструвати нові без 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 із тестових build не входять у документовану конфігурацію.

НАГОРУ