Hyvote

Hyvote

A secure vote listener plugin for Hytale that enables voting sites to send vote notifications to your server.

Features

Hybrid Encryption Protocol: Uses RSA + AES-256 encryption for secure, flexible vote transmission

Configurable Actions: Execute commands automatically when votes are received or when players join

Developer API: Fire custom events and integrate vote handling into your own plugins

Replay Protection: Built-in timestamp and nonce validation prevents duplicate votes

Multiple Protocol Support: Version field allows for future protocol updates without breaking existing integrations

Installation

Download the latest release

Place Hyvote.jar in your server's plugins folder

Start your server - settings.json will be generated automatically

Configure your settings (see below)

Share your public RSA key with voting sites (found in keys/public.pem)

Configuration

Settings are stored in settings.json:

{ "port": 2250, "database": { "type": "sqlite", "host": "localhost", "port": 3306, "username": "hytale", "password": "supersecretdatabasepassword", "database": "hyvote" }, "actions": [ { "on": "vote", "type": "command", "command": "say ${player} just voted on ${voteSite}!" }, { "on": "join", "type": "command", "command": "say Welcome back ${player}! Thanks for voting on ${voteSite}" } ] } Configuration Options

port: The TCP port the vote listener binds to (default: 2250)

database: The configuration options for the database

actions: Array of actions to execute when votes are received

Database Properties

Databases are used to track which nonces have been used and deliver votes for actions that require the user to be online but are recieved when offline.

type: The database type to use (supported - MySQL, MariaDB, SQLite, PostgreSQL)

host: The host of the database (ignored when using SQLite)

port: The port that the database listens on (ignored when using SQLite)

username: The username for the database user (ignored when using SQLite)

password: The password for the database user (ignored when using SQLite)

database: The database to use (ignored when using SQLite)

Action Properties

on: When to execute the action

vote - Immediately after vote is processed

join - When the player joins (or immediately if already online)

type: Type of action (currently only command is supported)

command: The command to execute. Supports placeholders:

${player} - The voter's username

${voteSite} - The name of the voting site

${uuid} - The voter's UUID

${timestamp} - Vote timestamp

Developer API

Hyvote provides an event system for plugin developers to integrate custom vote handling.

Listening for Votes

import uk.co.deveroonie.hyvote.api.VoteEventManager; import uk.co.deveroonie.hyvote.api.VoteReceivedEvent;

// Register your listener VoteEventManager.registerListener(event -> { Vote vote = event.getVote();

// Access vote data String player = vote.playerName; String site = vote.voteSite; long timestamp = vote.timestamp;

// Optionally cancel default processing event.setCancelled(true);

// Implement your custom logic myPlugin.giveCustomReward(player); }); Vote Object

public class Vote { public String uuid; // Player UUID public String playerName; // Player username public String voteSite; // Voting site identifier public long timestamp; // Unix timestamp public String nonce; // Replay protection nonce } Unregistering Listeners

VoteListener myListener = event -> { /* ... */ }; VoteEventManager.registerListener(myListener);

// Later... VoteEventManager.unregisterListener(myListener); Protocol Specification

Hyvote uses a custom binary protocol (HV01) for vote transmission:

Message Format

[4 bytes] Magic: "HV01" [4 bytes] Encrypted AES key length (big-endian int) [N bytes] RSA-encrypted AES-256 key [4 bytes] Encrypted payload length (big-endian int) [M bytes] AES-encrypted JSON payload Encryption

Generate a random 256-bit AES key

Encrypt vote JSON with AES-256-CBC (include 16-byte IV prepended to ciphertext)

Encrypt the AES key with the server's RSA public key (PKCS1 or OAEP padding)

Package and send according to the message format above

JSON Payload Structure

{ "uuid": "player-uuid-here", "playerName": "PlayerName", "voteSite": "VotingSiteName", "timestamp": 1737000000000, "nonce": "unique-random-string" } Client Libraries

Official client libraries coming soon for:

Java

JavaScript/Node.js

Security

All vote data is encrypted end-to-end using hybrid RSA + AES encryption

Replay attacks are mitigated through nonces

Malformed messages are rejected before processing

Support

For issues, feature requests, or protocol questions, please visit our GitHub repository.

License

MIT