Selector — Plugin de selección de servidores (Paper + Velocity)

Plugin para Paper 1.21+ que permite cambiar entre servidores de una red Velocity mediante GUIs interactivas, conteo de jugadores en tiempo real y cola de lobbies con enrutamiento inteligente.

Características

Selector de servidores

• GUI configurable (tamaño, bordes, botón cerrar, info del jugador)
• Conteo de jugadores por servidor vía plugin messaging (PlayerCountAll)
• Ítem en hotbar (slot configurable) + comando /servidores
• Iconos por material o cabezas con textura (URL, hash, base64, jugador)
• Barra de progreso de ocupación en cada servidor

Cola de lobbies (Velocity)

• GUI dedicada con estados visuales en tiempo real:
  • DIAMOND_BLOCK → lobby disponible (cupo libre)
  • RED_CONCRETE → lleno, offline o deshabilitado
• Refresco automático mientras el menú está abierto (sincronizado con Velocity)
• Modos de enrutamiento:
  • manual: solo entra al lobby elegido si tiene cupo
  • smart: si está lleno, busca otro lobby (fallback-server + cadena global)
• Ítem abridor en slot 8 (configurable) + comando /lobbies
• Documentación detallada: docs/LOBBY_VELOCITY.md

Formato de texto

• MiniMessage en mensajes, títulos y GUIs (<green>, <bold>, <gradient:...>, etc.)
• Compatibilidad con hex legacy (#RRGGBB) y códigos &

Otros

• Protección anti-drop del ítem selector y del abridor de lobbies
• Títulos y sonidos al conectar
• Recarga en caliente con /reload

Requisitos

Componente	Versión
Java	21+
Servidor backend	Paper 1.21+
Proxy	Velocity 3.0+
Plugin en Velocity	Debe implementar el canal serverconnector:main (p. ej. plugin Core)

Los nombres en server-name / fallback-server deben coincidir con [servers] en velocity.toml.

Instalación

mvn clean package
# JAR: target/Selector-1.0.jar

1. Copia el JAR en plugins/ del servidor Paper (backend detrás de Velocity).
2. Reinicia o recarga el servidor.
3. Edita plugins/Selector/config.yml.
4. Asegura que el proxy responda a PlayerCountAll y ejecute Connect en el mismo canal.

Ejemplo velocity.toml

[servers]
lobby1 = "127.0.0.1:25565"
lobby2 = "127.0.0.1:25566"
lobby3 = "127.0.0.1:25567"
vanilla = "127.0.0.1:25568"

Comandos y permisos

Comando	Permiso	Descripción
/servidores	selector.use	Abre el selector de servidores
/lobbies	selector.lobbies	Abre la cola de lobbies
/reload	selector.reload	Recarga config.yml

Uso en juego

Slot (por defecto)	Ítem	Acción
4	Brújula (selector)	Click → GUI de servidores
8	Esmeralda (lobbies)	Click → GUI de cola de lobbies

Configuración (config.yml)

El archivo se divide en secciones independientes (no están duplicadas):

Sección	Función
gui	Apariencia del selector de servidores
servers	Servidores del selector (slot, icono, server-name)
lobby-routing	Reglas globales: modo click, refresco, cadena smart
lobby-gui	Apariencia de la GUI de lobbies (materiales, lore)
lobbies	Definición de cada lobby (cupo, fallback, slot)
lobby-opener-item	Ítem del slot 8
selector-item	Ítem del slot 4
messages / titles / sounds	Textos y efectos

Enrutamiento de lobbies (lobby-routing + lobbies)

lobby-routing:
  click-mode: smart          # manual | smart
  refresh-interval-ticks: 20 # actualización en GUI abierta (~1 s)
  auto-route-chain:
    - lobby1
    - lobby2
    - lobby3

lobbies:
  lobby1:
    enabled: true
    slot: 11
    name: "<green><bold>Lobby #1"
    description: "<gray>Lobby principal"
    server-name: "lobby1"       # nombre en velocity.toml
    fallback-server: "lobby2"  # respaldo Velocity (modo smart)
    max-players: 100

Ver flujos y estados en docs/LOBBY_VELOCITY.md.

Iconos de cabeza (servers / gui)

Formato en icon	Ejemplo
Material	GRASS_BLOCK
URL de textura	http://textures.minecraft.net/texture/...
Hash	texture:8a49aca3...
Base64 (session profile)	base64:eyJ0ZXh0dXJlcyI6...
Jugador	player:Notch

MiniMessage

messages:
  welcome: "<gradient:#00ff00:#ffff00>¡Bienvenido!"
  connecting: "<green>✈ Conectando a <white>{server}<green>..."

lobby-gui:
  lobby-items:
    full-status: "<red>✖ Lleno"
    click-available: "<yellow><bold>▶ Click para entrar"

Variables en lore / mensajes

Variable	Uso
{player}	Nombre del jugador
{server}	Servidor actual o destino
{ping}	Ping del jugador
{description}	Descripción del servidor/lobby
{players}	Conteo actual/máximo
{current} / {max}	Jugadores actuales / límite
{status}	Texto de estado del lobby
{action}	Línea de acción (click)
{lobby}	Clave del lobby en config

Comunicación con Velocity

Canal: serverconnector:main

Subcanal	Dirección	Descripción
PlayerCountAll	Paper → Velocity	Solicita todos los conteos
PlayerCountAll	Velocity → Paper	Lista serverName + count
PlayerCount	Velocity → Paper	Actualización de un servidor
Connect	Paper → Velocity	Envía al jugador a serverName

Estructura del proyecto

src/main/java/cl/xgamers/selector/
├── Selector.java              # Plugin principal, eventos, selector GUI
├── LobbyGUI.java              # GUI de lobbies + refresco en tiempo real
├── lobby/
│   ├── LobbyRoutingService.java
│   ├── LobbyState.java
│   ├── LobbyDefinition.java
│   └── LobbyConnectResult.java
├── velocity/
│   └── VelocityBridge.java
└── utils/
    ├── Colorize.java          # MiniMessage
    ├── Heads.java             # Cabezas (PlayerProfile / base64)
    └── Hex.java
docs/
└── LOBBY_VELOCITY.md          # Lógica de cola y Velocity

Desarrollo

mvn clean package

Dependencias principales (pom.xml)

• paper-api 1.21.10 (provided)
• FastInv 3.1.1 (shaded)
• Mojang authlib (provided, cabezas vía Paper API)

Solución de problemas

El GUI no abre o el conteo es 0

• Jugadores deben entrar por Velocity (no standalone).
• Plugin proxy con canal serverconnector:main instalado y activo.
• server-name en config = clave en velocity.toml.

Lobbies siempre en concreto rojo (offline)

• El proxy no devuelve ese servidor en PlayerCountAll.
• Revisa logs al abrir la GUI (timeout 10 ticks usa caché vacía).

Error MiniMessage / colores raros

• Usa solo tags MiniMessage en config (<gray>, no mezclar con § pegado a tags).
• Tras cambiar config: /reload o reinicio.

Click en lobby lleno no redirige

• lobby-routing.click-mode debe ser smart.
• Comprueba que otro lobby tenga cupo y esté en auto-route-chain o como fallback-server.

Licencia

MIT — ver LICENSE.

Autores

• AeroSama — desarrollo principal
• _aero98 — colaborador
• blancocl — documentación

Web: blancocl.vercel.app