VoteRewards (MC Votifier Protocol + Rewards)

VoteRewards

Un plugin de Hytale que implementa el protocolo Votifier V2 para recompensar a los jugadores por votar en listas de servidores.

Características

• Protocolo Votifier V2 – Implementación completa con autenticación basada en tokens y firmas HMAC-SHA256
• Generación Automática de Tokens – Token alfanumérico seguro de 26 caracteres generado en la primera ejecución
• Recompensas Configurables – Ejecuta cualquier comando del servidor como recompensa con soporte para marcadores de posición
• Difusión de Votos – Anuncia los votos a todos los jugadores en línea
• Sistema de Eventos – VoteReceivedEvent para que otros plugins se integren
• Modo de Depuración – Registro detallado para solucionar problemas de recepción de votos

Instalación

• Descarga VoteRewards-1.0.0.jar
• Colócalo en la carpeta plugins de tu servidor Hytale
• Inicia/reinicia tu servidor
• Configura el plugin (ver sección de Configuración)

Configuración

En la primera ejecución, el plugin crea Hytalist_VoteRewards/config.json:

{
  "Port": 8192,
  "Host": "0.0.0.0",
  "Token": "b7tb4nal2sm91dt5uaeumt7d24",
  "RewardCommands": [
    "give {player} diamond 1",
    "give {player} emerald 5"
  ],
  "BroadcastVotes": true,
  "BroadcastMessage": "&a{player} &7ha votado por el servidor! &e/vote",
  "DebugMode": false
}

Opciones de Configuración

Opción	Tipo	Por Defecto	Descripción
Port	Entero	8192	Puerto para que el servidor Votifier escuche
Host	Cadena	"0.0.0.0"	Dirección del host a la que enlazar (0.0.0.0 = todas las interfaces)
Token	Cadena	Generado automáticamente	Token de autenticación de 26 caracteres para sitios de votación
RewardCommands	Array	Ver configuración	Comandos ejecutados cuando un jugador vota
BroadcastVotes	Booleano	true	Si se deben difundir los votos a todos los jugadores
BroadcastMessage	Cadena	Ver configuración	Mensaje difundido cuando alguien vota
DebugMode	Booleano	false	Habilitar registro detallado para solucionar problemas

Marcadores de posición para comandos de recompensa

Utiliza estos marcadores de posición en RewardCommands:

• {player} – Nombre de usuario del jugador que votó
• {service} – Nombre del servicio de votación
• {address} – Dirección IP del votante
• {timestamp} – Marca de tiempo Unix del voto

Ejemplo:

"RewardCommands": [
  "give {player} diamond 1",
  "give {player} gold_ingot 5",
  "broadcast {player} votó en {service}!",
  "title {player} title &6¡Gracias por votar!"
]

Configurando sitios de votación

• Obtén tu token del config.json (generado automáticamente en la primera ejecución)

• Configura tu lista de servidores con estos ajustes:

  • IP/Host: La IP de tu servidor
  • Puerto: El puerto de la configuración (por defecto: puerto del servidor + 1)
  • Token/Clave: Copia el token de config.json
  • Versión del Protocolo: Votifier V2

• Prueba la configuración:

   # Habilita el modo de depuración en config.json primero
   "DebugMode": true

Luego vota en la lista de servidores y revisa los registros de tu servidor para obtener una salida de depuración detallada.

Para desarrolladores

VoteReceivedEvent

Otros plugins pueden escuchar eventos de voto:

@Override
protected void setup() {
    getEventRegistry().register(VoteReceivedEvent.class, this::onVote);
}

private void onVote(VoteReceivedEvent event) {
    Vote vote = event.getVote();

    // Obtener información del voto
    String player = vote.getUsername();
    String service = vote.getServiceName();
    String address = vote.getAddress();
    String timestamp = vote.getTimestamp();

    // Cancelar el voto (previene recompensas por defecto)
    event.setCancelled(true);

    // Manejar el voto con lógica personalizada
    // ...
}

Modelo de Voto

class Vote {
    String getUsername()     // Jugador que votó
    String getServiceName()  // Nombre del servicio de votación
    String getAddress()      // Dirección IP del votante
    String getTimestamp()    // Marca de tiempo del voto
}

Detalles del Protocolo

VoteRewards implementa el Protocolo Votifier V2 que utiliza:

• Autenticación de Desafío-Respuesta – El servidor genera un desafío aleatorio para cada conexión
• Firmas HMAC-SHA256 – Los votos se firman con el token compartido
• Protocolo Binario – Utiliza bytes mágicos 0x733a con mensajes JSON con longitud prefijada
• Estructura JSON Anidada – La firma envuelve una carga útil firmada que contiene los datos del voto

Flujo del Protocolo

• El cliente se conecta al servidor
• El servidor responde con: VOTIFIER 2.0 <desafío-de-16-caracteres>

• El cliente construye el JSON de carga útil con los datos del voto + desafío
• El cliente firma la carga útil con HMAC-SHA256 utilizando el token
• El cliente envía: [mágico:0x733a][longitud:2bytes][json]
• El servidor verifica la firma y el desafío
• El servidor responde con: {"status":"ok"} o {"status":"error"}

Solución de Problemas

Votos no recibidos

• Habilita el modo de depuración en config.json
• Verifica el firewall – Asegúrate de que el puerto de Votifier esté abierto
• Verifica el token – Asegúrate de que el token en la configuración coincida con el que diste a los sitios de votación
• Revisa los registros – Busca mensajes de VoteRewards en la consola del servidor
• Prueba la conexión – Intenta enviar un voto de prueba utilizando una herramienta de prueba de Votifier

Salida del modo de depuración

Cuando DebugMode: true, verás:

[INFO] Desafío enviado: ABC123...
[INFO] Mensaje recibido: {"signature":"...","payload":"..."}
[INFO] Voto recibido: Vote(service=..., username=..., ...)

Si ves advertencias como:

• Firma inválida – Desajuste de token entre el servidor y el sitio de votación
• Desajuste de desafío – Problema de sincronización de reloj o problema de red
• Datos de voto inválidos – Paquete de voto mal formado

Problemas Comunes

“Desajuste de desafío” – Generalmente significa:

• El sitio de votación está utilizando el protocolo Votifier V1 (cambia a V2)
• Problemas de red que causan corrupción de paquetes
• Token incorrecto

“Firma inválida” – Generalmente significa:

• El token no coincide entre la configuración y el sitio de votación
• El token contiene espacios o caracteres adicionales

“Sin respuesta del servidor” – Generalmente significa:

• El puerto de Votifier está bloqueado por el firewall
• El servidor no está en funcionamiento
• Puerto configurado incorrectamente

Compilando desde la Fuente

./gradlew clean jar

Salida: build/libs/VoteRewards-1.0.0.jar

Requisitos

• Servidor Hytale v0.0.1+
• Java 17+

Licencia

Este plugin se proporciona tal cual para su uso con servidores Hytale.

Agradecimientos

• Protocolo basado en la especificación de NuVotifier

Soporte

Para problemas, preguntas o contribuciones, visita el repositorio de GitHub.

Nota: Este plugin es compatible con el protocolo estándar Votifier V2 utilizado por las listas de servidores de Minecraft, lo que facilita la integración con plataformas de votación existentes.