Setup Guide

HyVotifier Installation & Setup

Everything you need to install HyVotifier on your Hytale server and connect it to Hytale Realm so your players are automatically rewarded when they vote.

Overview

HyVotifier is a powerful Votifier mod for Hytale servers built by ogfabio. It supports both the V1 (RSA) and V2 (HMAC/Token) Votifier protocols and comes packed with features to reward players, track votes, and grow your community.

Reward commands on every vote

RNG rewards with weighted chances

On-screen vote notifications

Vote reminders for daily voting

Broadcast announcements server-wide

Custom sounds on vote

Custom vote GUI with clickable links

Offline voting with /claimvotes

Vote leaderboard & milestones

Vote forwarding for networks

MiniMessage color formatting

V1 (RSA) and V2 (HMAC) protocol support

Download on CurseForge

How It Works

When a player votes for your server on Hytale Realm, we forward that vote to your game server using the Votifier protocol. HyVotifier receives it and handles rewards, notifications, and tracking.

Player Votes

Clicks "Vote" on your Hytale Realm server page

Hytale Realm

Sends a signed vote to your server's votifier port

HyVotifier

Receives the vote, runs reward commands, tracks stats

Player Rewarded

Items, messages, notifications & sounds delivered

Installation

Download HyVotifier

Get the latest version from CurseForge.

Download on CurseForge

Add to your server

Place the downloaded .jar file into your server's mods/ folder.

your-server/mods/HyVotifier.jar

Start your server

Start or restart your server. On first run, HyVotifier creates its configuration files and generates RSA keys for the V1 protocol.

Generated file structure

mods/HSL_Votifier/
├── config.json           # Main config (host, port, tokens)
├── rewards.json          # Reward commands, messages, RNG rewards
├── notification.json     # On-screen vote notifications
├── voteReminder.json     # Daily vote reminder settings
├── voteCommand.json      # /vote command & GUI config
├── sound.json            # Vote sound settings
├── offlineVoting.json    # Offline vote claiming
├── voteForwarding.json   # Network vote forwarding
├── voteMilestones.json   # Vote milestone rewards
└── rsa/
    ├── public.key        # RSA public key (for V1 protocol)
    └── private.key       # RSA private key (keep secret!)

General Setup

The main configuration lives in config.json. This controls the votifier listener and authentication tokens.

config.jsonJSON

{
  "BindHost": "0.0.0.0",
  "BindPort": 8192,
  "DisableV1Protocol": false,
  "DebugMode": false,
  "Tokens": {
    "hytale-realm.com": "YourTokenHere"
  }
}

BindHost — The IP the votifier listens on. Leave at 0.0.0.0 to use your server's public IP.
BindPort — The port used to listen for votes. Default is 8192.
DisableV1Protocol — Set to true to only accept V2 protocol votes.
DebugMode — Enable verbose logging for troubleshooting.
Tokens — V2 protocol tokens. Each voting site provides a serviceName and token. See the Connect to Hytale Realm section below.

Tip: Use /plugin reload HSL:Votifier to reload the plugin after editing config files without restarting your server.

Connect to Hytale Realm

Hytale Realm uses the V2 protocol to send votes to your server. You need to configure a shared token so your server can verify votes are authentic.

Add a token for Hytale Realm

Open config.json and add a token entry for hytale-realm.com in the Tokens section. Choose any secure string as your token.

config.json - Tokens sectionJSON

"Tokens": {
  "hytale-realm.com": "p+C1yPX1c2sBEzUWXdiQBD3+M7ESyV34Z30vnbDvo4g="
}

Enter settings on Hytale Realm

Go to your Server Toolbox on Hytale Realm, navigate to the Votifier tab, and enter the same token along with your votifier port.

Token:p+C1yPX1c2sBEzU...

Port:8192

Open Server Toolbox

Test the connection

Click "Test Connection" in your Server Toolbox. This sends a test vote to confirm everything is configured correctly.

Connection Successful!

Test vote sent and acknowledged. You're all set to receive votes.

Warning: The token must match exactly between your config.json and your Server Toolbox on Hytale Realm. Any mismatch will cause an "Invalid signature" error.

Rewards

Configure rewards in rewards.json. You can run console commands on every vote, send messages to the voter, broadcast to the server, and set up RNG-based rare rewards.

rewards.jsonJSON

{
  "RewardCommands": [
    "give %player% Food_Wildmeat_Cooked --quantity=10",
    "give %player% Potion_Health_Small --quantity=3"
  ],
  "RewardMessages": [
    "<gray>Thanks for your vote on <gold>%from%</gold>. <green>Enjoy your rewards!</green>"
  ],
  "BroadcastWhenOffline": false,
  "RewardBroadcasts": [
    "<gray>Player <gradient:red:yellow:green:blue:purple>%player%</gradient> has voted for our server!</gray>"
  ],
  "RngRewardsEnabled": true,
  "RngRewardsNothingChance": 0.0,
  "RngRewards": [
    {
      "Percentage": 10.0,
      "Commands": [
        "give %player% Food_Popcorn --quantity=25"
      ],
      "BroadcastMessages": [
        "<gray>Player <gold>%player%</gold> received a special reward for voting! <dark_gray>(%chance%% Chance)"
      ],
      "Messages": [
        "<green>You received <gold>Popcorn</gold> as a special voting reward!"
      ]
    },
    {
      "Percentage": 5.0,
      "Commands": [
        "give %player% Ore_Adamantite --quantity=12"
      ],
      "BroadcastMessages": [
        "<gray>Player <gold>%player%</gold> received a <green>rare reward</green> for voting! <dark_gray>(%chance%% Chance)"
      ],
      "Messages": [
        "<green>You received <gold>Adamantite Ore</gold> as a <green>rare</green> voting reward!"
      ]
    }
  ]
}

Configuration Reference

RewardCommands — Commands executed in the console on every vote. Use %player% for the voter's name.
RewardMessages — Messages sent directly to the voter. Supports %player% and %from% (voting site).
RewardBroadcasts — Messages broadcast to all online players.
BroadcastWhenOffline — When true, broadcasts are sent even if the voter is offline.
RngRewardsEnabled — Enable/disable the random reward system.
RngRewardsNothingChance — Chance (0-100) of getting no RNG reward. Set to 0 to always give something.
RngRewards — List of weighted random rewards. Percentages are proportional — they don't need to add up to 100%.

Note: You can also set up ServiceRewardCommands to run additional commands only for specific voting sites. Set it to "ServiceRewardCommands": {} to disable.

Notifications

Show an on-screen notification when a player votes. Configure in notification.json.

notification.jsonJSON

{
  "Enabled": true,
  "TitleMessage": "<#e2b0ff>Vote Received!</#e2b0ff>",
  "TitleColor": "#e2b0ff",
  "DescriptionMessage": "<gray>Thanks for your vote on <#9f44d3>%from%</#9f44d3>!</gray>",
  "DescriptionColor": "#9f44d3",
  "IconItem": "Ingredient_Voidheart"
}

Enabled — Toggle notifications on or off.
TitleMessage — The primary notification text shown at the top.
DescriptionMessage — The secondary text shown below the title.
IconItem — Any Hytale item name to render as the notification icon.

Tip: TitleColor and DescriptionColor are legacy options. Since v1.3, you can use MiniMessage color tags directly in the message text instead. See Color Formatting.

Vote Reminders

Encourage daily voting by sending periodic reminders to players who haven't voted. Configure in voteReminder.json.

voteReminder.jsonJSON

{
  "Enabled": true,
  "SendOnJoin": true,
  "ExpireAfterHours": 24,
  "DelayInMinutes": 1,
  "Message": "<red><b>Heads Up!</b></red> <gray>You have not voted today! Do so with <green>'/vote'</green> to receive free rewards!</gray>",
  "Title": {
    "Enabled": true,
    "Title": "Reminder Title!",
    "SubTitle": "Don't forget to /vote for free rewards!",
    "DurationSeconds": 3,
    "FadeInSeconds": 0.5,
    "FadeOutSeconds": 0.5
  },
  "Notification": {
    "Enabled": true,
    "TitleMessage": "<#e2b0ff>Reminder Notification!</#e2b0ff>",
    "DescriptionMessage": "<gray>Don't forget to <#9f44d3>/vote</#9f44d3> for free rewards!</gray>",
    "IconItem": "Tool_Growth_Potion"
  },
  "Sound": {
    "Enabled": true,
    "Sound": "SFX_Player_Pickup_Item",
    "SoundCategory": "UI"
  }
}

SendOnJoin — Send a reminder immediately when a player joins if they haven't voted.
ExpireAfterHours — How long a vote stays valid before reminders start again.
DelayInMinutes — How often the reminder is sent to online players.
Title — Shows a title/subtitle at the top-center of the screen.
Notification — Shows an on-screen notification at the bottom-right.
Sound — Plays a sound with the reminder.

Vote Command & GUI

Customize the /vote command to open a GUI menu and/or send clickable links in chat. Configure in voteCommand.json.

voteCommand.jsonJSON

{
  "Enabled": true,
  "OpenCustomGui": true,
  "SendChatMessage": true,
  "ChatMessageHeader": [
    "<gray>----------------- <gold><b>Our Vote Links</b></gold> -----------------</gray>",
    "<white>Click on a vote link to open it in your browser."
  ],
  "ChatMessageFooter": [
    "<gray>----------------- <gold><b>Our Vote Links</b></gold> -----------------</gray>"
  ],
  "ChatMessageTemplate": "<gold>[<yellow>#%id%</yellow>]</gold> <yellow><click:%link%>%name% <b>(Click)</b></click></yellow>",
  "VoteLinks": {
    "Hytale Realm": "https://hytale-realm.com/vote/%player%"
  }
}

OpenCustomGui — Opens a fully configurable GUI menu when a player runs /vote.
SendChatMessage — Sends clickable vote links in chat.
VoteLinks — Map of display names to URLs. Use %player% to insert the player's name.
ChatMessageTemplate — Template for each link entry. Supports %id%, %link%, and %name%.

Offline Voting

Players who vote while offline can claim their rewards later with /claimvotes. Configure in offlineVoting.json.

offlineVoting.jsonJSON

{
  "Enabled": true,
  "MaxClaimAmount": 5,
  "ReminderMessage": "<green>You have <gold>%offlineVotes%</gold> offline vote(s) waiting! Use <yellow>/claimvotes</yellow> to claim them!",
  "MaxLifetimeHours": 48,
  "MessageNoOfflineVotes": "<red>You don't have any offline votes to claim!</red>",
  "MessageClaimSuccess": "<green>Successfully claimed <gold>%claimedVotes%</gold> vote(s)!</green>",
  "MessageRemainingVotes": "<gray>You still have <gold>%remainingVotes%</gold> offline vote(s) remaining. Use <yellow>/claimvotes</yellow> again to claim them!</gray>"
}

MaxClaimAmount — Maximum votes a player can claim in a single /claimvotes command.
MaxLifetimeHours — Hours before unclaimed offline votes expire and are removed.
ReminderMessage — Message shown on join if the player has pending offline votes.

Leaderboard & Milestones

Vote Leaderboard

Players can view the top 10 voters on your server with /votetop. Admins can manage the leaderboard with /votetopadmin to add, remove, set, or reset vote counts.

Vote Milestones

Reward players for reaching vote milestones. Configure tiers in voteMilestones.json. Players claim rewards with /votemilestone.

voteMilestones.json (excerpt)JSON

{
  "Enabled": true,
  "Milestones": [
    {
      "VoteRequirement": 5,
      "Commands": [
        "give %player% Food_Popcorn --quantity=10"
      ],
      "Messages": [
        "<green>You've reached 5 votes! Use /votemilestone to claim your reward!</green>"
      ]
    },
    {
      "VoteRequirement": 25,
      "Commands": [
        "give %player% Ore_Adamantite --quantity=3"
      ],
      "Messages": [
        "<gold>Amazing! 25 votes! Use /votemilestone to claim your reward!</gold>"
      ]
    }
  ]
}

Vote Forwarding

For server networks, vote forwarding lets one vote count on multiple servers. Configure in voteForwarding.json.

voteForwarding.jsonJSON

{
  "Enabled": true,
  "ForwardingSecret": "YourSecretHere",
  "SendToTargets": false,
  "ForwardingTargets": [
    {
      "Name": "Survival Server",
      "ForwardingSecret": "TargetSecret",
      "Address": "localhost",
      "Port": 8195
    }
  ]
}

ForwardingSecret — This instance's secret for receiving forwarded votes.
SendToTargets — When enabled, forwards all incoming votes to the listed targets.
ForwardingTargets — List of other HyVotifier instances to forward votes to.

Network Setup Tips

Each server needs its own unique port number
Only the main server's port needs to be public
Only connect voting websites to your main server's IP and port
The main server must be able to reach other servers' votifier ports internally

Commands

Command	Permission	Description
`/vote`	None	Opens vote GUI / shows clickable vote links
`/testvote <player>`	votifier.test	Simulates a vote to test your config
`/claimvotes`	None	Claim pending offline votes
`/votetop`/vt /vtop	None	View the top 10 voters leaderboard
`/votetopadmin`/vta	hyvotifier.leaderboard.admin	Add, remove, set, or reset player votes
`/votemilestone`/vm	None	View and claim vote milestones
`/votemilestoneadmin`/vmadmin	hyvotifier.milestones.admin	Manage milestone progress for players
`/plugin reload HSL:Votifier`	Admin	Reload the plugin without restarting

Color Formatting

Since v1.3, HyVotifier supports MiniMessage color formatting via TaleMessage. Use color tags in any message config field.

Available Color Tags

Examples

// Standard colors
<gray>Thanks for your vote on <gold>%from%</gold>. <green>Enjoy your rewards!</green>

// Hex colors
<#e2b0ff>Custom Purple Text</#e2b0ff>

// Gradient colors
<gradient:yellow:green:blue:purple>Rainbow Gradient!</gradient>

Firewall & Ports

Your votifier port must be open for TCP traffic so voting sites can send votes to your server. The default port is 8192.

Note: You can check if your port is open using a tool like ping.eu/port-chk. Enter your server IP and votifier port — if it says "closed", votes won't arrive.

Opening the Port

If you have terminal access to your server (VPS/dedicated), use one of these commands:

UFW (Ubuntu/Debian)

sudo ufw allow 8192/tcp

iptables

sudo iptables -A INPUT -p tcp --dport 8192 -j ACCEPT

If you're using a game hosting panel, check your firewall settings there or contact your host's support to request the port be opened.

Security

HyVotifier supports two Votifier protocols. The protocol used depends on the voting website.

V1 Protocol (RSA)

Uses RSA key pair encryption
Provide your rsa/public.key to the voting site
No token needed in config.json

V2 Protocol (HMAC)

Used by Hytale Realm

Uses HMAC token-based authentication
Add site's serviceName and token to Tokens in config.json
More secure than V1

Troubleshooting

Votes not arriving

Check your votifier port is open for TCP traffic using ping.eu/port-chk
Verify the token in your Server Toolbox matches config.json exactly
Enable "DebugMode": true in config.json and check logs
Make sure HyVotifier loaded — look for its startup message in console

Connection test shows "Connection refused"

Confirm your game server is running
Check that HyVotifier loaded (look for startup message in console)
Verify the port in config.json matches your Server Toolbox
Ask your hosting provider to open the port if needed

"Invalid signature" error

The token must match exactly — no extra spaces or line breaks
Make sure you're using the V2 token (not the RSA public key)
If you changed the token, reload with /plugin reload HSL:Votifier

Rewards not being given

Use /testvote <player> to verify your reward commands work
Check that command syntax is valid (e.g. give %player% Item --quantity=N)
If the player was offline, they need to use /claimvotes

Config errors after editing

JSON syntax errors will prevent the plugin from loading. Validate your config files at jsonlint.com before reloading.

Need Help?

Stuck on setup or have a question? Join our Discord community or get in touch.

Join our Discord Contact Us

HyVotifier is developed by ogfabio. Hytale Realm is not affiliated with Hypixel Studios.