HyTari Studios · Guía oficial de configuración

Server Router

Configura la red entendiendo realmente cada módulo.

Una referencia práctica para Server Router - Network Sync. Recorre los módulos desde la identidad del servidor y las rutas hasta los sistemas compartidos, el scoreboard nativo y la sincronización opcional del inventario. Cada sección combina JSON copiable con una explicación de su funcionamiento.

INICIAR LA GUÍA PÁGINA DEL MOD

ANTES DE EMPEZAR

Primeros pasos

PASO 01

Instala en cada servidor

Usa la misma build de ServerRouter en cada nodo que participe en la red.

PASO 02

Configura un nodo cada vez

Asigna a cada servidor un serverId único, su host/port y el rol correcto.

PASO 03

Prueba antes de abrir el acceso

Verifica rutas y protección backend con cuentas del staff antes de depender de ellas para tráfico público.

ServerRouter es infraestructura de red: configura credenciales, hosts, permisos y reglas de acceso directo con cuidado. Conserva una copia de seguridad de la configuración de producción antes de cambiar varios módulos.

CAPÍTULO 01 · 1 EJEMPLOS

Instalación y rol

Identifica el servidor en la red y decide si actúa como router, backend o ambos.

01CONFIGURACIÓN

Identidad y rol del servidor

Cada nodo de la red necesita un serverId único y una dirección accesible por los demás servidores.

CONFIGURACIÓN

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

mods/ServerRouter/config.json

QUÉ HACE

Cada nodo de la red necesita un serverId único y una dirección accesible por los demás servidores.

COMPORTAMIENTO IMPORTANTE

role: main habilita el enrutamiento, backend acepta transferencias y both combina ambos roles.
serverId debe ser estable y coincidir con el valor usado en rutas y módulos de red.
acceptingPlayers puede sacar temporalmente un servidor de los destinos sin apagarlo.

CAPÍTULO 02 · 1 EJEMPLOS

Base de datos y heartbeat

Configura MariaDB y la frecuencia con la que cada servidor publica su estado.

01CONFIGURACIÓN

MariaDB, heartbeat y estado online

ServerRouter usa MariaDB para compartir estado, presencia, transferencias y módulos de red.

CONFIGURACIÓN

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

QUÉ HACE

ServerRouter usa MariaDB para compartir estado, presencia, transferencias y módulos de red.

COMPORTAMIENTO IMPORTANTE

Todos los servidores de la misma red deben apuntar a la misma base de datos.
heartbeatIntervalSeconds define cada cuánto se actualiza el estado del nodo.
offlineTimeoutSeconds determina cuándo un nodo sin heartbeat se considera no disponible.

CAPÍTULO 03 · 1 EJEMPLOS

Rutas y comandos

Define destinos, comandos, alias, permisos y mensajes de ruta.

01CONFIGURACIÓN

Rutas, comandos, alias y permisos

Cada ruta enlaza un comando con un servidor de destino y se valida antes de transferir.

CONFIGURACIÓN

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

mods/ServerRouter/config.json → routes[]

QUÉ HACE

Cada ruta enlaza un comando con un servidor de destino y se valida antes de transferir.

COMPORTAMIENTO IMPORTANTE

El comando se guarda sin slash en JSON y se usa en juego como /survival.
aliases añade nombres alternativos al mismo traslado.
Antes del referral, ServerRouter verifica estado, capacidad y disponibilidad del destino.

CAPÍTULO 04 · 1 EJEMPLOS

Seguridad de transferencias

Protege los backend y controla autorizaciones temporales, rejoin y cooldowns.

01CONFIGURACIÓN

Protección backend y tokens de transferencia

Los backend pueden rechazar acceso directo y aceptar solo jugadores procedentes de una transferencia autorizada.

CONFIGURACIÓN

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

mods/ServerRouter/config.json

QUÉ HACE

Los backend pueden rechazar acceso directo y aceptar solo jugadores procedentes de una transferencia autorizada.

COMPORTAMIENTO IMPORTANTE

Con allowDirectAccess=false, el backend usa la autorización temporal generada por el servidor de origen.
La whitelist nativa de Hytale sigue siendo la autoridad final de acceso.
Los cooldowns de llegada evitan rebotes accidentales en portales justo después del login o transferencia.

CAPÍTULO 05 · 1 EJEMPLOS

Portales

Usa las mismas rutas para generar portales coherentes con los controles de red.

01CONFIGURACIÓN

Portales ligados a las rutas

Los portales usan los destinos configurados en el router y mantienen las mismas comprobaciones de disponibilidad y seguridad.

CONFIGURACIÓN

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

QUÉ HACE

Los portales usan los destinos configurados en el router y mantienen las mismas comprobaciones de disponibilidad y seguridad.

COMPORTAMIENTO IMPORTANTE

No hace falta un segundo destino para el portal: la ruta es la fuente común.
Los assets de los portales los genera el plugin y se cargan como runtime asset pack.
Si el destino está offline, lleno o no disponible, la transferencia se bloquea.

CAPÍTULO 06 · 1 EJEMPLOS

Sistemas compartidos

Chat, eventos, lista de jugadores y Presence API comparten información entre todos los servidores.

01CONFIGURACIÓN

Chat y eventos globales

Los servidores pueden compartir chat y eventos importantes para que Hub, Survival, Dungeon, Creative y otros nodos se perciban como una única red.

CONFIGURACIÓN

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

QUÉ HACE

Los servidores pueden compartir chat y eventos importantes para que Hub, Survival, Dungeon, Creative y otros nodos se perciban como una única red.

COMPORTAMIENTO IMPORTANTE

Network Chat reenvía mensajes entre servidores participantes manteniendo el nombre del servidor de origen y un formato común configurable.
captureMode define de dónde se captura el chat local; remoteFormat reutiliza el formato disponible y fallbackFormat proporciona una alternativa segura.
serverDisplayNames asigna nombres legibles como Hub, Survival o Creative en lugar del serverId técnico.
Network Events puede anunciar join, quit y cambios de servidor en toda la red, con cada tipo activable por separado.
suppressServerSwitchJoinQuit evita que un cambio de servidor parezca una salida de la red seguida de una nueva entrada.
quitDelaySeconds ayuda a distinguir una desconexión real de una transferencia en curso; respectVanish evita exponer jugadores ocultos cuando la integración lo permite.
Network Player List y Presence API comparten presencia con servidores y mods compatibles sin que cada integración consulte la base por separado.

CAPÍTULO 07 · 2 EJEMPLOS

Scoreboard nativo

Configura contenido, posición, colores, logo y overrides para mundos o instancias dinámicas.

01CONFIGURACIÓN

Scoreboard global

El scoreboard nativo es independiente y puede situarse en cualquiera de las cuatro esquinas con offsets en píxeles.

CONFIGURACIÓN

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

QUÉ HACE

El scoreboard nativo es independiente y puede situarse en cualquiera de las cuatro esquinas con offsets en píxeles.

COMPORTAMIENTO IMPORTANTE

El scoreboard nativo es opcional: puede desactivarse sin desactivar ServerRouter ni sus sistemas de red.
horizontal acepta left:<px> o right:<px>; vertical acepta top:<px> o bottom:<px>.
backgroundColor acepta default, none o un color HEX #RRGGBB.
logo: none oculta el logo. Las líneas admiten formato y placeholders dinámicos.
Si prefieres un scoreboard externo, puedes usar los placeholders de ServerRouter sin mostrar el nativo.

02CONFIGURACIÓN

Overrides por mundo e instancias dinámicas

Un mundo puede heredar la configuración global y cambiar solo los campos necesarios.

CONFIGURACIÓN

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

QUÉ HACE

Un mundo puede heredar la configuración global y cambiar solo los campos necesarios.

COMPORTAMIENTO IMPORTANTE

El matching no distingue mayúsculas/minúsculas y admite * para instancias con sufijo dinámico.
Prioridad: nombre exacto > wildcard más específico > configuración global.
Un override puede cambiar posición, líneas, ancho, fondo o logo sin duplicar todo el bloque global.

CAPÍTULO 08 · 2 EJEMPLOS

Inventory Sync e ItemQuality

Sincroniza inventarios de forma segura y conserva ItemQuality entre registries diferentes.

01CONFIGURACIÓN

Inventory Sync

La sincronización de inventario es opcional y usa locks temporales para proteger carga, guardado y transferencias concurrentes.

CONFIGURACIÓN

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

QUÉ HACE

La sincronización de inventario es opcional y usa locks temporales para proteger carga, guardado y transferencias concurrentes.

COMPORTAMIENTO IMPORTANTE

Actívala solo en servidores que deban compartir el mismo perfil de inventario.
Los locks evitan accesos concurrentes que podrían causar duplicaciones o sobrescrituras.
Mantén debugQualityMapping desactivado durante el uso normal.

02CONFIGURACIÓN

ItemQuality entre registries diferentes

ServerRouter conserva la identidad semántica de las calidades en vez de depender solo de índices runtime.

CONFIGURACIÓN

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

mods/ServerRouter/config.json

QUÉ HACE

ServerRouter conserva la identidad semántica de las calidades en vez de depender solo de índices runtime.

COMPORTAMIENTO IMPORTANTE

El diagnóstico ItemQuality es especialmente útil cuando dos servidores tienen registries o mods distintos.
Si una calidad no existe en el destino, el sistema usa un fallback seguro y conserva la identidad original cuando es posible.
Los logs de mapping son herramientas de diagnóstico y no son necesarios en una red estable.

CAPÍTULO 09 · 1 EJEMPLOS

Placeholders, API y diagnóstico

Integra mods complementarios, recarga el scoreboard y usa diagnóstico cuando haga falta.

01CONFIGURACIÓN

Placeholders y API para mods complementarios

El scoreboard incluye placeholders internos y una API pública permite a otros mods registrar nuevos sin parchear ServerRouter.

CONFIGURACIÓN

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

Java API + scoreboard.json

QUÉ HACE

El scoreboard incluye placeholders internos y una API pública permite a otros mods registrar nuevos sin parchear ServerRouter.

COMPORTAMIENTO IMPORTANTE

Los placeholders custom no distinguen mayúsculas/minúsculas y no pueden apropiarse de placeholders internos ya resueltos.
El scoreboard nativo puede permanecer desactivado: los placeholders de ServerRouter pueden usarse en scoreboards o mods externos compatibles.
BetterScoreBoard está soportado mediante la integración dedicada. Si otro scoreboard no reconoce los placeholders, se puede evaluar una compatibilidad específica.
La Presence/Network API de solo lectura evita que cada mod consulte la base de datos por separado.
Para el scoreboard nativo, usa /scoreboard reload después de cambios de configuración, logo o layout.

Antes de usar un ejemplo

Los ejemplos se centran deliberadamente en un módulo cada vez. Integra las propiedades mostradas en el archivo correspondiente en vez de sustituir una configuración completa por un ejemplo parcial.

Las credenciales de base de datos y hosts mostrados son ejemplos. No publiques contraseñas o secretos reales y comparte la misma base solo entre servidores de una red de confianza.

La versión pública usa horizontal/vertical para posicionar el scoreboard. Los antiguos campos offsetRight/offsetTop de builds de desarrollo no forman parte de la configuración documentada.

VOLVER ARRIBA