SimpleVotifier for Hytale

🌍 English | Français | Español | Deutsch | Italiano | Português | Русский | Українська | 中文 | 日本語

A modern voting plugin for Hytale servers that allows server lists to notify your server when players vote. Features an integrated reward system, multi-language support, and secure HMAC authentication.

✨ Features

Core Features

• 🔐 HMAC-SHA256 authentication for secure vote verification
• 🎁 Built-in reward system with customizable tiers
• 🌍 10 languages supported (EN, FR, ES, DE, IT, PT, RU, UK, ZH, JA)
• 📢 Vote broadcasts to all online players
• 📅 Monthly vote resets for competitive leaderboards
• 🔌 Event-based API for third-party rewards plugins

Reward System (optional)

• ✅ Execute commands on every vote
• 🎯 Configure vote count tiers with unique rewards
• 💾 Pending rewards system (players can claim later with /rewards)
• 📊 Track individual player vote counts
• 🔄 Optional monthly reset for fresh competitions

📋 Requirements

• Hytale Server
• Java 25
• WebServer plugin
• Maven 3.9+ (for building from source)

🚀 Installation

1. Download the latest SimpleVotifier.jar from the releases page
2. Place the JAR file in your server's mods/ directory
3. Ensure the WebServer plugin plugin is installed
4. Start your server to generate the default configuration
5. Configure the plugin (see Configuration section)
6. Restart your server

⚙️ Configuration

After first run, a configuration file will be created at mods/SimpleVotifier/config.json:

{
  "language": "en",
  "token": "AbCdEfGh123456789XyZ0123",
  "allowedIps": [],
  "logVotes": true,
  "broadcastVotes": true,
  "rewards": {
    "enabled": false,
    "monthlyReset": true,
    "everyVoteCommands": [
      "give {player} Plant_Crop_Carrot_Item"
    ],
    "tiers": [
      {
        "votesRequired": 10,
        "commands": ["give {player} Container_Bucket"]
      },
      {
        "votesRequired": 50,
        "commands": ["give {player} Armor_Iron_Head"]
      },
      {
        "votesRequired": 100,
        "commands": ["give {player} Rock_Gem_Diamond"]
      }
    ]
  },
  "leaderboard": {
    "enabled": true,
    "format": "html",
    "showVoteSites": true
  },
  "voteSites": [
    {
      "service": "Top-Games",
      "url": "https://top-games.net/hytale/my-server"
    },
    {
      "service": "Top-Serveurs",
      "url": "https://top-serveurs.net/hytale/my-server"
    }
  ]
}

Configuration Options

Main Settings

• language (string): Language code - en, fr, es, de, it, pt, ru, uk, zh, ja
• token (string): Secure token for HMAC authentication (auto-generated)
• allowedIps (array): IP whitelist (empty = allow all)
• logVotes (boolean): Log votes to console
• broadcastVotes (boolean): Announce votes to all players
• voteSites (array): List of vote sites with service (name) and url (link)

Reward System

• rewards.enabled (boolean): Enable/disable reward system
• rewards.monthlyReset (boolean): Reset vote counts on the 1st of each month
• rewards.everyVoteCommands (array): Commands executed on every vote
• rewards.tiers (array): Vote milestone rewards

Leaderboard

• leaderboard.enabled (boolean): Enable/disable leaderboard endpoint (default: false)
• leaderboard.format (string): Output format for leaderboard - html or json (default: html)
• leaderboard.showVoteSites (boolean): Show/hide vote sites section on leaderboard (default: true)
• leaderboard.limit (int): Maximum number of voters to display (default: 10, max: 10000)

Placeholders:

• {player} - Replaced with the voter's username

🎮 Player Commands

/rewards

Claim pending vote rewards.

Usage: /rewards

Output:

• Displays number of rewards claimed
• Executes all pending reward commands

/vote

List available vote sites configured in config.

Usage: /vote

Output:

• Displays all configured vote sites with their URLs

/voteinfo

View your vote statistics and tier progress.

Usage: /voteinfo

Output:

• Total vote count
• Pending rewards count
• Tier progress with status (reached/not reached)

🌍 Supported Languages

Code	Language	Code	Language
en	English	pt	Portuguese
fr	French	ru	Russian
es	Spanish	uk	Ukrainian
de	German	zh	Chinese
it	Italian	ja	Japanese

Change the language setting in config.json to switch languages.

🔌 Plugin API

Third-party plugins can listen to vote events via the Hytale EventBus:

import com.hypixel.hytale.server.core.HytaleServer;
import net.top_games.hytale.plugins.simplevotifier.VoteEvent;

public class MyPlugin extends JavaPlugin {

    @Override
    protected void setup() {
        HytaleServer.get().getEventBus()
            .listenFor(VoteEvent.class, null)
            .listen(this::onVote);
    }

    private void onVote(VoteEvent event) {
        String username = event.getUsername();
        String service = event.getServiceName();

        getLogger().atInfo().log(username + " voted on " + service);
        // Add your custom logic here
    }
}

VoteEvent API

public class VoteEvent implements IEvent<Void> {
    public String getServiceName();  // Voting service name
    public String getUsername();     // Player username
    public Instant getTimestamp();   // Vote timestamp
}

Note: When the VoteRewards module is enabled, it automatically handles rewards. Disable it (rewards.enabled: false) if you want full control via your own rewards plugin.

🐛 Troubleshooting

Plugin not loading

• ✅ Verify WebServer plugin is installed
• ✅ Check server logs for errors

Votes not received

• ✅ Verify HMAC signature is correctly generated
• ✅ Check allowedIps configuration
• ✅ Review server logs for error messages

Rewards not given

• ✅ Ensure rewards.enabled is true
• ✅ Check command syntax in configuration
• ✅ Verify player is online or use /rewards to claim

Monthly reset not working

• ✅ Confirm monthlyReset is enabled
• ✅ Check last_reset.txt file for last reset date
• ✅ Reset triggers at first vote of new month

📡 Vote Endpoint (for server lists owners)

Endpoint URL

POST https://your-server:port/Top-Games/SimpleVotifier/vote

Request Format

Headers:

Content-Type: application/json

Body:

{
  "payload": {
    "serviceName": "MyServerList",
    "username": "Steve"
  },
  "signature": "base64-encoded-hmac-sha256-signature"
}

HMAC Signature

Generate the signature using HMAC-SHA256.

Example Request (PHP)

<?php
$url = "https://localhost:8080/Top-Games/SimpleVotifier/vote";
$token = "AbCdEfGh123456789XyZ0123";

$payload = [
    "serviceName" => "MyServerList",
    "username" => "Steve"
];

$signature = base64_encode(hash_hmac('sha256', json_encode($payload), $token, true));

$payloadJson = json_encode([
    "payload" => $payload,
    "signature" => $signature
], JSON_UNESCAPED_SLASHES);


$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payloadJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Response Format

Success (200 OK):

{
  "status": "success"
}

Test vote (200 OK):

{
  "status": "test-success"
}

Errors:

• 400: Missing username or invalid JSON
• 401: Invalid or missing signature
• 403: IP not allowed
• 503: VoteRewards module disabled (if applicable)

🏆 Leaderboard Endpoint

The leaderboard endpoint displays top voters on your server.

Configuration

To use the leaderboard, enable it in your config.json:

  "leaderboard": {
    "enabled": true,
    "format": "html",
    "showVoteSites": true,
    "limit": 10
  },
    {
      "service": "Top-Serveurs",
      "url": "https://top-serveurs.net/hytale"
    }
  ]
}

• leaderboard.enabled: Set to true to enable leaderboard (disabled by default)
• leaderboard.format: Choose output format - html or json (HTML by default)
• leaderboard.voteSites: Array of vote sites to display on the leaderboard (optional). Each site must have service (name) and url (link)

Note: The HTML template file will be created at mods/SimpleVotifier/leaderboard.html on first run. You can customize this file to change the appearance of your leaderboard.

Endpoint URL

GET https://your-server:port/Top-Games/SimpleVotifier/leaderboard

The number of voters displayed is controlled by the leaderboard.limit configuration option in your config.json file.

Response Format

The response format depends on the configuration:

JSON Format

Success (200 OK):

{
  "success": true,
  "total": 10,
  "limit": 10,
  "voters": [
    {
      "rank": 1,
      "username": "Steve",
      "votes": 42
    },
    {
      "rank": 2,
      "username": "Alex",
      "votes": 38
    }
  ]
}

HTML

Errors:

• 503: Leaderboard disabled or VoteRewards module disabled

📝 License

This project is licensed under the MIT License.

💬 Support

For issues, questions, or feature requests, please open an issue on GitHub or on our contact form at Top-Games.