HyTari Studios · Guia oficial de configuração

Server Router

Configure a rede entendendo de verdade cada módulo.

Uma referência prática para Server Router - Network Sync. Siga os módulos desde identidade do servidor e rotas até sistemas compartilhados, scoreboard nativo e sincronização opcional de inventário. Cada seção combina JSON copiável com uma explicação do comportamento real.

INICIAR O GUIA PÁGINA DO MOD

ANTES DE COMEÇAR

Primeiros passos

ETAPA 01

Instale em todos os servidores

Use a mesma build do ServerRouter em cada nó que participa da rede.

ETAPA 02

Configure um nó por vez

Dê a cada servidor um serverId único, seu próprio host/port e o papel correto.

ETAPA 03

Teste antes de abrir o acesso

Verifique rotas e proteção de backend com contas da equipe antes de depender disso para tráfego público.

ServerRouter é infraestrutura de rede: configure credenciais, hosts, permissões e regras de acesso direto com cuidado. Mantenha backup da configuração de produção antes de alterar vários módulos.

CAPÍTULO 01 · 1 EXEMPLOS

Instalação e função

Identifique o servidor na rede e defina se ele atua como router, backend ou ambos.

01CONFIGURAÇÃO

Identidade e função do servidor

Cada nó da rede precisa de um serverId único e endereço acessível pelos outros servidores.

CONFIGURAÇÃO

{
  "enabled": true,
  "role": "both",
  "serverId": "hub",
  "host": "hub.example.com",
  "port": 5520,
  "maxPlayers": 100,
  "acceptingPlayers": true
}

mods/ServerRouter/config.json

O QUE FAZ

Cada nó da rede precisa de um serverId único e endereço acessível pelos outros servidores.

COMPORTAMENTO IMPORTANTE

role: main ativa roteamento, backend aceita transferências e both combina as duas funções.
serverId deve ser estável e igual ao valor usado nas rotas e módulos de rede.
acceptingPlayers pode remover temporariamente um servidor dos destinos sem desligá-lo.

CAPÍTULO 02 · 1 EXEMPLOS

Banco de dados e heartbeat

Configure MariaDB e a frequência com que cada servidor publica seu estado.

01CONFIGURAÇÃO

MariaDB, heartbeat e estado online

ServerRouter usa MariaDB para compartilhar estado, presença, transferências e módulos de rede.

CONFIGURAÇÃO

{
  "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

O QUE FAZ

ServerRouter usa MariaDB para compartilhar estado, presença, transferências e módulos de rede.

COMPORTAMENTO IMPORTANTE

Todos os servidores da mesma rede devem apontar para o mesmo banco.
heartbeatIntervalSeconds define com que frequência o nó atualiza o estado.
offlineTimeoutSeconds determina quando um nó sem heartbeat é considerado indisponível.

CAPÍTULO 03 · 1 EXEMPLOS

Rotas e comandos

Defina destinos, comandos, aliases, permissões e mensagens das rotas.

01CONFIGURAÇÃO

Rotas, comandos, aliases e permissões

Cada rota liga um comando a um servidor de destino e é validada antes da transferência.

CONFIGURAÇÃO

{
  "routes": [
    {
      "name": "Survival",
      "command": "survival",
      "aliases": [
        "sopravvivenza"
      ],
      "serverId": "survival",
      "host": "survival.example.com",
      "port": 5522,
      "permission": "serverrouter.command.survival"
    }
  ]
}

mods/ServerRouter/config.json → routes[]

O QUE FAZ

Cada rota liga um comando a um servidor de destino e é validada antes da transferência.

COMPORTAMENTO IMPORTANTE

O comando é salvo sem slash no JSON e usado no jogo como /survival.
aliases adiciona nomes alternativos à mesma transferência.
Antes do referral, ServerRouter verifica estado, capacidade e disponibilidade do destino.

CAPÍTULO 04 · 1 EXEMPLOS

Segurança das transferências

Proteja backends e controle autorizações temporárias, rejoin e cooldowns.

01CONFIGURAÇÃO

Proteção de backend e tokens de transferência

Backends podem recusar acesso direto e aceitar apenas jogadores vindos de uma transferência autorizada.

CONFIGURAÇÃO

{
  "allowDirectAccess": false,
  "allowSameServerRejoin": true,
  "sameServerRejoinSeconds": 300,
  "accessTokenTtlSeconds": 60,
  "accessTokenSecret": "",
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20,
  "loginPortalSafetySeconds": 20
}

mods/ServerRouter/config.json

O QUE FAZ

Backends podem recusar acesso direto e aceitar apenas jogadores vindos de uma transferência autorizada.

COMPORTAMENTO IMPORTANTE

Com allowDirectAccess=false, o backend usa a autorização temporária criada pelo servidor de origem.
A whitelist nativa do Hytale continua sendo a autoridade final de acesso.
Cooldowns de chegada evitam retorno acidental por portais logo após login ou transferência.

CAPÍTULO 05 · 1 EXEMPLOS

Portais

Use as mesmas rotas para gerar portais coerentes com as verificações da rede.

01CONFIGURAÇÃO

Portais ligados às rotas

Portais usam destinos configurados no router e mantêm as mesmas verificações de disponibilidade e segurança.

CONFIGURAÇÃO

{
  "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[]

O QUE FAZ

Portais usam destinos configurados no router e mantêm as mesmas verificações de disponibilidade e segurança.

COMPORTAMENTO IMPORTANTE

Não é necessário um segundo destino para o portal: a rota é a fonte comum.
Assets dos portais são gerados pelo plugin e carregados como runtime asset pack.
Se o destino estiver offline, cheio ou indisponível, a transferência é bloqueada.

CAPÍTULO 06 · 1 EXEMPLOS

Sistemas compartilhados

Chat, eventos, lista de jogadores e Presence API compartilham informações entre todos os servidores.

01CONFIGURAÇÃO

Chat e eventos globais

Os servidores podem compartilhar chat e eventos importantes para que Hub, Survival, Dungeon, Creative e outros nós pareçam uma única rede.

CONFIGURAÇÃO

{
  "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

O QUE FAZ

Os servidores podem compartilhar chat e eventos importantes para que Hub, Survival, Dungeon, Creative e outros nós pareçam uma única rede.

COMPORTAMENTO IMPORTANTE

Network Chat encaminha mensagens entre servidores participantes mantendo o nome do servidor de origem e um formato comum configurável.
captureMode define de qual sistema o chat local é capturado; remoteFormat reutiliza formatação disponível e fallbackFormat oferece uma alternativa segura.
serverDisplayNames fornece nomes legíveis como Hub, Survival ou Creative em vez do serverId técnico.
Network Events pode anunciar join, quit e troca de servidor em toda a rede; cada evento é configurável separadamente.
suppressServerSwitchJoinQuit impede que uma troca de servidor pareça uma falsa saída seguida de nova entrada.
quitDelaySeconds ajuda a diferenciar desconexão real de transferência em andamento; respectVanish evita expor jogadores ocultos quando a integração suporta isso.
Network Player List e Presence API compartilham presença com servidores e mods compatíveis sem consultas separadas ao banco para cada integração.

CAPÍTULO 07 · 2 EXEMPLOS

Scoreboard nativo

Configure conteúdo, posição, cores, logo e overrides para mundos ou instâncias dinâmicas.

01CONFIGURAÇÃO

Scoreboard global

O scoreboard nativo é independente e pode ser posicionado em qualquer um dos quatro cantos com offsets em pixels.

CONFIGURAÇÃO

{
  "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

O QUE FAZ

O scoreboard nativo é independente e pode ser posicionado em qualquer um dos quatro cantos com offsets em pixels.

COMPORTAMENTO IMPORTANTE

O scoreboard nativo é opcional e pode ser desativado sem desligar ServerRouter ou os sistemas de rede.
horizontal aceita left:<px> ou right:<px>; vertical aceita top:<px> ou bottom:<px>.
backgroundColor aceita default, none ou cor HEX #RRGGBB.
logo: none esconde o logo. As linhas aceitam formatação e placeholders dinâmicos.
Se preferir scoreboard externo, use placeholders do ServerRouter sem mostrar o nativo.

02CONFIGURAÇÃO

Overrides por mundo e instâncias dinâmicas

Um mundo pode herdar a configuração global e alterar apenas os campos necessários.

CONFIGURAÇÃO

{
  "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

O QUE FAZ

Um mundo pode herdar a configuração global e alterar apenas os campos necessários.

COMPORTAMENTO IMPORTANTE

O matching ignora maiúsculas/minúsculas e suporta * para instâncias com sufixo dinâmico.
Prioridade: nome exato > wildcard mais específico > configuração global.
Um override pode mudar posição, linhas, largura, fundo ou logo sem duplicar o bloco global.

CAPÍTULO 08 · 2 EXEMPLOS

Inventory Sync e ItemQuality

Sincronize inventários com segurança e preserve ItemQuality entre registries diferentes.

01CONFIGURAÇÃO

Inventory Sync

A sincronização de inventário é opcional e usa locks temporários para proteger carregamento, salvamento e transferências concorrentes.

CONFIGURAÇÃO

{
  "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

O QUE FAZ

A sincronização de inventário é opcional e usa locks temporários para proteger carregamento, salvamento e transferências concorrentes.

COMPORTAMENTO IMPORTANTE

Ative somente nos servidores que devem compartilhar o mesmo perfil de inventário.
Locks impedem acessos concorrentes que poderiam causar duplicações ou sobrescritas.
Mantenha debugQualityMapping desativado no uso normal.

02CONFIGURAÇÃO

ItemQuality entre registries diferentes

ServerRouter preserva a identidade semântica das qualidades em vez de depender somente dos índices runtime.

CONFIGURAÇÃO

{
  "itemQualityMapping": {
    "enabled": false,
    "log-to-file": true,
    "log-to-console": false
  }
}

mods/ServerRouter/config.json

O QUE FAZ

ServerRouter preserva a identidade semântica das qualidades em vez de depender somente dos índices runtime.

COMPORTAMENTO IMPORTANTE

Diagnóstico ItemQuality é mais útil quando dois servidores usam registries ou mods diferentes.
Se uma qualidade não existir no destino, o sistema usa fallback seguro e preserva a identidade original quando possível.
Logs de mapping são ferramentas de diagnóstico e não são necessários em uma rede estável.

CAPÍTULO 09 · 1 EXEMPLOS

Placeholders, API e diagnóstico

Integre mods complementares, recarregue o scoreboard e use diagnóstico quando necessário.

01CONFIGURAÇÃO

Placeholders e API para mods complementares

O scoreboard inclui placeholders internos e uma API pública permite que outros mods registrem novos sem patch no ServerRouter.

CONFIGURAÇÃO

{
  "integrations": {
    "api": {
      "enabled": true,
      "cacheSeconds": 10
    },
    "betterScoreBoard": {
      "enabled": false,
      "registerPlaceholders": true
    }
  },
  "scoreboardExample": [
    "{player}",
    "{world}",
    "{tps}",
    "{serverrouter_total_online}",
    "{myplugin_rank}"
  ]
}

Java API + scoreboard.json

O QUE FAZ

O scoreboard inclui placeholders internos e uma API pública permite que outros mods registrem novos sem patch no ServerRouter.

COMPORTAMENTO IMPORTANTE

Placeholders custom ignoram maiúsculas/minúsculas e não podem tomar placeholders internos já resolvidos.
O scoreboard nativo pode ficar desativado: placeholders do ServerRouter podem ser usados por scoreboards ou mods externos compatíveis.
BetterScoreBoard é suportado pela integração dedicada. Se outro scoreboard não reconhecer os placeholders, podemos avaliar uma compatibilidade específica.
A Presence/Network API somente leitura evita que cada mod consulte o banco separadamente.
Para o scoreboard nativo, use /scoreboard reload após mudanças em configuração, logo ou layout.

Antes de usar um exemplo

Os exemplos focam propositalmente em um módulo por vez. Mescle as propriedades mostradas no arquivo correspondente em vez de substituir uma configuração completa por um exemplo parcial.

Credenciais de banco e hosts mostrados aqui são exemplos. Nunca publique senhas ou segredos reais e compartilhe o mesmo banco apenas entre servidores da mesma rede confiável.

A versão pública usa horizontal/vertical para posicionar o scoreboard. Os antigos campos offsetRight/offsetTop de builds de desenvolvimento não fazem parte da configuração documentada.

VOLTAR AO TOPO